diff --git a/.agents/plugins/agent-native-design/.codex-plugin/plugin.json b/.agents/plugins/agent-native-design/.codex-plugin/plugin.json
index ae0aab86ce..80191bbafd 100644
--- a/.agents/plugins/agent-native-design/.codex-plugin/plugin.json
+++ b/.agents/plugins/agent-native-design/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-native-design",
-  "version": "1.0.0+codex.e5519282396d",
+  "version": "1.0.0+codex.66dbb8d10905",
   "description": "Explore, compare, iterate, and export interactive UI design prototypes from the Design app.",
   "author": { "name": "Agent-Native", "url": "https://agent-native.com" },
   "homepage": "https://design.agent-native.com",
diff --git a/.agents/plugins/agent-native-design/skills/visual-edit/SKILL.md b/.agents/plugins/agent-native-design/skills/visual-edit/SKILL.md
index 79437cb8f0..9f2875e166 100644
--- a/.agents/plugins/agent-native-design/skills/visual-edit/SKILL.md
+++ b/.agents/plugins/agent-native-design/skills/visual-edit/SKILL.md
@@ -205,6 +205,20 @@ replace them with copied `srcdoc` HTML unless the user explicitly asks for a
 frozen snapshot. To change a state, rerun `add-localhost-screens` with the new
 path/query or duplicate the screen and update the copy's URL metadata.
 
+## React Source Writeback
+
+- Use compiler/debug provenance (project-relative file, line, column,
+  component, and runtime multiplicity) to locate React/TSX source. Treat it as
+  evidence, not as permission for a generic AST structural transform.
+- Reparenting, grouping/ungrouping, wrappers, dynamic expressions, repeated
+  `.map()` instances, shared components, and cross-file changes go through the
+  coding agent with exact subject/target anchors and their runtime
+  relationship.
+- Before each write, read the file and pass its exact `versionHash` to
+  `write-local-file` with `requireExpectedVersionHash: true`; on conflict,
+  re-read and re-plan. Keep the optimistic preview until HMR/runtime confirms
+  the result. Human write consent remains mandatory and agents cannot grant it.
+
 ## Verification
 
 - `list-localhost-connections` returns the expected connection and routes.
diff --git a/.changeset/bright-local-react-previews.md b/.changeset/bright-local-react-previews.md
new file mode 100644
index 0000000000..c62324c702
--- /dev/null
+++ b/.changeset/bright-local-react-previews.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Keep local React visual-edit previews hydrated by preserving Vite request metadata and response lengths through the bridge, and recover exact development source locations from React jsxDEV Fiber stacks.
diff --git a/.changeset/calm-content-flushes.md b/.changeset/calm-content-flushes.md
new file mode 100644
index 0000000000..105e98f370
--- /dev/null
+++ b/.changeset/calm-content-flushes.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Expose strict active-collaboration awareness reads so safety-critical sync flows can distinguish no open editor from presence-storage failures.
diff --git a/.changeset/confirmed-local-chat-delivery.md b/.changeset/confirmed-local-chat-delivery.md
new file mode 100644
index 0000000000..24773f3ea5
--- /dev/null
+++ b/.changeset/confirmed-local-chat-delivery.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Add cancellation-safe `sendToAgentChatAndConfirm` delivery confirmation and its submit-result event contract so callers can preserve user work when a local chat message is rejected or times out, without allowing that timed-out message to arrive later.
diff --git a/.changeset/f3b-fig-binary-builder-index.md b/.changeset/f3b-fig-binary-builder-index.md
new file mode 100644
index 0000000000..e3b00aa99b
--- /dev/null
+++ b/.changeset/f3b-fig-binary-builder-index.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Fix `.fig` and other binary files silently corrupting when uploaded through `index-design-system-with-builder`: `buildBuilderDesignSystemIndexFiles` always UTF-8-encoded file content even though `mimeTypeForBuilderDesignSystemFilename` already recognized `.fig` as binary (`application/octet-stream`). Add an optional per-file `encoding: "utf8" | "base64"` (defaults to `utf8`, unchanged for existing text-file callers) so binary files can be base64-encoded by the caller and decoded byte-exact here.
diff --git a/.changeset/fresh-authoritative-reverts.md b/.changeset/fresh-authoritative-reverts.md
new file mode 100644
index 0000000000..26636bc6d5
--- /dev/null
+++ b/.changeset/fresh-authoritative-reverts.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Prevent pre-seed collaborative editor updates from reaching autosave, and allow newer authoritative restores to reapply content previously emitted during mount while retaining stale-echo protection during active typing.
diff --git a/.changeset/guard-recap-ssr-failures.md b/.changeset/guard-recap-ssr-failures.md
new file mode 100644
index 0000000000..1a9b94bbe3
--- /dev/null
+++ b/.changeset/guard-recap-ssr-failures.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Prevent PR recap workflows from publishing screenshots of failed recap pages, and report SSR render failures through configured error monitoring.
diff --git a/.changeset/loop-protection-background-continuation.md b/.changeset/loop-protection-background-continuation.md
new file mode 100644
index 0000000000..66fd126101
--- /dev/null
+++ b/.changeset/loop-protection-background-continuation.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Fix long agent-chat turns dying with a Netlify "508 Loop Detected" error after several server-driven continuation chunks: nested self-dispatch chains now break proactively before the platform's undocumented loop-protection limit, and a 508 that does occur is classified distinctly and deferred to the existing unclaimed-run sweep for recovery instead of failing the turn outright.
diff --git a/.changeset/lost-turns-recover-lost-handoffs.md b/.changeset/lost-turns-recover-lost-handoffs.md
new file mode 100644
index 0000000000..1ec366d2be
--- /dev/null
+++ b/.changeset/lost-turns-recover-lost-handoffs.md
@@ -0,0 +1,7 @@
+---
+"@agent-native/core": patch
+---
+
+Recover background chat turns whose continuation handoff dispatch failed instead of failing them immediately: the pre-inserted successor run is left claimable so the unclaimed-run sweep can redispatch it (and the client poll defers to that sweep within a bound), backed by a backstop that still fails loud if the handoff never lands.
+
+Operational note — terminal-reason change: when a continuation handoff exhausts its dispatch retry budget but the successor row exists, the run's `terminal_reason` is now `background_continuation_dispatch_deferred` (recoverable, awaiting sweep redispatch) instead of `background_continuation_dispatch_failed`. The old `background_continuation_dispatch_failed` reason is still emitted, but now only in the narrower case where the successor row itself could not be pre-inserted. Any dashboards, alerts, or audit queries matching `background_continuation_dispatch_failed` should add `background_continuation_dispatch_deferred` to keep covering this failure class.
diff --git a/.changeset/plenty-cobras-cursor.md b/.changeset/plenty-cobras-cursor.md
new file mode 100644
index 0000000000..8caffcc6e7
--- /dev/null
+++ b/.changeset/plenty-cobras-cursor.md
@@ -0,0 +1,7 @@
+---
+"@agent-native/core": patch
+---
+
+Fix an awareness "storm" in `useCollaborativeDoc`: the shared collab connection's fast awareness-push path re-broadcast a client's own (unchanged) presence state whenever ANY remote participant's awareness changed, not just when the local user actually moved their cursor or updated their presence. With several people collaborating on the same document, every peer's cursor move caused every other connected client to also re-POST its own state, multiplying awareness traffic roughly quadratically with participant count. The fast-push listener now only fires on locally-originated awareness changes (`origin === "local"`), matching the equivalent guard already present in `usePresence`.
+
+Also add a defensive size cap to the collab `recentEdits` ring (`appendRecentEdit`): descriptor strings (`quote`, `selector`, path entries) and the edit `label` are now truncated to 500 characters. The ring was already bounded in length, but an app forgetting to trim its own excerpt before publishing (e.g. passing a whole paragraph or document as `quote`) could otherwise push an oversized payload through the awareness fast-path broadcast and into the `_collab_awareness` SQL mirror.
diff --git a/.changeset/rare-bridges-reconnect.md b/.changeset/rare-bridges-reconnect.md
new file mode 100644
index 0000000000..5466710563
--- /dev/null
+++ b/.changeset/rare-bridges-reconnect.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Give the Design localhost bridge a per-boot `bridgeInstanceId`, exposed on `/health`, the `/live-edit-bridge` registration response, and the `/live-edit` "unknown bridge key" 409 (now carrying a machine-readable `code: "unknown-bridge-key"` and the echoed `bridgeKey`). This lets a client distinguish a bridge process restart — which silently empties the in-memory live-edit bridge script registry — from a genuine registration bug, instead of guessing from free-text error strings.
diff --git a/.changeset/silly-slots-sanitize.md b/.changeset/silly-slots-sanitize.md
new file mode 100644
index 0000000000..712c2be3a6
--- /dev/null
+++ b/.changeset/silly-slots-sanitize.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Fix a recurring `DataCloneError` console error when any embedded extension (Design's Tools/Extensions panel, or any other app using `EmbeddedExtension`) loads or its slot context updates. Slot contexts commonly carry live callback functions the host uses internally; `postMessage`'s structured clone algorithm throws on function-valued properties, so the context update silently never reached the extension iframe. Sanitize the context through a JSON round-trip (dropping functions) before posting it.
diff --git a/.changeset/strong-local-source-writes.md b/.changeset/strong-local-source-writes.md
new file mode 100644
index 0000000000..5da38394ca
--- /dev/null
+++ b/.changeset/strong-local-source-writes.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Harden local Design source writes with SHA-256 version checks, per-file serialization, atomic replacement, and repeated symlink containment validation.
diff --git a/.claude/launch.json b/.claude/launch.json
index 3f86893f46..fba58050ef 100644
--- a/.claude/launch.json
+++ b/.claude/launch.json
@@ -91,6 +91,22 @@
         "3104"
       ],
       "port": 3104
+    },
+    {
+      "name": "slides",
+      "runtimeExecutable": "env",
+      "runtimeArgs": [
+        "DATABASE_URL=file:/private/tmp/claude-501/-Users-steve-Projects-builder-agent-native-framework/726cb1e5-ab5f-4658-b340-e7877455395b/scratchpad/slides-verify.sqlite",
+        "PORT=3106",
+        "AUTH_MODE=local",
+        "pnpm",
+        "--dir",
+        "templates/slides",
+        "dev",
+        "--port",
+        "3106"
+      ],
+      "port": 3106
     }
   ]
 }
diff --git a/.gitignore b/.gitignore
index f7e1992181..0b706601a5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -73,6 +73,7 @@ test-results/
 e2e/.auth/
 **/.auth/
 **/.auth-debug/
+**/.auth-*/
 
 # Wrangler local state
 .wrangler
diff --git a/packages/core/src/agent/production-agent.chain-continuation.spec.ts b/packages/core/src/agent/production-agent.chain-continuation.spec.ts
index 16c61e29df..4c314c2841 100644
--- a/packages/core/src/agent/production-agent.chain-continuation.spec.ts
+++ b/packages/core/src/agent/production-agent.chain-continuation.spec.ts
@@ -6,7 +6,9 @@ import {
 } from "./durable-background.js";
 import {
   chainServerDrivenContinuation,
+  isLoopProtectionDispatchError,
   MAX_BACKGROUND_RUN_CONTINUATIONS,
+  MAX_NESTED_SELF_DISPATCH_DEPTH,
   resolveContinuationDispatchBudget,
   type ChainServerDrivenContinuationDeps,
 } from "./production-agent.js";
@@ -131,11 +133,13 @@ async function runChain(
     chainViaDurableBackground?: boolean;
     workerProvenInBackgroundFunction?: boolean;
     requestBody?: Record<string, unknown>;
+    backgroundContinuationCount?: number;
+    run?: ActiveRun;
   },
 ): Promise<void> {
   await chainServerDrivenContinuation({
     event: {},
-    run: timeoutBoundaryRun(),
+    run: opts?.run ?? timeoutBoundaryRun(),
     effectiveThreadId: "thread-1",
     effectiveTurnId: "turn-1",
     requestBody: opts?.requestBody ?? {
@@ -144,7 +148,7 @@ async function runChain(
       threadId: "thread-1",
       [AGENT_CHAT_BACKGROUND_RUN_FIELD]: { runId: "run-chunk0" },
     },
-    backgroundContinuationCount: 0,
+    backgroundContinuationCount: opts?.backgroundContinuationCount ?? 0,
     chainViaDurableBackground: opts?.chainViaDurableBackground ?? false,
     workerProvenInBackgroundFunction: opts?.workerProvenInBackgroundFunction,
     deps: harness.deps,
@@ -256,45 +260,81 @@ describe("chainServerDrivenContinuation — transactional handoff (foreground se
     expect(h.deps.updateRunStatusIfRunning).not.toHaveBeenCalled();
   });
 
-  it("fails LOUD when every attempt dies: successor + chunk errored, diag stage recorded — never silent", async () => {
+  it("DEFERS (never errors) the pre-inserted successor when every attempt dies — the unclaimed-run sweep gets a chance to recover it", async () => {
     const dispatchMock = vi.fn().mockRejectedValue(new Error("dispatch down"));
     const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
     await runChain(h);
 
     // Foreground path: 2 attempts (initial + one retry).
     expect(dispatchMock).toHaveBeenCalledTimes(2);
-    // The pre-inserted successor is errored immediately (not left for the
-    // sweep) with a truthful terminal reason…
-    expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledWith(
+    // The pre-inserted successor is LEFT ALONE — still status='running',
+    // dispatch_mode='background', dispatch_payload intact — so the
+    // unclaimed-background-run sweep (agent-chat-plugin.ts) can redispatch
+    // it. It is never marked errored from this path.
+    expect(h.deps.updateRunStatusIfRunning).not.toHaveBeenCalledWith(
       "run-next",
       "errored",
     );
-    expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
+    expect(h.deps.setRunTerminalReason).not.toHaveBeenCalledWith(
       "run-next",
-      "background_continuation_dispatch_failed",
+      expect.any(String),
+    );
+    // The successor's diag stage records WHY it was left for the sweep (the
+    // only forensics channel — bg logs are unreadable).
+    expect(h.deps.recordRunDiagnostic).toHaveBeenCalledWith(
+      "run-next",
+      RUN_DIAG_STAGE.workerThrew,
+      expect.stringContaining("chain_dispatch_deferred"),
     );
-    // …and the finished chunk is errored too, with the failure written as its
-    // diag stage (the only forensics channel — bg logs are unreadable).
+    // …the finished chunk DOES go terminal — its own soft-timeout budget is
+    // genuinely spent — but with the distinct, honest "deferred" reason: the
+    // TURN is not dead, only this handoff attempt was.
     expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledWith(
       "run-chunk0",
       "errored",
     );
     expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
       "run-chunk0",
-      "background_continuation_dispatch_failed",
+      "background_continuation_dispatch_deferred",
     );
     expect(h.deps.recordRunDiagnostic).toHaveBeenCalledWith(
       "run-chunk0",
       RUN_DIAG_STAGE.workerThrew,
-      expect.stringContaining("chain_dispatch_failed"),
+      expect.stringContaining("chain_dispatch_deferred"),
     );
     // The chunk is NOT marked as a clean continuation boundary.
     expect(
       h.deps.markBackgroundContinuationChunkTerminal,
     ).not.toHaveBeenCalled();
-    // With both rows terminal, the thread slot is free — the client's
+    // With this chunk terminal, the thread slot is free — the client's
     // existing auto_continue re-POST (it still receives the terminal event)
-    // takes over as the fallback. See run-store.foreground-self-chain.spec.
+    // is a second, faster fallback alongside the sweep. See
+    // run-store.foreground-self-chain.spec.
+  });
+
+  it("still fails LOUD immediately when the pre-insert itself failed — nothing exists for a sweep to recover", async () => {
+    const dispatchMock = vi.fn().mockRejectedValue(new Error("dispatch down"));
+    const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
+    (h.deps.insertRun as any).mockRejectedValueOnce(new Error("insert failed"));
+    await runChain(h);
+
+    // No successor row was ever created, so there is nothing to defer to a
+    // sweep — this is genuinely unrecoverable and must fail loud immediately,
+    // same as before this change.
+    expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledTimes(1);
+    expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledWith(
+      "run-chunk0",
+      "errored",
+    );
+    expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
+      "run-chunk0",
+      "background_continuation_dispatch_failed",
+    );
+    expect(h.deps.recordRunDiagnostic).toHaveBeenCalledWith(
+      "run-chunk0",
+      RUN_DIAG_STAGE.workerThrew,
+      expect.stringContaining("chain_dispatch_failed"),
+    );
   });
 
   it("refuses to chain when the SQL per-turn run budget is exhausted (cross-chain loop killer)", async () => {
@@ -379,7 +419,7 @@ describe("resolveContinuationDispatchBudget — retry budget matrix", () => {
 });
 
 describe("chainServerDrivenContinuation — worker proven in background function gets the widened budget", () => {
-  it("retries up to 5 times at a 15s response timeout, using the capped backoff schedule, before failing loud", async () => {
+  it("retries up to 5 times at a 15s response timeout, using the capped backoff schedule, before deferring to the sweep", async () => {
     const dispatchMock = vi.fn().mockRejectedValue(new Error("fetch failed"));
     const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
     await runChain(h, {
@@ -398,10 +438,12 @@ describe("chainServerDrivenContinuation — worker proven in background function
     );
     expect(sleepCalls).toEqual([500, 1000, 2000, 4000]);
     // Dispatch still targets the regular `_process-run` route (unchanged
-    // target — only the budget widened), and both rows go terminal loudly
-    // on final exhaustion, same as the foreground exhaustion path.
+    // target — only the budget widened). This is exactly the case the
+    // recovery was built for: a background-function worker with NO
+    // connected-client fallback — the pre-inserted successor is left for the
+    // sweep instead of being errored immediately.
     expect(dispatch.path).toBe(AGENT_CHAT_PROCESS_RUN_PATH);
-    expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledWith(
+    expect(h.deps.updateRunStatusIfRunning).not.toHaveBeenCalledWith(
       "run-next",
       "errored",
     );
@@ -411,7 +453,7 @@ describe("chainServerDrivenContinuation — worker proven in background function
     );
     expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
       "run-chunk0",
-      "background_continuation_dispatch_failed",
+      "background_continuation_dispatch_deferred",
     );
   });
 });
@@ -439,9 +481,216 @@ describe("chainServerDrivenContinuation — durable-background path unchanged",
     // A Netlify background fn 202s on enqueue, so a failed await IS a dead
     // handoff — the claim-check shortcut is foreground-only.
     expect(readClaim).not.toHaveBeenCalled();
+    // This chunk still goes terminal loudly, but the recoverable-vs-fatal
+    // split applies uniformly regardless of dispatch target: the pre-inserted
+    // successor row exists in SQL either way, so it is left for the sweep
+    // instead of being errored immediately.
+    expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledWith(
+      "run-chunk0",
+      "errored",
+    );
+    expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
+      "run-chunk0",
+      "background_continuation_dispatch_deferred",
+    );
+    expect(h.deps.updateRunStatusIfRunning).not.toHaveBeenCalledWith(
+      "run-next",
+      "errored",
+    );
+  });
+});
+
+describe("isLoopProtectionDispatchError — classifies Netlify's undocumented loop-protection response", () => {
+  it("matches the exact message self-dispatch.ts's dispatchResponseError constructs for a 508", () => {
+    expect(
+      isLoopProtectionDispatchError(
+        new Error(
+          "Self-dispatch to /_agent-native/agent-chat/_process-run returned HTTP 508 Loop Detected",
+        ),
+      ),
+    ).toBe(true);
+  });
+
+  it("does not match a generic transient dispatch failure", () => {
+    expect(isLoopProtectionDispatchError(new Error("fetch failed"))).toBe(
+      false,
+    );
+    expect(
+      isLoopProtectionDispatchError(
+        new Error(
+          "Self-dispatch to /_agent-native/agent-chat/_process-run returned HTTP 503 Service Unavailable",
+        ),
+      ),
+    ).toBe(false);
+  });
+
+  it("does not match a non-Error value", () => {
+    expect(isLoopProtectionDispatchError("HTTP 508")).toBe(false);
+    expect(isLoopProtectionDispatchError(undefined)).toBe(false);
+  });
+});
+
+describe("chainServerDrivenContinuation — Netlify loop-protection 508 is classified and DEFERRED, not fatally errored", () => {
+  it("stops retrying immediately on a 508 instead of burning the full dispatch budget — distinct from a generic 'fetch failed'", async () => {
+    const dispatchMock = vi
+      .fn()
+      .mockRejectedValue(
+        new Error(
+          "Self-dispatch to /_agent-native/agent-chat/_process-run returned HTTP 508 Loop Detected",
+        ),
+      );
+    const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
+    await runChain(h);
+
+    // The foreground budget allows 2 attempts, but a 508 is a property of
+    // this same nested call chain — retrying it will not help, so the loop
+    // stops after the FIRST attempt instead of exhausting the budget.
+    expect(dispatchMock).toHaveBeenCalledTimes(1);
+
+    // Still deferred — never the fatal `background_continuation_dispatch_failed`.
+    expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledWith(
+      "run-chunk0",
+      "errored",
+    );
+    expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
+      "run-chunk0",
+      "background_continuation_dispatch_deferred",
+    );
+    expect(h.deps.setRunTerminalReason).not.toHaveBeenCalledWith(
+      "run-chunk0",
+      "background_continuation_dispatch_failed",
+    );
+    // The successor row itself is left alone for the sweep — never errored.
+    expect(h.deps.updateRunStatusIfRunning).not.toHaveBeenCalledWith(
+      "run-next",
+      "errored",
+    );
+    // Distinctly classified in the diagnostics — greppable apart from a
+    // generic "dispatch_budget_exhausted" deferral.
+    expect(h.deps.recordRunDiagnostic).toHaveBeenCalledWith(
+      "run-chunk0",
+      RUN_DIAG_STAGE.workerThrew,
+      expect.stringContaining(
+        "chain_dispatch_deferred[netlify_loop_protection]",
+      ),
+    );
+  });
+
+  it("still burns the full retry budget for a generic transient error (unchanged behavior)", async () => {
+    const dispatchMock = vi.fn().mockRejectedValue(new Error("fetch failed"));
+    const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
+    await runChain(h);
+
+    expect(dispatchMock).toHaveBeenCalledTimes(2);
+    expect(h.deps.recordRunDiagnostic).toHaveBeenCalledWith(
+      "run-chunk0",
+      RUN_DIAG_STAGE.workerThrew,
+      expect.stringContaining(
+        "chain_dispatch_deferred[dispatch_budget_exhausted]",
+      ),
+    );
+  });
+});
+
+describe("chainServerDrivenContinuation — proactive nested-dispatch depth cap", () => {
+  it("defers WITHOUT ever attempting a dispatch once backgroundContinuationCount reaches MAX_NESTED_SELF_DISPATCH_DEPTH", async () => {
+    const dispatchMock = vi.fn().mockResolvedValue(undefined);
+    const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
+    await runChain(h, {
+      backgroundContinuationCount: MAX_NESTED_SELF_DISPATCH_DEPTH,
+    });
+
+    // No nested self-dispatch was even attempted — avoided the doomed call
+    // entirely instead of reacting to it after the fact.
+    expect(dispatchMock).not.toHaveBeenCalled();
+    // The successor row was still pre-inserted (so the sweep has something to
+    // find) and this chunk is deferred, exactly like an exhausted retry budget.
+    expect(h.deps.insertRun).toHaveBeenCalled();
+    expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledWith(
+      "run-chunk0",
+      "errored",
+    );
+    expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
+      "run-chunk0",
+      "background_continuation_dispatch_deferred",
+    );
+    expect(h.deps.recordRunDiagnostic).toHaveBeenCalledWith(
+      "run-chunk0",
+      RUN_DIAG_STAGE.workerThrew,
+      expect.stringContaining("chain_dispatch_deferred[proactive_depth_cap]"),
+    );
+  });
+
+  it("dispatches normally below the depth cap", async () => {
+    const dispatchMock = vi.fn().mockResolvedValue(undefined);
+    const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
+    await runChain(h, {
+      backgroundContinuationCount: MAX_NESTED_SELF_DISPATCH_DEPTH - 1,
+    });
+
+    expect(dispatchMock).toHaveBeenCalledTimes(1);
+    expect(h.deps.markBackgroundContinuationChunkTerminal).toHaveBeenCalled();
+    expect(h.deps.updateRunStatusIfRunning).not.toHaveBeenCalled();
+  });
+
+  it("applies the SAME depth cap regardless of continuation reason (run_timeout, loop_limit alike) — the cap is about nested self-dispatch mechanics, not turn behavior", async () => {
+    const loopLimitRun = makeRun([{ type: "loop_limit" }]);
+    const dispatchMock = vi.fn().mockResolvedValue(undefined);
+    const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
+    await runChain(h, {
+      backgroundContinuationCount: MAX_NESTED_SELF_DISPATCH_DEPTH,
+      run: loopLimitRun,
+    });
+
+    expect(dispatchMock).not.toHaveBeenCalled();
+    expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
+      "run-chunk0",
+      "background_continuation_dispatch_deferred",
+    );
+  });
+
+  it("applies uniformly on the durable-background dispatch target too (Background Functions do not escape Netlify's loop protection)", async () => {
+    process.env.NETLIFY = "true";
+    const dispatchMock = vi.fn().mockResolvedValue(undefined);
+    const h = makeHarness({ fireInternalDispatch: dispatchMock as any });
+    await runChain(h, {
+      chainViaDurableBackground: true,
+      backgroundContinuationCount: MAX_NESTED_SELF_DISPATCH_DEPTH,
+    });
+
+    expect(dispatchMock).not.toHaveBeenCalled();
+    expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
+      "run-chunk0",
+      "background_continuation_dispatch_deferred",
+    );
+  });
+});
+
+describe("chainServerDrivenContinuation — the intentional per-turn budget still caps a chain of deferred/redispatched segments", () => {
+  it("refuses to chain past the SQL per-turn ledger even when backgroundContinuationCount has been reset by sweep-mediated chain breaks", async () => {
+    // Simulates a turn that has already been through several sweep-mediated
+    // chain breaks (each resets backgroundContinuationCount to 0 — see the
+    // "Unclaimed background-run sweep" in agent-chat-plugin.ts) but has
+    // genuinely consumed far more runs than the intentional budget allows.
+    // The durable SQL ledger (countRunsForTurn), NOT the in-marker count, is
+    // what must catch this.
+    const h = makeHarness({
+      countRunsForTurn: vi.fn(
+        async () => MAX_BACKGROUND_RUN_CONTINUATIONS + 6,
+      ) as any,
+    });
+    const dispatchMock = h.deps.fireInternalDispatch as any;
+    await runChain(h, { backgroundContinuationCount: 0 });
+
+    expect(h.deps.insertRun).not.toHaveBeenCalled();
+    expect(dispatchMock).not.toHaveBeenCalled();
     expect(h.deps.updateRunStatusIfRunning).toHaveBeenCalledWith(
       "run-chunk0",
       "errored",
     );
+    expect(h.deps.setRunTerminalReason).toHaveBeenCalledWith(
+      "run-chunk0",
+      "turn_continuation_budget_exhausted",
+    );
   });
 });
diff --git a/packages/core/src/agent/production-agent.ts b/packages/core/src/agent/production-agent.ts
index d4580aa17c..3ed65d8f7e 100644
--- a/packages/core/src/agent/production-agent.ts
+++ b/packages/core/src/agent/production-agent.ts
@@ -5038,6 +5038,70 @@ export function resolveContinuationDispatchBudget(opts: {
   };
 }
 
+/**
+ * True when a `fireInternalDispatch` failure is Netlify's Functions platform
+ * loop-protection response (`HTTP 508 Loop Detected`), matched against the
+ * exact message `self-dispatch.ts`'s `dispatchResponseError` constructs
+ * (`Self-dispatch to ${path} returned HTTP ${res.status} ${res.statusText}...`).
+ * Matches on the status code alone (not the reason phrase text) so it is
+ * robust to any wording Netlify's edge puts in `statusText`.
+ *
+ * VERIFIED: production `agent_runs` diagnostics show exactly this failure mode
+ * — 8 successful `chain_dispatch_sent` self-dispatches followed by a 9th/10th
+ * that dies with `HTTP 508 Loop Detected`, terminal reason
+ * `background_continuation_dispatch_failed`. UNVERIFIED (Netlify does not
+ * document the mechanism — checked the Functions overview, Functions API
+ * reference, Background Functions overview, Status Codes reference, and
+ * Request Chain troubleshooting docs, none mention it): the ONLY public
+ * confirmation is a Netlify staff forum reply — "we prevent multiple
+ * executions after one-another as that's a 'loop' ... I believe we enforce
+ * this after 9 or 10 self-invocations"
+ * (https://answers.netlify.com/t/self-invoke-background-function-via-post-requests/146012)
+ * — which also confirms Background Functions do NOT escape the limit (the
+ * reporter's case was already a `-background` function self-invoking). See
+ * `MAX_NESTED_SELF_DISPATCH_DEPTH` for how this classification is used.
+ */
+export function isLoopProtectionDispatchError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  return /\bHTTP\s*508\b/i.test(err.message);
+}
+
+/**
+ * Conservative safety margin on NESTED self-dispatch chaining — a
+ * continuation dispatched directly from within the live invocation that is
+ * about to finish, as opposed to being picked up later by the
+ * unclaimed-background-run sweep (`agent-chat-plugin.ts`), which fires its
+ * redispatch from an unrelated, timer-driven invocation rather than from
+ * inside the chain's own execution.
+ *
+ * Netlify's loop-protection ceiling is undocumented and platform-reported
+ * only approximately ("I believe... 9 or 10" — see
+ * `isLoopProtectionDispatchError`), so hard-coding that exact number here
+ * would be pinning behavior to a number Netlify itself won't commit to, and
+ * production evidence shows it can trigger by the 9th self-dispatch. Rather
+ * than only reacting after triggering that undocumented limit,
+ * `chainServerDrivenContinuation` proactively hands a chunk to the sweep once
+ * `backgroundContinuationCount` (nested hops since the last chain break)
+ * reaches this value — comfortably below the observed ~9-10 failure point —
+ * instead of attempting another nested dispatch. This is the SAME deferred-
+ * recovery path already used when a dispatch fails outright: the row is left
+ * `status='running', dispatch_mode='background'` for the sweep to redispatch,
+ * never silently dropped.
+ *
+ * The sweep's redispatch marker intentionally omits `continuationCount` (see
+ * the "Unclaimed background-run sweep" in `agent-chat-plugin.ts`), so a
+ * sweep-recovered chunk's own `backgroundContinuationCount` resets to 0 —
+ * this constant therefore bounds each NESTED segment between chain breaks,
+ * not the whole turn. The TRUE ceiling on total turn length is unaffected by
+ * that reset: it is the durable per-turn SQL ledger (`countRunsForTurn`,
+ * checked above in this function) plus `MAX_BACKGROUND_RUN_CONTINUATIONS` —
+ * both counted independently of this in-marker value — so a legitimately
+ * long turn keeps making progress in bounded nested segments, each recovered
+ * by the sweep, until it genuinely exhausts the intentional overall budget
+ * and fails loud with `turn_continuation_budget_exhausted`.
+ */
+export const MAX_NESTED_SELF_DISPATCH_DEPTH = 6;
+
 /**
  * Server-driven continuation handoff for a chunk that hit its soft-timeout
  * boundary still unfinished: mint the next chunk's runId, PRE-INSERT its run
@@ -5046,12 +5110,26 @@ export function resolveContinuationDispatchBudget(opts: {
  * `_process-run` self-dispatch carrying ids only (the body is persisted on
  * the row as `dispatch_payload`), fully AWAIT the dispatch acknowledgment
  * with retries, and mark this chunk terminal only after the handoff landed.
- * On failure every path is loud: the successor row is errored, the failure
- * is recorded as the run's diag stage, and this chunk is flipped to errored
- * with a terminal reason — never a silent loss. (For a FOREGROUND self-chain
- * the client additionally still receives the terminal `auto_continue` event
- * — run-manager emits it after this callback — so the existing client
- * re-POST path takes over as the fallback.)
+ * On failure this chunk always goes terminal loudly (diag stage + terminal
+ * reason recorded — never a silent loss), but the successor row's fate
+ * depends on WHY the dispatch failed:
+ *   - the pre-insert itself failed (no successor row exists) — nothing for a
+ *     sweep to find, so this is unrecoverable: fail loud immediately with
+ *     `background_continuation_dispatch_failed`.
+ *   - every dispatch attempt failed but the successor row DOES exist with its
+ *     `dispatch_payload` intact — this is RECOVERABLE: the row is left alone
+ *     (`status='running', dispatch_mode='background'`) instead of being
+ *     errored, so the unclaimed-background-run sweep in `agent-chat-plugin.ts`
+ *     can redispatch it once `UNCLAIMED_BACKGROUND_RUN_GRACE_MS` has passed.
+ *     This chunk is flipped to errored with the distinct, honest
+ *     `background_continuation_dispatch_deferred` reason — the TURN is
+ *     deferred, not dead. The sweep still bounds this by
+ *     `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS`: past that it falls back
+ *     to the existing loud reap, so a genuinely dead handoff never hangs
+ *     silently forever. (For a FOREGROUND self-chain the client additionally
+ *     still receives the terminal `auto_continue` event — run-manager emits
+ *     it after this callback — so the existing client re-POST path is a
+ *     second, faster fallback alongside the sweep.)
  *
  * `chainViaDurableBackground` selects the dispatch target:
  *   - true  → the durable-background worker chain (unchanged behavior): the
@@ -5244,9 +5322,23 @@ export async function chainServerDrivenContinuation(opts: {
         };
     let dispatched = false;
     let lastDispatchErr: unknown;
+    // Proactive nested-chain safety margin — see `MAX_NESTED_SELF_DISPATCH_DEPTH`.
+    // Skip the nested dispatch attempt entirely once this segment's hop count
+    // reaches the cap; a nested attempt at this depth is expected to trip
+    // Netlify's loop protection, so there is nothing to gain by trying it and
+    // burning this worker's remaining wall clock on a doomed call. Falls
+    // straight into the same deferred-recovery path below as an exhausted
+    // retry budget.
+    const nestedDepthExceeded =
+      opts.backgroundContinuationCount >= MAX_NESTED_SELF_DISPATCH_DEPTH;
+    if (nestedDepthExceeded) {
+      lastDispatchErr = new Error(
+        `proactive nested-dispatch depth cap reached (backgroundContinuationCount=${opts.backgroundContinuationCount} >= MAX_NESTED_SELF_DISPATCH_DEPTH=${MAX_NESTED_SELF_DISPATCH_DEPTH}) — deferring to the unclaimed-background-run sweep instead of risking Netlify loop protection`,
+      );
+    }
     for (
       let attempt = 0;
-      attempt < maxDispatchAttempts && !dispatched;
+      !nestedDepthExceeded && attempt < maxDispatchAttempts && !dispatched;
       attempt++
     ) {
       try {
@@ -5313,25 +5405,99 @@ export async function chainServerDrivenContinuation(opts: {
           `[agent-chat] background continuation dispatch attempt ${attempt + 1} failed:`,
           dispatchErr instanceof Error ? dispatchErr.message : dispatchErr,
         );
+        // Netlify loop protection (see `isLoopProtectionDispatchError`) is a
+        // property of this same live, nested call chain — retrying the exact
+        // same nested self-dispatch within the next few seconds will not
+        // change that, so further attempts are a guaranteed-doomed use of
+        // this worker's remaining wall clock. Stop immediately (instead of
+        // burning the full `maxDispatchAttempts` budget) and fall into the
+        // same deferred-recovery path below, which hands the successor to the
+        // sweep — a genuinely different, non-nested invocation.
+        if (isLoopProtectionDispatchError(dispatchErr)) {
+          break;
+        }
       }
     }
     if (!dispatched) {
-      // The pre-inserted successor row would otherwise sit unclaimed until
-      // the sweep reaps it — error it now so the failure is immediate and
-      // truthful.
       if (nextRowInserted) {
-        const nextStatusUpdated = await d
-          .updateRunStatusIfRunning(nextRunId, "errored")
+        // Classify WHY this handoff is being deferred — distinct, greppable
+        // tags so production diagnostics (which is all that is readable from
+        // a background worker) can tell "we proactively avoided Netlify loop
+        // protection", "we hit loop protection and stopped retrying", and "a
+        // generic transient dispatch failure exhausted its retry budget"
+        // apart, instead of lumping every deferred handoff into one bucket.
+        const deferralClassification = nestedDepthExceeded
+          ? "proactive_depth_cap"
+          : isLoopProtectionDispatchError(lastDispatchErr)
+            ? "netlify_loop_protection"
+            : "dispatch_budget_exhausted";
+        // RECOVERABLE: the successor row already exists in SQL with its
+        // rehydration payload (`dispatch_payload`) intact and is still
+        // `status='running', dispatch_mode='background'` — exactly the state
+        // the unclaimed-background-run sweep (`agent-chat-plugin.ts`) already
+        // scans for. Do NOT error it here: leave it alone so the sweep can
+        // redispatch it once `UNCLAIMED_BACKGROUND_RUN_GRACE_MS` has passed,
+        // bounded by `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS` before it
+        // falls back to the existing loud reap
+        // (`background_worker_never_started`) — so this is deferred, never a
+        // silent hang. This chunk still goes terminal (its own soft-timeout
+        // budget is genuinely spent), but with an honest reason: the TURN is
+        // not dead, only this handoff attempt was.
+        //
+        // THREE-SITE INVARIANT (keep in lockstep — a future reader must not
+        // "fix" one without the others): this deferral only survives because
+        // the ~1s client poll in `getActiveRunForThreadAsync`
+        // (run-manager.ts) ALSO skips `reapUnclaimedBackgroundRun` while the
+        // successor is within `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS`
+        // (via `shouldRedispatchUnclaimedBackgroundRun`). Without that guard a
+        // connected client would reap this row at the 25s grace, before the
+        // ~2-min sweep, defeating the deferral. The sweep in agent-chat-plugin
+        // is the recovery actor; run-manager is the guard; this is the
+        // producer.
+        await d
+          .recordRunDiagnostic(
+            nextRunId,
+            RUN_DIAG_STAGE.workerThrew,
+            `chain_dispatch_deferred[${deferralClassification}]: dispatch budget exhausted (${maxDispatchAttempts} attempts) awaiting unclaimed-run sweep redispatch; ${
+              lastDispatchErr instanceof Error
+                ? lastDispatchErr.message
+                : String(lastDispatchErr)
+            }`,
+          )
+          .catch(() => {});
+        await d
+          .recordRunDiagnostic(
+            runId,
+            RUN_DIAG_STAGE.workerThrew,
+            `chain_dispatch_deferred[${deferralClassification}] nextRunId=${nextRunId} ${
+              lastDispatchErr instanceof Error
+                ? lastDispatchErr.message
+                : String(lastDispatchErr)
+            }`,
+          )
+          .catch(() => {});
+        console.error(
+          `[agent-chat] background continuation dispatch deferred (${deferralClassification}); leaving the pre-inserted successor for the unclaimed-run sweep to redispatch:`,
+          lastDispatchErr instanceof Error
+            ? lastDispatchErr.message
+            : lastDispatchErr,
+        );
+        const statusUpdated = await d
+          .updateRunStatusIfRunning(runId, "errored")
           .catch(() => false);
-        if (nextStatusUpdated) {
+        if (statusUpdated) {
           await d
             .setRunTerminalReason(
-              nextRunId,
-              "background_continuation_dispatch_failed",
+              runId,
+              "background_continuation_dispatch_deferred",
             )
             .catch(() => {});
         }
+        return;
       }
+      // No successor row exists at all (the pre-insert itself failed) — there
+      // is nothing for the sweep to find and recover, so this really is
+      // fatal. Fail loud immediately via the shared catch block below.
       throw lastDispatchErr instanceof Error
         ? lastDispatchErr
         : new Error(String(lastDispatchErr));
diff --git a/packages/core/src/agent/run-manager.spec.ts b/packages/core/src/agent/run-manager.spec.ts
index 65aace4317..d4864cf394 100644
--- a/packages/core/src/agent/run-manager.spec.ts
+++ b/packages/core/src/agent/run-manager.spec.ts
@@ -24,6 +24,13 @@ vi.mock("./run-store.js", () => ({
   bumpRunProgress: vi.fn(() => Promise.resolve()),
   reapIfStale: vi.fn(() => Promise.resolve(null)),
   reapUnclaimedBackgroundRun: vi.fn(() => Promise.resolve(false)),
+  // Faithful copy of the real pure predicate (5-min redispatch bound) so the
+  // run-manager client-poll guard can be exercised without the real DB module.
+  UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS: 5 * 60_000,
+  shouldRedispatchUnclaimedBackgroundRun: (
+    row: { startedAt: number },
+    now: number = Date.now(),
+  ) => now - row.startedAt < 5 * 60_000,
   reconcileTerminalRunFromEvents: vi.fn(() => Promise.resolve(false)),
   ensureTerminalRunEvent: vi.fn(() => Promise.resolve()),
   getLastTerminalRunEvent: vi.fn(() => Promise.resolve(null)),
@@ -1831,14 +1838,16 @@ describe("run manager soft timeout", () => {
   });
 
   // ─── FALLBACK HARDENING: unclaimed background run recovery ──────────────────
-  it("recovers an unclaimed-stale background run (202 acked, worker never started)", async () => {
+  it("reaps an unclaimed-stale background run PAST the redispatch bound (202 acked, worker never started, no recovery left)", async () => {
     // dispatch_mode still 'background' (never flipped to 'background-processing')
-    // means the bg-fn worker silently died. The read path must recover it.
+    // means the bg-fn worker silently died. Once the successor is OLDER than the
+    // redispatch bound the sweep has had its chances, so the client poll reaps it
+    // loudly — this is the moved-later loud failure.
     vi.mocked(getRunByThread).mockResolvedValue({
       id: "run-unclaimed",
       threadId: "thread-unclaimed",
       status: "running",
-      startedAt: Date.now() - 30_000,
+      startedAt: Date.now() - (5 * 60_000 + 30_000), // past the 5-min bound
       heartbeatAt: Date.now() - 30_000,
       completedAt: null,
       lastProgressAt: null,
@@ -1857,6 +1866,42 @@ describe("run manager soft timeout", () => {
     expect(reapIfStale).not.toHaveBeenCalled();
   });
 
+  it("does NOT reap a deferred background successor while still WITHIN the redispatch bound — leaves it for the sweep", async () => {
+    // A successor that chainServerDrivenContinuation deferred (dispatch failed,
+    // row left running+background for the sweep to redispatch). At 30s it is well
+    // inside the 5-min redispatch bound, so the ~1s client poll must NOT reap it
+    // at the 25s unclaimed grace — that would convert the silent server-side
+    // recovery into a user-visible background_worker_never_started manual-retry
+    // error. reapIfStale (90s → stale_run auto-continue) stays the outer backstop.
+    vi.mocked(getRunByThread).mockResolvedValue({
+      id: "run-deferred",
+      threadId: "thread-deferred",
+      status: "running",
+      startedAt: Date.now() - 30_000, // within the 5-min bound
+      heartbeatAt: Date.now() - 30_000,
+      completedAt: null,
+      lastProgressAt: null,
+      dispatchMode: "background",
+      diagStage: null,
+    });
+    vi.mocked(reapUnclaimedBackgroundRun).mockClear();
+    // reapIfStale not yet eligible (background 90s window) → returns false, so the
+    // still-running successor is surfaced as active while it awaits the sweep.
+    vi.mocked(reapIfStale).mockResolvedValueOnce(false);
+
+    const result = await getActiveRunForThreadAsync("thread-deferred");
+
+    // The unclaimed reap was skipped — the sweep owns recovery inside the bound.
+    expect(reapUnclaimedBackgroundRun).not.toHaveBeenCalled();
+    // The run is still surfaced as an active background run (client keeps
+    // following; no premature manual-retry error).
+    expect(result).toMatchObject({
+      runId: "run-deferred",
+      status: "running",
+      dispatchMode: "background",
+    });
+  });
+
   it("does NOT attempt unclaimed recovery for a claimed (background-processing) run", async () => {
     vi.mocked(getRunByThread).mockResolvedValue({
       id: "run-processing",
diff --git a/packages/core/src/agent/run-manager.ts b/packages/core/src/agent/run-manager.ts
index 86867e5f10..81fccdcbee 100644
--- a/packages/core/src/agent/run-manager.ts
+++ b/packages/core/src/agent/run-manager.ts
@@ -16,6 +16,7 @@ import {
   bumpRunProgress,
   reapIfStale,
   reapUnclaimedBackgroundRun,
+  shouldRedispatchUnclaimedBackgroundRun,
   reconcileTerminalRunFromEvents,
   ensureTerminalRunEvent,
   getLastTerminalRunEvent,
@@ -1469,10 +1470,36 @@ export async function getActiveRunForThreadAsync(threadId: string): Promise<{
       // past the tight grace means the bg-fn worker never started — a silent
       // async-worker death that the 202-ack inline fallback can't catch. Reap it
       // early and recoverably (background_worker_never_started) so the run no
-      // longer hangs for the full 90s window and the client's recoverable-error
-      // path can re-drive the turn. Only fires when there is provably no live
-      // worker; a claimed/heartbeating run is left alone by the conditional SQL.
-      if (sqlRun.dispatchMode === "background") {
+      // longer hangs for the full 90s window. Only fires when there is provably
+      // no live worker; a claimed/heartbeating run is left alone by the
+      // conditional SQL.
+      //
+      // REDISPATCH-BOUND GUARD (must be kept in lockstep with the "Unclaimed
+      // background-run sweep" in agent-chat-plugin.ts and with
+      // chainServerDrivenContinuation's deferral in production-agent.ts — do NOT
+      // remove this guard without reading those two sites):
+      // `chainServerDrivenContinuation` now DEFERS a dispatch-failed successor
+      // instead of erroring it — it leaves the row status='running',
+      // dispatch_mode='background' with its dispatch_payload intact so the sweep
+      // can silently redispatch it. This client poll runs every ~1s while a
+      // client is connected, so without this guard it would reap that deferred
+      // successor at the 25s unclaimed grace — long before the ~2-min sweep —
+      // converting the intended SILENT server-side recovery into a user-visible
+      // `background_worker_never_started` manual-retry error (that terminal
+      // reason does NOT auto-continue in the client follow loop; only `stale_run`
+      // does). While the successor is still inside its redispatch bound we skip
+      // this reap and leave it for the sweep. The outer backstops still bound it:
+      // `reapIfStale` below reaps a heartbeat-stale background row at 90s
+      // (BACKGROUND_RUN_STALE_MS) to the recoverable `stale_run` — which the
+      // follow loop AUTO-continues — and once the redispatch bound is exceeded
+      // this reap fires loudly as before. So recovery stays automatic in the
+      // common case and loud failure is only moved later, never removed.
+      if (
+        sqlRun.dispatchMode === "background" &&
+        !shouldRedispatchUnclaimedBackgroundRun({
+          startedAt: sqlRun.startedAt,
+        })
+      ) {
         const recovered = await reapUnclaimedBackgroundRun(sqlRun.id).catch(
           () => false,
         );
diff --git a/packages/core/src/agent/run-store.foreground-self-chain.spec.ts b/packages/core/src/agent/run-store.foreground-self-chain.spec.ts
index 930f854e21..ef9c4ac9f4 100644
--- a/packages/core/src/agent/run-store.foreground-self-chain.spec.ts
+++ b/packages/core/src/agent/run-store.foreground-self-chain.spec.ts
@@ -182,4 +182,47 @@ describe("foreground self-chain — reaper coverage for the handoff window", ()
     expect(await reapUnclaimedBackgroundRun(successor)).toBe(false);
     expect((await getRunById(successor))?.status).toBe("running");
   });
+
+  // ── Deferred-successor recovery: sweep redispatch vs. reap interleaving ──
+  // A dispatch-deferred successor can now be recovered by the sweep OR reaped by
+  // a backstop; these prove the claim CAS keeps the two mutually exclusive so
+  // there is never a double-run and never a run-forever.
+
+  it("a redispatched worker that ARRIVES AFTER the row was reaped cannot execute (CAS requires status='running')", async () => {
+    const { successor, thread } = ids();
+    await insertRun(successor, thread, "turn-1", {
+      dispatchMode: "background",
+    });
+    setLiveness(successor, Date.now() - 60_000);
+
+    // A backstop (client-poll past the bound, or reapIfStale) reaps the row
+    // first: it is now terminal.
+    expect(await reapUnclaimedBackgroundRun(successor)).toBe(true);
+    expect((await getRunById(successor))?.status).toBe("errored");
+
+    // A sweep redispatch that was already in flight lands late; the worker it
+    // wakes tries to claim — the CAS (status='running' AND
+    // dispatch_mode='background') rejects the reaped row, so it no-ops instead
+    // of executing a turn nobody is watching.
+    expect(await claimBackgroundRun(successor)).toBe(false);
+  });
+
+  it("once a redispatched worker CLAIMS the row, a later reap cannot resurrect or double-run it", async () => {
+    const { successor, thread } = ids();
+    await insertRun(successor, thread, "turn-1", {
+      dispatchMode: "background",
+    });
+
+    // The sweep redispatched and a worker won the claim first: the row is now
+    // dispatch_mode='background-processing', still running.
+    expect(await claimBackgroundRun(successor)).toBe(true);
+
+    // A concurrent unclaimed-reap can no longer touch it — its WHERE clause
+    // requires dispatch_mode='background', which the claim already changed. So
+    // the claimed worker owns the run exclusively; no reap, no second claim.
+    setLiveness(successor, Date.now() - 60_000);
+    expect(await reapUnclaimedBackgroundRun(successor)).toBe(false);
+    expect((await getRunById(successor))?.status).toBe("running");
+    expect(await claimBackgroundRun(successor)).toBe(false);
+  });
 });
diff --git a/packages/core/src/agent/run-store.spec.ts b/packages/core/src/agent/run-store.spec.ts
index 1531033588..44c11a82ce 100644
--- a/packages/core/src/agent/run-store.spec.ts
+++ b/packages/core/src/agent/run-store.spec.ts
@@ -29,6 +29,10 @@ let insertEventBehavior: () => void = () => {};
 let abortRowsAffected = 1;
 let dispatchPayloadRows: Array<{ dispatch_payload: string | null }> = [];
 let unclaimedBackgroundRunRows: Array<{ id: string }> = [];
+let unclaimedBackgroundRunRowsWithStartedAt: Array<{
+  id: string;
+  started_at: number;
+}> = [];
 let runCountRows: Array<{ run_count: number }> = [];
 
 const mockDb = {
@@ -55,6 +59,18 @@ const mockDb = {
     ) {
       return { rows: claimSlotRows, rowsAffected: 0 };
     }
+    // listUnclaimedBackgroundRunRows: SELECT id, started_at FROM agent_runs
+    // WHERE status = 'running' AND dispatch_mode = 'background' AND ... Must
+    // come before the narrower id-only variant below (both match
+    // "dispatch_mode = 'background'").
+    if (
+      /SELECT id, started_at FROM agent_runs\s*WHERE status = 'running'/i.test(
+        rawSql,
+      ) &&
+      /dispatch_mode = 'background'/i.test(rawSql)
+    ) {
+      return { rows: unclaimedBackgroundRunRowsWithStartedAt, rowsAffected: 0 };
+    }
     // listUnclaimedBackgroundRunIds: SELECT id FROM agent_runs WHERE status =
     // 'running' AND dispatch_mode = 'background' AND ... Must also come before
     // the broader stale-run SELECT check below, which matches the same shape.
@@ -156,7 +172,10 @@ const {
   readRunDispatchPayload,
   clearRunDispatchPayload,
   listUnclaimedBackgroundRunIds,
+  listUnclaimedBackgroundRunRows,
   countRunsForTurn,
+  UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS,
+  shouldRedispatchUnclaimedBackgroundRun,
 } = await import("./run-store.js");
 
 // Mock storage for ledger SELECT responses, keyed by toolKey
@@ -177,6 +196,7 @@ describe("run store", () => {
     ledgerRows = [];
     dispatchPayloadRows = [];
     unclaimedBackgroundRunRows = [];
+    unclaimedBackgroundRunRowsWithStartedAt = [];
     runCountRows = [];
     insertEventBehavior = () => {};
     abortRowsAffected = 1;
@@ -862,4 +882,86 @@ describe("run store", () => {
     const ids = await listUnclaimedBackgroundRunIds();
     expect(ids).toEqual(["run-ok"]);
   });
+
+  // ─── listUnclaimedBackgroundRunRows (sweep redispatch bound) ───────────────
+
+  it("listUnclaimedBackgroundRunRows returns each row's original started_at alongside its id", async () => {
+    unclaimedBackgroundRunRowsWithStartedAt = [
+      { id: "run-lost-1", started_at: 111 },
+      { id: "run-lost-2", started_at: 222 },
+    ];
+    const rows = await listUnclaimedBackgroundRunRows();
+    expect(rows).toEqual([
+      { id: "run-lost-1", startedAt: 111 },
+      { id: "run-lost-2", startedAt: 222 },
+    ]);
+
+    const select = execCalls.find((call) =>
+      /SELECT id, started_at FROM agent_runs\s*WHERE status = 'running'/i.test(
+        call.sql,
+      ),
+    );
+    expect(select?.sql).toContain("dispatch_mode = 'background'");
+    expect(select?.sql).toContain("COALESCE(heartbeat_at, started_at)");
+  });
+
+  it("listUnclaimedBackgroundRunRows ignores rows with a non-string/empty id defensively", async () => {
+    unclaimedBackgroundRunRowsWithStartedAt = [
+      { id: "run-ok", started_at: 100 },
+      // @ts-expect-error -- exercising defensive filtering of malformed rows
+      { id: null, started_at: 200 },
+    ];
+    const rows = await listUnclaimedBackgroundRunRows();
+    expect(rows).toEqual([{ id: "run-ok", startedAt: 100 }]);
+  });
+
+  it("UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS is a real bound wider than the grace window — never zero, never infinite", () => {
+    // The sweep must get more than one redispatch attempt (grace window is
+    // 25s, sweep tick is ~2min) but the bound must still be finite so a
+    // permanently-dead handoff eventually fails loud instead of retrying
+    // forever.
+    expect(UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS).toBeGreaterThan(
+      2 * 60_000,
+    );
+    expect(Number.isFinite(UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS)).toBe(
+      true,
+    );
+  });
+
+  // ─── shouldRedispatchUnclaimedBackgroundRun (bounded recovery backstop) ────
+
+  it("shouldRedispatchUnclaimedBackgroundRun allows redispatch while inside the bound", () => {
+    const now = 1_000_000;
+    const row = {
+      startedAt: now - UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS + 1,
+    };
+    expect(shouldRedispatchUnclaimedBackgroundRun(row, now)).toBe(true);
+  });
+
+  it("shouldRedispatchUnclaimedBackgroundRun falls back to the reap once the bound is exceeded — the loud backstop", () => {
+    const now = 1_000_000;
+    // Exactly at the bound: no longer "within" it (strict <).
+    const atBound = {
+      startedAt: now - UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS,
+    };
+    expect(shouldRedispatchUnclaimedBackgroundRun(atBound, now)).toBe(false);
+
+    // Well past the bound — a genuinely dead handoff must stop being
+    // redispatched forever and go to the reap instead.
+    const wayPast = {
+      startedAt: now - UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS * 10,
+    };
+    expect(shouldRedispatchUnclaimedBackgroundRun(wayPast, now)).toBe(false);
+  });
+
+  it("shouldRedispatchUnclaimedBackgroundRun defaults `now` to the real clock", () => {
+    // A row that just started is always within the bound right now.
+    expect(
+      shouldRedispatchUnclaimedBackgroundRun({ startedAt: Date.now() }),
+    ).toBe(true);
+    // A row from a very long time ago is not.
+    expect(shouldRedispatchUnclaimedBackgroundRun({ startedAt: 0 })).toBe(
+      false,
+    );
+  });
 });
diff --git a/packages/core/src/agent/run-store.ts b/packages/core/src/agent/run-store.ts
index 29db920308..6f6f125142 100644
--- a/packages/core/src/agent/run-store.ts
+++ b/packages/core/src/agent/run-store.ts
@@ -99,6 +99,21 @@ export const CLAIMED_BACKGROUND_WORKER_FAILED_ERROR_EVENT = {
  */
 export const UNCLAIMED_BACKGROUND_RUN_GRACE_MS = 25_000;
 
+/**
+ * Backstop ceiling — measured from the row's ORIGINAL `started_at`, which never
+ * changes — after which the unclaimed-background-run sweep stops attempting to
+ * redispatch a lost handoff and instead reaps it via `reapUnclaimedBackgroundRun`
+ * (loud, attributable `errored`). This is what keeps redispatch recoverable
+ * WITHOUT becoming a silent hang: a handoff that cannot be delivered within this
+ * window (a genuinely dead platform, not a transient blip) still fails loudly,
+ * it just gets a few sweep-cycle chances first. 5 minutes comfortably allows
+ * multiple 2-minute sweep ticks (see `agent-chat-plugin.ts`'s
+ * "Unclaimed background-run sweep") while staying well inside both the 40s
+ * foreground chunk clamp and the ~13min background soft-timeout ceiling that
+ * bound how long a real user turn is worth waiting on before failing loud.
+ */
+export const UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS = 5 * 60_000;
+
 async function ensureRunTables(): Promise<void> {
   if (!_initPromise) {
     _initPromise = (async () => {
@@ -648,6 +663,71 @@ export async function listUnclaimedBackgroundRunIds(): Promise<string[]> {
   return ids;
 }
 
+/** A row returned by `listUnclaimedBackgroundRunRows`. */
+export interface UnclaimedBackgroundRunRow {
+  id: string;
+  /** The row's ORIGINAL `started_at` (never bumped by heartbeats), so a
+   *  caller can measure total elapsed time since the handoff was first
+   *  pre-inserted — independent of any liveness bump a redispatch attempt
+   *  makes along the way. */
+  startedAt: number;
+}
+
+/**
+ * Same eligibility as `listUnclaimedBackgroundRunIds`, but also returns each
+ * row's original `started_at` so a caller can bound total redispatch time
+ * (see `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS`) independent of the
+ * liveness bumps a redispatch attempt makes along the way. Used by the
+ * unclaimed-background-run sweep's redispatch pass; `listUnclaimedBackgroundRunIds`
+ * is kept as the simpler, pre-existing surface for callers that only need ids.
+ */
+export async function listUnclaimedBackgroundRunRows(): Promise<
+  UnclaimedBackgroundRunRow[]
+> {
+  await ensureRunTables();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    // CAST keeps the ms-epoch param 64-bit on Postgres (see
+    // backgroundAwareStaleCutoffSql for the int4-inference failure mode).
+    sql: `SELECT id, started_at FROM agent_runs
+          WHERE status = 'running'
+            AND dispatch_mode = 'background'
+            AND COALESCE(heartbeat_at, started_at) < (CAST(? AS BIGINT) - ${UNCLAIMED_BACKGROUND_RUN_GRACE_MS})`,
+    args: [Date.now()],
+  });
+  const result: UnclaimedBackgroundRunRow[] = [];
+  for (const row of rows ?? []) {
+    const id = (row as { id?: unknown }).id;
+    const startedAt = (row as { started_at?: unknown }).started_at;
+    if (typeof id === "string" && id) {
+      result.push({
+        id,
+        startedAt:
+          typeof startedAt === "number" ? startedAt : Number(startedAt) || 0,
+      });
+    }
+  }
+  return result;
+}
+
+/**
+ * Pure decision for the unclaimed-background-run sweep: should THIS row get
+ * another redispatch attempt, or has it exceeded
+ * `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS` and must fall back to the
+ * loud reap (`reapUnclaimedBackgroundRun`)? Measured from the row's ORIGINAL
+ * `started_at` (never bumped by a redispatch's heartbeat write), so this is
+ * the total-elapsed-time backstop that keeps recovery bounded — a handoff
+ * that cannot be delivered within the window is not spinning forever, it
+ * fails loud. Exported as a pure function (no DB access) so the bound is unit
+ * -testable independent of the sweep's setInterval wiring.
+ */
+export function shouldRedispatchUnclaimedBackgroundRun(
+  row: { startedAt: number },
+  now: number = Date.now(),
+): boolean {
+  return now - row.startedAt < UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS;
+}
+
 /**
  * Count how many runs (chunks) a logical turn has consumed so far. This is the
  * durable per-turn recovery ledger: unlike the in-marker `continuationCount`
diff --git a/packages/core/src/cli/design-connect-bridge-filters.spec.ts b/packages/core/src/cli/design-connect-bridge-filters.spec.ts
index 7513df4891..1334ec9bff 100644
--- a/packages/core/src/cli/design-connect-bridge-filters.spec.ts
+++ b/packages/core/src/cli/design-connect-bridge-filters.spec.ts
@@ -484,6 +484,43 @@ describe("design connect bridge version conflict handling", () => {
       );
       expect(result.status).toBe(200);
       expect(typeof result.body["versionHash"]).toBe("string");
+      expect(result.body["versionHash"]).toMatch(/^[a-f0-9]{64}$/);
+    } finally {
+      await new Promise<void>((resolve) =>
+        bridge.server.close(() => resolve()),
+      );
+    }
+  });
+
+  it("uses content hashes when size and mtime are unchanged", async () => {
+    const root = tmpDir();
+    const file = path.join(root, "same-size.tsx");
+    const fixedTime = new Date("2025-01-01T00:00:00.000Z");
+    fs.writeFileSync(file, "AAAA");
+    fs.utimesSync(file, fixedTime, fixedTime);
+    const port = await freePort();
+    const manifest = await prepareDesignConnectManifest({
+      root,
+      url: "http://localhost:5173",
+      port,
+    });
+    const bridge = await startDesignConnectBridge(manifest);
+    const auth = { "x-bridge-token": bridge.bridgeToken };
+    try {
+      const base = `http://127.0.0.1:${port}`;
+      const before = await postJson(
+        `${base}/read-file`,
+        { relPath: "same-size.tsx" },
+        auth,
+      );
+      fs.writeFileSync(file, "BBBB");
+      fs.utimesSync(file, fixedTime, fixedTime);
+      const after = await postJson(
+        `${base}/read-file`,
+        { relPath: "same-size.tsx" },
+        auth,
+      );
+      expect(before.body["versionHash"]).not.toBe(after.body["versionHash"]);
     } finally {
       await new Promise<void>((resolve) =>
         bridge.server.close(() => resolve()),
@@ -517,6 +554,88 @@ describe("design connect bridge version conflict handling", () => {
     }
   });
 
+  it("supports an exact-hash contract without changing legacy optional writes", async () => {
+    const root = tmpDir();
+    fs.writeFileSync(path.join(root, "component.tsx"), "export const v = 0;\n");
+    const port = await freePort();
+    const manifest = await prepareDesignConnectManifest({
+      root,
+      url: "http://localhost:5173",
+      port,
+    });
+    const bridge = await startDesignConnectBridge(manifest);
+    const auth = { "x-bridge-token": bridge.bridgeToken };
+    try {
+      const base = `http://127.0.0.1:${port}`;
+      const guarded = await postJson(
+        `${base}/write-file`,
+        {
+          relPath: "component.tsx",
+          content: "export const v = 1;\n",
+          requireExpectedVersionHash: true,
+        },
+        auth,
+      );
+      expect(guarded.status).toBe(428);
+      expect(guarded.body["error"]).toBe("expectedVersionHash is required");
+
+      const legacy = await postJson(
+        `${base}/write-file`,
+        { relPath: "component.tsx", content: "export const v = 2;\n" },
+        auth,
+      );
+      expect(legacy.status).toBe(200);
+    } finally {
+      await new Promise<void>((resolve) =>
+        bridge.server.close(() => resolve()),
+      );
+    }
+  });
+
+  it("treats deletion as a conflict under the exact-hash contract", async () => {
+    const root = tmpDir();
+    const file = path.join(root, "component.tsx");
+    fs.writeFileSync(file, "export const v = 0;\n");
+    const port = await freePort();
+    const manifest = await prepareDesignConnectManifest({
+      root,
+      url: "http://localhost:5173",
+      port,
+    });
+    const bridge = await startDesignConnectBridge(manifest);
+    const auth = { "x-bridge-token": bridge.bridgeToken };
+    try {
+      const base = `http://127.0.0.1:${port}`;
+      const read = await postJson(
+        `${base}/read-file`,
+        { relPath: "component.tsx" },
+        auth,
+      );
+      fs.rmSync(file);
+      const result = await postJson(
+        `${base}/write-file`,
+        {
+          relPath: "component.tsx",
+          content: "export const v = 1;\n",
+          expectedVersionHash: read.body["versionHash"],
+          requireExpectedVersionHash: true,
+        },
+        auth,
+      );
+      expect(result.status).toBe(409);
+      expect(result.body).toMatchObject({
+        ok: false,
+        error: "version conflict",
+      });
+      expect(result.body).not.toHaveProperty("content");
+      expect(fs.existsSync(file)).toBe(false);
+    } finally {
+      await new Promise<void>((resolve) =>
+        bridge.server.close(() => resolve()),
+      );
+    }
+  });
+
   it("write-file returns 409 when expectedVersionHash is stale", async () => {
     const root = tmpDir();
     fs.writeFileSync(path.join(root, "index.html"), "<h1>hi</h1>");
@@ -605,6 +724,138 @@ describe("design connect bridge version conflict handling", () => {
     }
   });
 
+  it("serializes concurrent compare-and-swap writes to one canonical path", async () => {
+    const root = tmpDir();
+    fs.mkdirSync(path.join(root, "real"));
+    fs.writeFileSync(
+      path.join(root, "real/component.tsx"),
+      "export const v = 0;\n",
+    );
+    fs.symlinkSync(path.join(root, "real"), path.join(root, "alias"), "dir");
+    const port = await freePort();
+    const manifest = await prepareDesignConnectManifest({
+      root,
+      url: "http://localhost:5173",
+      port,
+    });
+    const bridge = await startDesignConnectBridge(manifest);
+    const auth = { "x-bridge-token": bridge.bridgeToken };
+    try {
+      const base = `http://127.0.0.1:${port}`;
+      const read = await postJson(
+        `${base}/read-file`,
+        { relPath: "real/component.tsx" },
+        auth,
+      );
+      const expectedVersionHash = read.body["versionHash"] as string;
+      const writes = await Promise.all(
+        [
+          { value: 1, relPath: "real/component.tsx" },
+          { value: 2, relPath: "alias/component.tsx" },
+        ].map(({ value, relPath }) =>
+          postJson(
+            `${base}/write-file`,
+            {
+              relPath,
+              content: `export const v = ${value};\n`,
+              expectedVersionHash,
+            },
+            auth,
+          ),
+        ),
+      );
+      expect(writes.map((result) => result.status).sort()).toEqual([200, 409]);
+      const winner = writes.find((result) => result.status === 200)!;
+      const finalRead = await postJson(
+        `${base}/read-file`,
+        { relPath: "real/component.tsx" },
+        auth,
+      );
+      expect(finalRead.body["versionHash"]).toBe(winner.body["versionHash"]);
+      expect(
+        fs
+          .readdirSync(path.join(root, "real"))
+          .filter((name) => name.includes(".agent-native-")),
+      ).toEqual([]);
+    } finally {
+      await new Promise<void>((resolve) =>
+        bridge.server.close(() => resolve()),
+      );
+    }
+  });
+
+  it("rejects a leaf symlink swapped in after read without touching its target", async () => {
+    const root = tmpDir();
+    const outside = tmpDir();
+    const relPath = "component.tsx";
+    const localPath = path.join(root, relPath);
+    const outsidePath = path.join(outside, "outside.tsx");
+    fs.writeFileSync(localPath, "export const local = true;\n");
+    fs.writeFileSync(outsidePath, "export const secret = true;\n");
+    const port = await freePort();
+    const manifest = await prepareDesignConnectManifest({
+      root,
+      url: "http://localhost:5173",
+      port,
+    });
+    const bridge = await startDesignConnectBridge(manifest);
+    const auth = { "x-bridge-token": bridge.bridgeToken };
+    try {
+      const base = `http://127.0.0.1:${port}`;
+      const read = await postJson(`${base}/read-file`, { relPath }, auth);
+      fs.rmSync(localPath);
+      fs.symlinkSync(outsidePath, localPath);
+      const result = await postJson(
+        `${base}/write-file`,
+        {
+          relPath,
+          content: "export const overwritten = true;\n",
+          expectedVersionHash: read.body["versionHash"],
+        },
+        auth,
+      );
+      expect(result.status).not.toBe(200);
+      expect(fs.readFileSync(outsidePath, "utf8")).toBe(
+        "export const secret = true;\n",
+      );
+    } finally {
+      await new Promise<void>((resolve) =>
+        bridge.server.close(() => resolve()),
+      );
+    }
+  });
+
+  it("atomically creates nested files and removes temp siblings", async () => {
+    const root = tmpDir();
+    const port = await freePort();
+    const manifest = await prepareDesignConnectManifest({
+      root,
+      url: "http://localhost:5173",
+      port,
+    });
+    const bridge = await startDesignConnectBridge(manifest);
+    try {
+      const result = await postJson(
+        `http://127.0.0.1:${port}/write-file`,
+        { relPath: "src/new.tsx", content: "export default <main />;\n" },
+        { "x-bridge-token": bridge.bridgeToken },
+      );
+      expect(result.status).toBe(200);
+      expect(fs.readFileSync(path.join(root, "src/new.tsx"), "utf8")).toBe(
+        "export default <main />;\n",
+      );
+      expect(
+        fs
+          .readdirSync(path.join(root, "src"))
+          .filter((name) => name.includes(".agent-native-")),
+      ).toEqual([]);
+    } finally {
+      await new Promise<void>((resolve) =>
+        bridge.server.close(() => resolve()),
+      );
+    }
+  });
+
   it("apply-edit returns 409 when expectedVersionHash is stale", async () => {
     const root = tmpDir();
     fs.writeFileSync(path.join(root, "style.css"), "body { color: red; }");
diff --git a/packages/core/src/cli/design-connect.spec.ts b/packages/core/src/cli/design-connect.spec.ts
index e0de73f5f6..e5f06509ca 100644
--- a/packages/core/src/cli/design-connect.spec.ts
+++ b/packages/core/src/cli/design-connect.spec.ts
@@ -564,6 +564,106 @@ describe("design connect bridge endpoints", () => {
     }
   });
 
+  it("signals an unregistered bridgeKey with a machine-readable code and the process's bridgeInstanceId, so a client can tell a restarted bridge apart from a real bug", async () => {
+    const root = tmpDir();
+    const devPort = await freePort();
+    const devServer = http.createServer((_req, res) => {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end("<!doctype html><html><body><main>Screen</main></body></html>");
+    });
+    await new Promise<void>((resolve, reject) => {
+      devServer.once("error", reject);
+      devServer.listen(devPort, "127.0.0.1", () => {
+        devServer.off("error", reject);
+        resolve();
+      });
+    });
+    const port = await freePort();
+    const manifest = await prepareDesignConnectManifest({
+      root,
+      url: `http://127.0.0.1:${devPort}`,
+      port,
+    });
+    const bridge = await startDesignConnectBridge(manifest);
+    try {
+      const base = `http://127.0.0.1:${port}`;
+
+      // A bridgeKey that was never registered against THIS bridge process —
+      // e.g. the client remembers registering it before the bridge process
+      // restarted (crash, machine sleep/wake, manual restart), which silently
+      // empties the in-memory liveEditBridgeScripts map.
+      const unregistered = await getJson(
+        `${base}/live-edit?path=/a&bridgeKey=never-registered&previewToken=${bridge.previewToken}`,
+      );
+      expect(unregistered.status).toBe(409);
+      expect(unregistered.body.code).toBe("unknown-bridge-key");
+      expect(unregistered.body.bridgeKey).toBe("never-registered");
+      expect(unregistered.body.bridgeInstanceId).toBe(bridge.bridgeInstanceId);
+
+      // The registration endpoint echoes the same instance id, so a client
+      // that registers, then later hits the 409 above with a DIFFERENT
+      // bridgeInstanceId than what it got back here, knows the process
+      // restarted (safe to silently re-register) rather than distrust its
+      // own bridgeKey.
+      const registration = await postJson(
+        `${base}/live-edit-bridge`,
+        {
+          script:
+            '<script>window.parent.postMessage({type:"agent-native:editor-chrome-ready"},"*");</script>',
+          bridgeKey: "screen-a",
+        },
+        { "x-design-preview-token": bridge.previewToken },
+      );
+      expect(registration.body.bridgeInstanceId).toBe(bridge.bridgeInstanceId);
+
+      // /health exposes the same id for a lightweight out-of-band check.
+      const health = await getJson(`${base}/health`);
+      expect(health.body.bridgeInstanceId).toBe(bridge.bridgeInstanceId);
+    } finally {
+      await new Promise<void>((resolve) =>
+        bridge.server.close(() => resolve()),
+      );
+      await new Promise<void>((resolve) => devServer.close(() => resolve()));
+    }
+  });
+
+  it("mints a fresh bridgeInstanceId per bridge process, so a restart is distinguishable", async () => {
+    const root = tmpDir();
+    const devPort = await freePort();
+    const devServer = http.createServer((_req, res) => {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end("<!doctype html><html><body><main>Screen</main></body></html>");
+    });
+    await new Promise<void>((resolve, reject) => {
+      devServer.once("error", reject);
+      devServer.listen(devPort, "127.0.0.1", () => {
+        devServer.off("error", reject);
+        resolve();
+      });
+    });
+    const port = await freePort();
+    const manifest = await prepareDesignConnectManifest({
+      root,
+      url: `http://127.0.0.1:${devPort}`,
+      port,
+    });
+    const firstBridge = await startDesignConnectBridge(manifest);
+    await new Promise<void>((resolve) =>
+      firstBridge.server.close(() => resolve()),
+    );
+    const secondBridge = await startDesignConnectBridge(manifest);
+    try {
+      expect(secondBridge.bridgeInstanceId).not.toBe(
+        firstBridge.bridgeInstanceId,
+      );
+    } finally {
+      await new Promise<void>((resolve) =>
+        secondBridge.server.close(() => resolve()),
+      );
+      await new Promise<void>((resolve) => devServer.close(() => resolve()));
+    }
+  });
+
   it("returns read-only HTML snapshots from the connected dev server", async () => {
     const root = tmpDir();
     const devPort = await freePort();
@@ -608,6 +708,16 @@ describe("design connect bridge endpoints", () => {
     const devPort = await freePort();
     const devServer = http.createServer((req, res) => {
       if (req.url?.startsWith("/src/main.ts")) {
+        if (req.headers.cookie || req.headers.authorization) {
+          res.writeHead(400, { "content-type": "text/plain" });
+          res.end("sensitive request headers leaked");
+          return;
+        }
+        if (req.headers["sec-fetch-dest"] !== "script") {
+          res.writeHead(404, { "content-type": "text/plain" });
+          res.end("missing script destination");
+          return;
+        }
         res.writeHead(200, {
           "content-type": "application/javascript; charset=utf-8",
           "cache-control": "no-store",
@@ -684,11 +794,17 @@ describe("design connect bridge endpoints", () => {
 
       const module = await getText(`${base}/src/main.ts`, {
         "sec-fetch-site": "same-origin",
+        "sec-fetch-dest": "script",
+        cookie: "pilot_session=must-not-forward",
+        authorization: "Bearer example-must-not-forward",
       });
       expect(module.status).toBe(200);
       expect(module.headers["content-type"]).toContain(
         "application/javascript",
       );
+      expect(module.headers["content-length"]).toBe(
+        String(Buffer.byteLength(module.body)),
+      );
       expect(module.body).toContain("CSR booted");
 
       const panOnlyRegistration = await postJson(
diff --git a/packages/core/src/cli/design-connect.ts b/packages/core/src/cli/design-connect.ts
index 31bfe9b716..bc527165e4 100644
--- a/packages/core/src/cli/design-connect.ts
+++ b/packages/core/src/cli/design-connect.ts
@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import crypto from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
 import http, {
   type IncomingMessage,
   type Server,
@@ -123,6 +124,12 @@ export interface DesignConnectBridge {
    *  bridge-registration endpoints. Safe to hand to the Design browser, but
    *  never accepted by filesystem endpoints. */
   previewToken: string;
+  /** Random id minted fresh each time this bridge process boots. Also
+   *  returned by `/health`, `/live-edit-bridge`, and the "unknown bridge key"
+   *  409 from `/live-edit` — a client can compare it across those responses
+   *  to tell a restarted bridge process apart from a genuine registration
+   *  bug. See the `bridgeInstanceId` doc comment in startDesignConnectBridge. */
+  bridgeInstanceId: string;
 }
 
 export interface DesignConnectBridgeOptions {
@@ -679,11 +686,11 @@ export async function prepareDesignConnectManifest(
       reason:
         operation === "resolveNodeToFile"
           ? // resolveNodeToFile maps a runtime DOM node id (from the editor's
-            // 'select' payload) to { file, line, component } provenance.  The
-            // bridge endpoint exists; per-element provenance data must be
-            // emitted by the connected app at build time — see the provenance
-            // note in the help text below.
-            "Requires the connected app to emit data-source-file / data-source-line / data-component-name attributes (e.g. via @vitejs/plugin-react jsxDEV or a Babel source plugin)."
+            // 'select' payload) to { file, line, component } provenance.
+            // React development builds expose jsxDEV call sites through the
+            // Fiber debug stack; other runtimes/builds can emit explicit DOM
+            // provenance attributes — see the help text below.
+            "React development builds resolve jsxDEV call sites automatically; other runtimes can emit data-source-file / data-source-line / data-component-name attributes."
           : undefined,
     })),
   };
@@ -786,9 +793,11 @@ function sendBytes(
   statusCode: number,
   body: Buffer,
   headers: Headers,
+  contentLength = body.length,
 ) {
   const responseHeaders: Record<string, string> = {
     ...bridgeCorsHeaders(res),
+    "content-length": String(contentLength),
   };
   for (const name of [
     "content-type",
@@ -833,6 +842,25 @@ function readHeader(req: IncomingMessage, name: string): string {
   return typeof value === "string" ? value : "";
 }
 
+/**
+ * Preserve only the browser request metadata a local dev server needs to
+ * classify Vite source-module and stylesheet requests. Agent Native's dev
+ * gateway intentionally varies source-file handling by `Sec-Fetch-Dest`; if
+ * the bridge drops it, React Router module URLs such as `/app/root.tsx` fall
+ * through to Nitro and 404. Keep this allowlist narrow: cookies, authorization,
+ * bridge tokens, origins, and referrers must never be forwarded upstream.
+ */
+function previewProxyRequestHeaders(
+  req: IncomingMessage,
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const name of ["accept", "sec-fetch-dest"] as const) {
+    const value = readHeader(req, name);
+    if (value) headers[name] = value;
+  }
+  return headers;
+}
+
 function resolvePreviewSnapshotUrl(
   devServerUrl: string,
   rawUrl: string | null,
@@ -917,6 +945,7 @@ async function fetchPreviewSnapshot(
 async function fetchPreviewProxyResource(
   devServerUrl: string,
   targetUrl: string,
+  requestHeaders: Record<string, string> = {},
   redirects = 0,
 ): Promise<{
   url: string;
@@ -934,6 +963,7 @@ async function fetchPreviewProxyResource(
       method: "GET",
       redirect: "manual",
       signal: controller.signal,
+      headers: requestHeaders,
     });
     const location = response.headers.get("location");
     if (location && response.status >= 300 && response.status < 400) {
@@ -945,6 +975,7 @@ async function fetchPreviewProxyResource(
       return fetchPreviewProxyResource(
         devServerUrl,
         redirected.toString(),
+        requestHeaders,
         redirects + 1,
       );
     }
@@ -1101,6 +1132,236 @@ async function assertPathInside(
   }
 }
 
+interface SafeBridgeFileTarget {
+  absolutePath: string;
+  canonicalPath: string;
+}
+
+/**
+ * Resolve a bridge file to a stable lock key without following a leaf
+ * symlink. Missing parent directories are represented beneath their nearest
+ * existing real ancestor, so aliases through in-root directory symlinks share
+ * one mutex while first-time file creation remains supported.
+ */
+async function resolveSafeBridgeFileTarget(
+  rootPath: string,
+  targetPath: string,
+): Promise<SafeBridgeFileTarget> {
+  await assertPathInside(rootPath, targetPath);
+  const resolvedRoot = await fs.realpath(rootPath);
+  const absolutePath = path.resolve(rootPath, targetPath);
+  let existingAncestor = path.dirname(absolutePath);
+  let resolvedAncestor: string | null = null;
+  for (let depth = 0; depth < 32; depth += 1) {
+    try {
+      resolvedAncestor = await fs.realpath(existingAncestor);
+      break;
+    } catch {
+      const parent = path.dirname(existingAncestor);
+      if (parent === existingAncestor) break;
+      existingAncestor = parent;
+    }
+  }
+  if (!resolvedAncestor) {
+    throw new Error(`Cannot resolve parent directory: ${absolutePath}`);
+  }
+  // Existing regular files get their own realpath as the lock key. Besides
+  // resolving in-root directory aliases, this canonicalizes case on the
+  // default macOS filesystem so `Button.tsx` and `button.tsx` cannot acquire
+  // separate mutexes for the same inode. assertPathInside already rejected a
+  // symlink leaf before this point.
+  const canonicalPath =
+    (await fs.realpath(absolutePath).catch(() => null)) ??
+    path.resolve(
+      resolvedAncestor,
+      path.relative(existingAncestor, absolutePath),
+    );
+  if (
+    canonicalPath !== resolvedRoot &&
+    !canonicalPath.startsWith(resolvedRoot + path.sep)
+  ) {
+    throw new Error("Path traversal detected: resolved target is outside root");
+  }
+  return { absolutePath, canonicalPath };
+}
+
+const bridgeWriteLocks = new Map<string, Promise<void>>();
+
+/** Serialize read-check-write sequences for one canonical local file. */
+async function withBridgeWriteLock<T>(
+  canonicalPath: string,
+  work: () => Promise<T>,
+): Promise<T> {
+  const previous = bridgeWriteLocks.get(canonicalPath) ?? Promise.resolve();
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const queued = previous.catch(() => undefined).then(() => gate);
+  bridgeWriteLocks.set(canonicalPath, queued);
+  await previous.catch(() => undefined);
+  try {
+    return await work();
+  } finally {
+    release();
+    if (bridgeWriteLocks.get(canonicalPath) === queued) {
+      bridgeWriteLocks.delete(canonicalPath);
+    }
+  }
+}
+
+interface BridgeFileSnapshot {
+  content: string;
+  versionHash: string;
+  mode: number;
+}
+
+function contentVersionHash(content: string | Buffer): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/** Read an existing regular file without ever following a leaf symlink. */
+async function readBridgeFileSnapshot(
+  absolutePath: string,
+): Promise<BridgeFileSnapshot | null> {
+  const noFollow = fsSync.constants.O_NOFOLLOW ?? 0;
+  let handle: FileHandle | null = null;
+  try {
+    handle = await fs.open(absolutePath, fsSync.constants.O_RDONLY | noFollow);
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+      throw new Error(`Bridge target is not a regular file: ${absolutePath}`);
+    }
+    const bytes = await handle.readFile();
+    return {
+      content: bytes.toString("utf8"),
+      versionHash: contentVersionHash(bytes),
+      mode: stat.mode & 0o777,
+    };
+  } catch (error: unknown) {
+    const code =
+      error instanceof Error && "code" in error
+        ? (error as NodeJS.ErrnoException).code
+        : undefined;
+    if (code === "ENOENT") return null;
+    throw error;
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+class BridgeVersionConflictError extends Error {
+  constructor(readonly currentVersionHash?: string) {
+    super("version conflict");
+  }
+}
+
+class BridgePreconditionRequiredError extends Error {
+  constructor() {
+    super("expectedVersionHash is required");
+  }
+}
+
+function assertExpectedBridgeVersion(
+  expectedVersionHash: string | undefined,
+  currentVersionHash: string | undefined,
+  requireExpectedVersionHash = false,
+): void {
+  // Preserve compatibility: callers that omit a hash retain the existing
+  // last-write-wins behavior, including creation. Compiled-source callers opt
+  // into exact compare-and-swap by sending the hash returned by read-file.
+  if (requireExpectedVersionHash && expectedVersionHash === undefined) {
+    throw new BridgePreconditionRequiredError();
+  }
+  if (
+    expectedVersionHash !== undefined &&
+    (currentVersionHash !== undefined
+      ? currentVersionHash !== expectedVersionHash
+      : requireExpectedVersionHash)
+  ) {
+    throw new BridgeVersionConflictError(currentVersionHash);
+  }
+}
+
+/**
+ * Replace a file durably without exposing a partial write: create an
+ * O_EXCL/O_NOFOLLOW temp sibling, fsync it, revalidate confinement and the
+ * expected content hash, rename atomically, then fsync the parent directory.
+ */
+async function atomicWriteBridgeFile(args: {
+  rootPath: string;
+  relPath: string;
+  lockedCanonicalPath: string;
+  content: string;
+  expectedVersionHash?: string;
+  requireExpectedVersionHash?: boolean;
+  originalMode?: number;
+}): Promise<string> {
+  const parent = path.dirname(path.resolve(args.rootPath, args.relPath));
+  await fs.mkdir(parent, { recursive: true });
+  const revalidated = await resolveSafeBridgeFileTarget(
+    args.rootPath,
+    args.relPath,
+  );
+  if (revalidated.canonicalPath !== args.lockedCanonicalPath) {
+    throw new Error("Bridge target changed while waiting for the write lock");
+  }
+
+  const basename = path.basename(revalidated.absolutePath);
+  const tempPath = path.join(
+    parent,
+    `.${basename}.agent-native-${process.pid}-${crypto.randomBytes(8).toString("hex")}.tmp`,
+  );
+  const noFollow = fsSync.constants.O_NOFOLLOW ?? 0;
+  let tempHandle: FileHandle | null = null;
+  try {
+    tempHandle = await fs.open(
+      tempPath,
+      fsSync.constants.O_CREAT |
+        fsSync.constants.O_EXCL |
+        fsSync.constants.O_WRONLY |
+        noFollow,
+      args.originalMode ?? 0o666,
+    );
+    await tempHandle.writeFile(args.content, "utf8");
+    await tempHandle.sync();
+    await tempHandle.close();
+    tempHandle = null;
+
+    // Re-check after the potentially slow temp write/fsync. This catches a
+    // parent/leaf symlink swap and an external content edit before rename.
+    const beforeRenameTarget = await resolveSafeBridgeFileTarget(
+      args.rootPath,
+      args.relPath,
+    );
+    if (beforeRenameTarget.canonicalPath !== args.lockedCanonicalPath) {
+      throw new Error("Bridge target changed during atomic write");
+    }
+    const current = await readBridgeFileSnapshot(
+      beforeRenameTarget.absolutePath,
+    );
+    assertExpectedBridgeVersion(
+      args.expectedVersionHash,
+      current?.versionHash,
+      args.requireExpectedVersionHash,
+    );
+
+    await fs.rename(tempPath, beforeRenameTarget.absolutePath);
+    const directoryHandle = await fs.open(parent, "r").catch(() => null);
+    if (directoryHandle) {
+      try {
+        await directoryHandle.sync();
+      } finally {
+        await directoryHandle.close();
+      }
+    }
+    return contentVersionHash(args.content);
+  } finally {
+    await tempHandle?.close().catch(() => undefined);
+    await fs.rm(tempPath, { force: true }).catch(() => undefined);
+  }
+}
+
 /** Allowed file extensions for write/apply-edit operations. */
 const ALLOWED_WRITE_EXTENSIONS = new Set([
   ".html",
@@ -1166,21 +1427,6 @@ function assertNotBlockedSecretPath(relPath: string): void {
   }
 }
 
-/**
- * Compute a cheap, stable version identifier for a file from its stat: mtime
- * plus size. Not a content hash — it is only meant to detect "did this file
- * change on disk since the caller last read it", the same tradeoff the inline
- * (SQL-backed) workspace provider's versionHash already makes. Returns
- * undefined when the file does not exist (new-file case).
- */
-async function computeVersionHash(
-  absolutePath: string,
-): Promise<string | undefined> {
-  const stat = await fs.stat(absolutePath).catch(() => null);
-  if (!stat) return undefined;
-  return `${stat.mtimeMs}-${stat.size}`;
-}
-
 function countOccurrences(haystack: string, needle: string): number {
   if (!needle) return 0;
   let count = 0;
@@ -1516,6 +1762,18 @@ export async function startDesignConnectBridge(
   // other and boot a frame with another frame's identity. Keep keyed scripts
   // for modern clients while retaining the unkeyed slot for older clients.
   const liveEditBridgeScripts = new Map<string, string>();
+  // Identifies THIS bridge process's in-memory registry, minted fresh every
+  // time the bridge boots. `liveEditBridgeScripts` above only lives in
+  // process memory, so a bridge restart (crash, machine sleep/wake, manual
+  // restart) silently empties it: any screen that registered a bridgeKey
+  // before the restart now gets a 409 "unknown bridge key" from `/live-edit`
+  // even though nothing about that screen actually changed. Echoing this id
+  // on both the registration response and the 409 lets a client tell the two
+  // cases apart — "this exact process never saw my key" (stale/typo, id
+  // matches what it already has cached) vs. "the process restarted since I
+  // registered" (id changed, safe to transparently re-POST `/live-edit-bridge`
+  // and retry) — instead of guessing from the error text or retrying forever.
+  const bridgeInstanceId = crypto.randomBytes(16).toString("hex");
 
   const server = http.createServer(
     (req: IncomingMessage, res: ServerResponse) => {
@@ -1574,6 +1832,7 @@ export async function startDesignConnectBridge(
           ok: true,
           source: manifest.source,
           appFingerprint: designConnectAppFingerprint(manifest),
+          bridgeInstanceId,
         });
         return;
       }
@@ -1628,6 +1887,7 @@ export async function startDesignConnectBridge(
             }
             sendJson(res, 200, {
               ok: true,
+              bridgeInstanceId,
               ...(bridgeKey ? { bridgeKey } : {}),
             });
           } catch (err: unknown) {
@@ -1668,8 +1928,17 @@ export async function startDesignConnectBridge(
               requestedBridgeKey &&
               !editorBridgeScript
             ) {
+              // Machine-readable `code` + echoed `bridgeKey`/`bridgeInstanceId`
+              // let a client distinguish "this bridge process restarted since
+              // I last registered — safe to silently re-POST
+              // /live-edit-bridge and retry" from a genuine caller bug,
+              // instead of string-matching `error` (see bridgeInstanceId's
+              // doc comment above for the full rationale).
               sendJson(res, 409, {
                 ok: false,
+                code: "unknown-bridge-key",
+                bridgeKey: requestedBridgeKey,
+                bridgeInstanceId,
                 error:
                   "The requested live-edit bridge script is not registered. Reload the Design frame to register it again.",
               });
@@ -1794,174 +2063,185 @@ export async function startDesignConnectBridge(
               return;
             }
 
-            await assertPathInside(manifest.rootPath, relPath);
             assertNotBlockedSecretPath(relPath);
-            const absolutePath = path.resolve(manifest.rootPath, relPath);
+            const initialTarget = await resolveSafeBridgeFileTarget(
+              manifest.rootPath,
+              relPath,
+            );
 
             if (pathname === "/read-file") {
               // Read-file: no extension restriction (agents need to read any
               // non-secret file), but the secret-path blocklist above still
               // applies to .env*, *.pem, *.key, id_rsa*, and anything under .git/.
-              let content: string;
-              try {
-                content = await fs.readFile(absolutePath, "utf8");
-              } catch (err: unknown) {
-                const code =
-                  err instanceof Error &&
-                  "code" in err &&
-                  (err as NodeJS.ErrnoException).code;
-                if (code === "ENOENT") {
-                  sendJson(res, 404, { ok: false, error: "file not found" });
-                } else {
-                  sendJson(res, 500, {
-                    ok: false,
-                    error: `read failed: ${err instanceof Error ? err.message : String(err)}`,
-                  });
-                }
+              const snapshot = await readBridgeFileSnapshot(
+                initialTarget.absolutePath,
+              );
+              if (!snapshot) {
+                sendJson(res, 404, { ok: false, error: "file not found" });
                 return;
               }
-              const versionHash = await computeVersionHash(absolutePath);
-              sendJson(res, 200, { ok: true, content, versionHash });
+              sendJson(res, 200, {
+                ok: true,
+                content: snapshot.content,
+                versionHash: snapshot.versionHash,
+              });
               return;
             }
 
             // write-file and apply-edit only allow known text/code extensions.
             assertAllowedExtension(relPath);
 
-            // Optional optimistic-concurrency check: when the caller supplies
-            // expectedVersionHash, compare it against the file's CURRENT hash
-            // before writing. A missing file is treated as no-conflict (new
-            // file case) so first-time writes always succeed.
             const expectedVersionHash =
               typeof body["expectedVersionHash"] === "string"
                 ? body["expectedVersionHash"]
                 : undefined;
-            if (expectedVersionHash !== undefined) {
-              const currentVersionHash = await computeVersionHash(absolutePath);
-              if (
-                currentVersionHash !== undefined &&
-                currentVersionHash !== expectedVersionHash
-              ) {
-                sendJson(res, 409, {
-                  ok: false,
-                  error: "version conflict",
-                  currentVersionHash,
+            const requireExpectedVersionHash =
+              body["requireExpectedVersionHash"] === true;
+            await withBridgeWriteLock(initialTarget.canonicalPath, async () => {
+              const lockedTarget = await resolveSafeBridgeFileTarget(
+                manifest.rootPath,
+                relPath,
+              );
+              if (lockedTarget.canonicalPath !== initialTarget.canonicalPath) {
+                throw new Error(
+                  "Bridge target changed while waiting for the write lock",
+                );
+              }
+              const existing = await readBridgeFileSnapshot(
+                lockedTarget.absolutePath,
+              );
+              assertExpectedBridgeVersion(
+                expectedVersionHash,
+                existing?.versionHash,
+                requireExpectedVersionHash,
+              );
+
+              if (pathname === "/write-file") {
+                const content =
+                  typeof body["content"] === "string"
+                    ? body["content"]
+                    : undefined;
+                if (content === undefined) {
+                  sendJson(res, 400, {
+                    ok: false,
+                    error: "content is required for write-file",
+                  });
+                  return;
+                }
+                const versionHash = await atomicWriteBridgeFile({
+                  rootPath: manifest.rootPath,
+                  relPath,
+                  lockedCanonicalPath: initialTarget.canonicalPath,
+                  content,
+                  expectedVersionHash,
+                  requireExpectedVersionHash,
+                  originalMode: existing?.mode,
+                });
+                sendJson(res, 200, { ok: true, relPath, versionHash });
+                return;
+              }
+
+              // /apply-edit supports either full replace ({content}) or one
+              // exact search-and-replace. Both stay within this file's lock.
+              if (typeof body["content"] === "string") {
+                const versionHash = await atomicWriteBridgeFile({
+                  rootPath: manifest.rootPath,
+                  relPath,
+                  lockedCanonicalPath: initialTarget.canonicalPath,
+                  content: body["content"],
+                  expectedVersionHash,
+                  requireExpectedVersionHash,
+                  originalMode: existing?.mode,
+                });
+                sendJson(res, 200, {
+                  ok: true,
+                  relPath,
+                  method: "replace",
+                  versionHash,
                 });
                 return;
               }
-            }
 
-            if (pathname === "/write-file") {
-              const content =
-                typeof body["content"] === "string"
-                  ? body["content"]
+              const search =
+                typeof body["search"] === "string" ? body["search"] : undefined;
+              const replace =
+                typeof body["replace"] === "string"
+                  ? body["replace"]
                   : undefined;
-              if (content === undefined) {
+              if (search === undefined || replace === undefined) {
                 sendJson(res, 400, {
                   ok: false,
-                  error: "content is required for write-file",
+                  error:
+                    "apply-edit requires either {content} for a full replace, or {search, replace} for a patch",
                 });
                 return;
               }
-              await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-              await fs.writeFile(absolutePath, content, "utf8");
-              const versionHash = await computeVersionHash(absolutePath);
-              sendJson(res, 200, { ok: true, relPath, versionHash });
-              return;
-            }
-
-            // /apply-edit: supports either full replace ({content}) or
-            // search-and-replace ({search, replace}).
-            if (typeof body["content"] === "string") {
-              // Full-file replace via apply-edit — same as write-file but keeps
-              // the endpoint semantically separate for callers that want to
-              // distinguish intent.
-              await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-              await fs.writeFile(
-                absolutePath,
-                body["content"] as string,
-                "utf8",
-              );
-              const versionHash = await computeVersionHash(absolutePath);
-              sendJson(res, 200, {
-                ok: true,
-                relPath,
-                method: "replace",
-                versionHash,
-              });
-              return;
-            }
-
-            const search =
-              typeof body["search"] === "string" ? body["search"] : undefined;
-            const replace =
-              typeof body["replace"] === "string" ? body["replace"] : undefined;
-            if (search === undefined || replace === undefined) {
-              sendJson(res, 400, {
-                ok: false,
-                error:
-                  "apply-edit requires either {content} for a full replace, or {search, replace} for a patch",
-              });
-              return;
-            }
-
-            let existing: string;
-            try {
-              existing = await fs.readFile(absolutePath, "utf8");
-            } catch (err: unknown) {
-              const code =
-                err instanceof Error &&
-                "code" in err &&
-                (err as NodeJS.ErrnoException).code;
-              if (code === "ENOENT") {
+              if (!existing) {
                 sendJson(res, 404, {
                   ok: false,
                   error: "file not found — use write-file to create new files",
                 });
-              } else {
-                sendJson(res, 500, {
+                return;
+              }
+              if (search.length === 0) {
+                sendJson(res, 400, {
                   ok: false,
-                  error: `read failed: ${err instanceof Error ? err.message : String(err)}`,
+                  error: "search string must not be empty",
                 });
+                return;
               }
-              return;
-            }
-
-            if (search.length === 0) {
-              sendJson(res, 400, {
-                ok: false,
-                error: "search string must not be empty",
+              const occurrenceCount = countOccurrences(
+                existing.content,
+                search,
+              );
+              if (occurrenceCount === 0) {
+                sendJson(res, 422, {
+                  ok: false,
+                  error: "search string not found in file",
+                });
+                return;
+              }
+              if (occurrenceCount > 1) {
+                sendJson(res, 422, {
+                  ok: false,
+                  error:
+                    "search string is ambiguous; it appears more than once in the file",
+                });
+                return;
+              }
+              const updated = existing.content.replace(search, replace);
+              const versionHash = await atomicWriteBridgeFile({
+                rootPath: manifest.rootPath,
+                relPath,
+                lockedCanonicalPath: initialTarget.canonicalPath,
+                content: updated,
+                expectedVersionHash,
+                requireExpectedVersionHash,
+                originalMode: existing.mode,
               });
-              return;
-            }
-
-            const occurrenceCount = countOccurrences(existing, search);
-            if (occurrenceCount === 0) {
-              sendJson(res, 422, {
+              sendJson(res, 200, {
+                ok: true,
+                relPath,
+                method: "patch",
+                versionHash,
+              });
+            });
+          } catch (err: unknown) {
+            if (err instanceof BridgePreconditionRequiredError) {
+              sendJson(res, 428, {
                 ok: false,
-                error: "search string not found in file",
+                error: "expectedVersionHash is required",
               });
               return;
             }
-            if (occurrenceCount > 1) {
-              sendJson(res, 422, {
+            if (err instanceof BridgeVersionConflictError) {
+              sendJson(res, 409, {
                 ok: false,
-                error:
-                  "search string is ambiguous; it appears more than once in the file",
+                error: "version conflict",
+                currentVersionHash: err.currentVersionHash,
               });
               return;
             }
-
-            const updated = existing.replace(search, replace);
-            await fs.writeFile(absolutePath, updated, "utf8");
-            const versionHash = await computeVersionHash(absolutePath);
-            sendJson(res, 200, {
-              ok: true,
-              relPath,
-              method: "patch",
-              versionHash,
-            });
-          } catch (err: unknown) {
             sendJson(res, 500, {
               ok: false,
               error: err instanceof Error ? err.message : String(err),
@@ -1990,12 +2270,14 @@ export async function startDesignConnectBridge(
             const proxied = await fetchPreviewProxyResource(
               manifest.devServerUrl,
               targetUrl,
+              previewProxyRequestHeaders(req),
             );
             sendBytes(
               res,
               proxied.status >= 400 ? proxied.status : 200,
               req.method === "HEAD" ? Buffer.alloc(0) : proxied.body,
               proxied.headers,
+              proxied.body.length,
             );
           } catch (err: unknown) {
             sendJson(res, 400, {
@@ -2019,7 +2301,7 @@ export async function startDesignConnectBridge(
     });
   });
 
-  return { server, manifest, bridgeToken, previewToken };
+  return { server, manifest, bridgeToken, previewToken, bridgeInstanceId };
 }
 
 /**
@@ -2163,12 +2445,11 @@ Options:
 
 Element provenance (resolveNodeToFile):
   The design editor can map a selected DOM element back to its source file,
-  line, and React component name when the connected app emits provenance
-  attributes at build time.  Add one of the following to your app's build:
+  line, and component name using one of these provenance sources:
 
-  • @vitejs/plugin-react with jsxDEV enabled (development mode default):
-      Sets data-source-file and data-source-line on each JSX element
-      automatically when using the Babel transform.
+  • React development builds with jsxDEV enabled (the default):
+      Design reads the selected element's development-only Fiber debug stack.
+      React does not emit data-source-* DOM attributes automatically.
 
   • A Babel source plugin (e.g. babel-plugin-react-source or a custom plugin):
       Emits data-source-file="src/Button.tsx" data-source-line="12"
@@ -2177,7 +2458,8 @@ Element provenance (resolveNodeToFile):
   • data-loc="src/Button.tsx:12:4" shorthand attribute (Babel source convention):
       The bridge parses this as { sourceFile, line, column } automatically.
 
-  Without these attributes the editor still works; provenance is simply absent.
+  In production React builds and other runtimes without explicit attributes,
+  the editor still works but exact element provenance may be absent.
   Cross-origin localhost iframes cannot be read regardless of attributes (CSP).`);
 }
 
diff --git a/packages/core/src/cli/recap.io.spec.ts b/packages/core/src/cli/recap.io.spec.ts
index 309bfc82a9..f733bc168b 100644
--- a/packages/core/src/cli/recap.io.spec.ts
+++ b/packages/core/src/cli/recap.io.spec.ts
@@ -543,6 +543,12 @@ describe("runShot — playwright not available", () => {
     const fakePage = {
       goto: vi.fn(async (nextUrl: string) => {
         gotoUrls.push(nextUrl);
+        return {
+          ok: () => true,
+          status: () => 200,
+          url: () => nextUrl,
+          headers: () => ({ "content-type": "text/html; charset=utf-8" }),
+        };
       }),
       waitForLoadState: vi.fn(async () => {}),
       waitForSelector: vi.fn(async () => {}),
diff --git a/packages/core/src/cli/recap.spec.ts b/packages/core/src/cli/recap.spec.ts
index 5de7bafa51..28ed7d459e 100644
--- a/packages/core/src/cli/recap.spec.ts
+++ b/packages/core/src/cli/recap.spec.ts
@@ -1277,7 +1277,12 @@ describe("recap screenshot browser launch", () => {
 describe("recap screenshot capture", () => {
   function createShotPlaywright(screenshotBytes: Buffer[]) {
     const page = {
-      goto: vi.fn(async () => undefined),
+      goto: vi.fn(async () => ({
+        ok: () => true,
+        status: () => 200,
+        url: () => "https://plan.agent-native.com/recaps/plan-abc123",
+        headers: () => ({ "content-type": "text/html; charset=utf-8" }),
+      })),
       waitForLoadState: vi.fn(async () => undefined),
       waitForSelector: vi.fn(async () => undefined),
       waitForTimeout: vi.fn(async () => undefined),
@@ -1386,6 +1391,47 @@ describe("recap screenshot capture", () => {
     }
   });
 
+  it("does not upload a screenshot when the recap page returns an HTTP error", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "an-recap-shot-"));
+    const out = path.join(dir, "recap.png");
+    const { page, importPlaywright } = createShotPlaywright([
+      Buffer.from("png"),
+    ]);
+    page.goto.mockResolvedValueOnce({
+      ok: () => false,
+      status: () => 500,
+      url: () => "https://plan.agent-native.com/recaps/recap-broken",
+      headers: () => ({ "content-type": "text/plain" }),
+    });
+    const writes: string[] = [];
+    const stdout = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        writes.push(String(chunk));
+        return true;
+      });
+
+    try {
+      await runShot(
+        {
+          url: "https://plan.agent-native.com/recaps/recap-broken",
+          out,
+        },
+        importPlaywright,
+      );
+
+      expect(page.screenshot).not.toHaveBeenCalled();
+      expect(JSON.parse(writes.join("").trim())).toMatchObject({
+        ok: false,
+        reason:
+          "recap page returned HTTP 500 while loading https://plan.agent-native.com/recaps/recap-broken",
+      });
+    } finally {
+      stdout.mockRestore();
+      fs.rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
   it("retries oversized screenshots at CSS-pixel scale", async () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "an-recap-shot-"));
     const out = path.join(dir, "recap.png");
diff --git a/packages/core/src/cli/recap.ts b/packages/core/src/cli/recap.ts
index 8c8d572870..f6b61cd553 100644
--- a/packages/core/src/cli/recap.ts
+++ b/packages/core/src/cli/recap.ts
@@ -2987,10 +2987,24 @@ export async function runShot(
       });
     }
     const page = await context.newPage();
-    await page.goto(captureUrl, {
+    const navigationResponse = await page.goto(captureUrl, {
       waitUntil: "domcontentloaded",
       timeout: 45_000,
     });
+    if (!navigationResponse) {
+      throw new Error("recap page did not return an HTTP response");
+    }
+    if (!navigationResponse.ok()) {
+      throw new Error(
+        `recap page returned HTTP ${navigationResponse.status()} while loading ${navigationResponse.url()}`,
+      );
+    }
+    const contentType = navigationResponse.headers()["content-type"] ?? "";
+    if (contentType && !/\btext\/html\b/i.test(contentType)) {
+      throw new Error(
+        `recap page returned unexpected content type ${contentType} while loading ${navigationResponse.url()}`,
+      );
+    }
     await page.waitForLoadState("load", { timeout: 15_000 }).catch(() => {
       // The selectors below are the real readiness signal for screenshots.
       // Some recap pages keep long-lived/background requests open.
diff --git a/packages/core/src/cli/skills.ts b/packages/core/src/cli/skills.ts
index 6f60f00650..2ebf02de01 100644
--- a/packages/core/src/cli/skills.ts
+++ b/packages/core/src/cli/skills.ts
@@ -631,6 +631,20 @@ replace them with copied \`srcdoc\` HTML unless the user explicitly asks for a
 frozen snapshot. To change a state, rerun \`add-localhost-screens\` with the new
 path/query or duplicate the screen and update the copy's URL metadata.
 
+## React Source Writeback
+
+- Use compiler/debug provenance (project-relative file, line, column,
+  component, and runtime multiplicity) to locate React/TSX source. Treat it as
+  evidence, not as permission for a generic AST structural transform.
+- Reparenting, grouping/ungrouping, wrappers, dynamic expressions, repeated
+  \`.map()\` instances, shared components, and cross-file changes go through the
+  coding agent with exact subject/target anchors and their runtime
+  relationship.
+- Before each write, read the file and pass its exact \`versionHash\` to
+  \`write-local-file\` with \`requireExpectedVersionHash: true\`; on conflict,
+  re-read and re-plan. Keep the optimistic preview until HMR/runtime confirms
+  the result. Human write consent remains mandatory and agents cannot grant it.
+
 ## Verification
 
 - \`list-localhost-connections\` returns the expected connection and routes.
diff --git a/packages/core/src/client/AssistantChat.tsx b/packages/core/src/client/AssistantChat.tsx
index a5f518b119..9dff67c322 100644
--- a/packages/core/src/client/AssistantChat.tsx
+++ b/packages/core/src/client/AssistantChat.tsx
@@ -55,9 +55,11 @@ import {
   appendAgentChatContextToMessage,
   formatAgentChatContextItemsForPrompt,
   getAgentChatContextState,
+  isAgentChatSubmitCancelled,
   normalizeAgentChatContextItem,
   publishAgentChatContextItems,
   refreshAgentChatContext,
+  reportAgentChatSubmitResult,
   subscribeAgentChatContext,
   type AgentChatContextItem,
 } from "./agent-chat.js";
@@ -197,6 +199,8 @@ export type AgentRecoveryAction = "continue" | "retry";
 export interface AssistantChatSendOptions {
   trackInRunsTray?: boolean;
   requestMode?: AgentRequestMode;
+  /** Correlates with `AGENT_CHAT_SUBMIT_RESULT_EVENT` — see agent-chat.ts. */
+  submitMessageId?: string;
 }
 
 function createUserMessageRunConfig(
@@ -3651,9 +3655,12 @@ const AssistantChatInner = forwardRef<
       trackInRunsTray = false,
       preserveReconnectAutoRecoveryBudget = false,
       hideUserMessage = false,
+      submitMessageId?: string,
     ) => {
+      if (isAgentChatSubmitCancelled(submitMessageId)) return;
       if (agentEngineConfigured.state === "missing") {
         void ensureAgentEngineReadyForSubmit();
+        reportAgentChatSubmitResult(submitMessageId, false, "missing-engine");
         return;
       }
       if (!preserveReconnectAutoRecoveryBudget) {
@@ -3687,8 +3694,10 @@ const AssistantChatInner = forwardRef<
             ? err.message
             : "Attachment could not be processed.";
         setComposerError(msg);
+        reportAgentChatSubmitResult(submitMessageId, false, "attachment-error");
         return;
       }
+      if (isAgentChatSubmitCancelled(submitMessageId)) return;
       const imageAttachments = createAgentImageAttachments(images);
       const allAttachments = [
         ...(queuedAttachments ?? []),
@@ -3782,6 +3791,11 @@ const AssistantChatInner = forwardRef<
               setComposerError(
                 `"${rejected.name}" makes the message too large to send (combined attachments must be under ${Math.round(MAX_ESTIMATED_BODY_BYTES / 1024 / 1024)} MB). Remove it or use a smaller image.`,
               );
+              reportAgentChatSubmitResult(
+                submitMessageId,
+                false,
+                "attachment-too-large",
+              );
               return;
             }
           }
@@ -3789,6 +3803,7 @@ const AssistantChatInner = forwardRef<
         }
       }
       // ── End body-size guard ──────────────────────────────────────────
+      if (isAgentChatSubmitCancelled(submitMessageId)) return;
       // Snapshot the exec mode at enqueue time when the caller didn't
       // pass an explicit override. Without this, a plan-mode message that
       // sits in the queue runs as 'act' if the user flips the global toggle
@@ -3863,9 +3878,16 @@ const AssistantChatInner = forwardRef<
           } as Parameters<typeof threadRuntime.append>[0]);
         } catch (error) {
           setOptimisticRunning(false);
+          reportAgentChatSubmitResult(submitMessageId, false, "append-failed");
           throw error;
         }
       }
+      // The turn is now either queued behind the active run or already a
+      // visible message — either way it has reached the chat. This is
+      // intentionally reported before the agent's response resolves: a
+      // caller like sendToAgentChatAndConfirm only needs to know the submit
+      // wasn't silently dropped, not whether the run itself later succeeds.
+      reportAgentChatSubmitResult(submitMessageId, true);
       if (submitted.includesContext) {
         updateComposerContextItems(() => []);
       }
@@ -3927,6 +3949,9 @@ const AssistantChatInner = forwardRef<
           undefined,
           false,
           options?.trackInRunsTray === true,
+          false,
+          false,
+          options?.submitMessageId,
         );
       },
       prefillMessage(text: string) {
diff --git a/packages/core/src/client/MultiTabAssistantChat.spec.tsx b/packages/core/src/client/MultiTabAssistantChat.spec.tsx
index 72cd98966b..10969df3db 100644
--- a/packages/core/src/client/MultiTabAssistantChat.spec.tsx
+++ b/packages/core/src/client/MultiTabAssistantChat.spec.tsx
@@ -5,6 +5,7 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
+  cancelAgentChatSubmit,
   requestAgentChatThreadOpen,
   requestAgentTaskOpen,
   sendToAgentChat,
@@ -917,6 +918,7 @@ describe("MultiTabAssistantChat cold-start delivery (Mode B)", () => {
     expect(chatHandleMocks.sendMessage).toHaveBeenCalledWith(
       "Sent before mount",
       undefined,
+      { submitMessageId: expect.any(String) },
     );
   });
 
@@ -939,9 +941,33 @@ describe("MultiTabAssistantChat cold-start delivery (Mode B)", () => {
     expect(chatHandleMocks.sendMessage).toHaveBeenCalledWith(
       "Once only",
       undefined,
+      { submitMessageId: "dup-1" },
     );
   });
 
+  it("drops a pending delivery after its confirmation times out", async () => {
+    threadMocks.activeThreadId = "";
+    await act(async () => {
+      root.render(<MultiTabAssistantChat storageKey="mode-b" />);
+    });
+
+    act(() => {
+      dispatchSubmitChat({
+        message: "Never deliver late",
+        submitMessageId: "cancelled-submit",
+      });
+    });
+    cancelAgentChatSubmit("cancelled-submit");
+
+    threadMocks.activeThreadId = "thread-1";
+    await act(async () => {
+      root.render(<MultiTabAssistantChat storageKey="mode-b" />);
+      await new Promise((resolve) => setTimeout(resolve, 80));
+    });
+
+    expect(chatHandleMocks.sendMessage).not.toHaveBeenCalled();
+  });
+
   it("replays an open-thread request sent before the lazy panel mounted", async () => {
     threadMocks.threads = [
       ...threadMocks.threads,
diff --git a/packages/core/src/client/MultiTabAssistantChat.tsx b/packages/core/src/client/MultiTabAssistantChat.tsx
index bccf0434b8..f23a842589 100644
--- a/packages/core/src/client/MultiTabAssistantChat.tsx
+++ b/packages/core/src/client/MultiTabAssistantChat.tsx
@@ -30,8 +30,10 @@ import {
   claimAgentChatSubmit,
   drainBufferedAgentChatOpenRequests,
   drainBufferedAgentChatSubmits,
+  isAgentChatSubmitCancelled,
   normalizeAgentChatContextItem,
   parseSubmitChatMessage,
+  reportAgentChatSubmitResult,
   type AgentChatContextItem,
 } from "./agent-chat.js";
 import { agentNativePath, appPath } from "./api-path.js";
@@ -79,6 +81,8 @@ interface PendingSend {
   submit: boolean;
   trackInRunsTray?: boolean;
   requestMode?: "act" | "plan";
+  /** Correlates with `AGENT_CHAT_SUBMIT_RESULT_EVENT` — see agent-chat.ts. */
+  submitMessageId?: string;
 }
 
 /**
@@ -93,14 +97,18 @@ interface PendingDelivery {
 
 /** The single path that hands a queued send to a mounted chat ref. */
 function deliverPendingSend(ref: AssistantChatHandle, send: PendingSend): void {
+  if (isAgentChatSubmitCancelled(send.submitMessageId)) return;
   if (!send.submit) {
     ref.prefillMessage(send.message);
     return;
   }
-  if (send.trackInRunsTray || send.requestMode) {
+  if (send.trackInRunsTray || send.requestMode || send.submitMessageId) {
     ref.sendMessage(send.message, send.images, {
       ...(send.trackInRunsTray ? { trackInRunsTray: true } : {}),
       ...(send.requestMode ? { requestMode: send.requestMode } : {}),
+      ...(send.submitMessageId
+        ? { submitMessageId: send.submitMessageId }
+        : {}),
     });
   } else {
     ref.sendMessage(send.message, send.images);
@@ -1767,6 +1775,7 @@ export function MultiTabAssistantChat({
         background,
         submit,
         images,
+        submitMessageId,
       } = parsed;
       const requestedTabId = parsed.tabId;
       const requestMode =
@@ -1777,7 +1786,14 @@ export function MultiTabAssistantChat({
       if (openSidebar !== false && !background) {
         window.dispatchEvent(new CustomEvent("agent-panel:open"));
       }
-      if (postMessageSubmissionsDisabled) return;
+      if (postMessageSubmissionsDisabled) {
+        reportAgentChatSubmitResult(
+          submitMessageId,
+          false,
+          "composer-disabled",
+        );
+        return;
+      }
 
       // Plan mode is sent as request metadata by the chat adapter. Keep the
       // user-visible message clean so mode instructions never enter history.
@@ -1791,9 +1807,11 @@ export function MultiTabAssistantChat({
         submit,
         ...(background ? { trackInRunsTray: true } : {}),
         ...(requestMode ? { requestMode } : {}),
+        ...(submitMessageId ? { submitMessageId } : {}),
       };
 
       const sendToTab = (threadId: string) => {
+        if (isAgentChatSubmitCancelled(submitMessageId)) return;
         // If a model override was specified, apply it only if we recognize it
         if (model) {
           const matchedGroup = availableModels.find((g) =>
@@ -1826,8 +1844,17 @@ export function MultiTabAssistantChat({
 
       if (newTab) {
         const previousTabId = activeThreadIdRef.current;
-        createThread(requestedTabId).then((newId) => {
-          if (newId) {
+        createThread(requestedTabId)
+          .then((newId) => {
+            if (isAgentChatSubmitCancelled(submitMessageId)) return;
+            if (!newId) {
+              reportAgentChatSubmitResult(
+                submitMessageId,
+                false,
+                "thread-create-failed",
+              );
+              return;
+            }
             newThreadIds.current.add(newId);
             if (background) {
               mountedTabsRef.current.add(newId);
@@ -1842,8 +1869,14 @@ export function MultiTabAssistantChat({
             if (background && previousTabId) {
               switchThreadState(previousTabId);
             }
-          }
-        });
+          })
+          .catch(() => {
+            reportAgentChatSubmitResult(
+              submitMessageId,
+              false,
+              "thread-create-failed",
+            );
+          });
       } else {
         const currentTabId = activeThreadIdRef.current;
         if (currentTabId) {
@@ -1901,6 +1934,7 @@ export function MultiTabAssistantChat({
     const active = activeThreadIdRef.current;
     const remaining: PendingDelivery[] = [];
     for (const delivery of pendingDeliveries.current) {
+      if (isAgentChatSubmitCancelled(delivery.send.submitMessageId)) continue;
       const threadId = delivery.threadId ?? active ?? null;
       const ref = threadId ? chatRefs.current.get(threadId) : null;
       if (threadId && ref) {
diff --git a/packages/core/src/client/agent-chat.spec.ts b/packages/core/src/client/agent-chat.spec.ts
index ea1577dc6c..53cc9c58e8 100644
--- a/packages/core/src/client/agent-chat.spec.ts
+++ b/packages/core/src/client/agent-chat.spec.ts
@@ -3,7 +3,29 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 // We need to set up a minimal window/postMessage before importing
 const parentPostMessageSpy = vi.fn();
 const selfPostMessageSpy = vi.fn();
-const dispatchEventSpy = vi.fn();
+const windowListeners = new Map<
+  string,
+  Set<EventListenerOrEventListenerObject>
+>();
+const addEventListenerSpy = vi.fn(
+  (type: string, listener: EventListenerOrEventListenerObject) => {
+    const listeners = windowListeners.get(type) ?? new Set();
+    listeners.add(listener);
+    windowListeners.set(type, listeners);
+  },
+);
+const removeEventListenerSpy = vi.fn(
+  (type: string, listener: EventListenerOrEventListenerObject) => {
+    windowListeners.get(type)?.delete(listener);
+  },
+);
+const dispatchEventSpy = vi.fn((event: Event) => {
+  for (const listener of windowListeners.get(event.type) ?? []) {
+    if (typeof listener === "function") listener(event);
+    else listener.handleEvent(event);
+  }
+  return true;
+});
 const fetchSpy = vi.fn(() =>
   Promise.resolve({ ok: true, status: 200, text: () => Promise.resolve("") }),
 );
@@ -21,30 +43,39 @@ vi.mock("./mcp-app-host.js", () => ({
   sendMcpAppHostMessage: sendMcpAppHostMessageMock,
 }));
 
-vi.stubGlobal("window", {
+const windowStub = {
   parent: { postMessage: parentPostMessageSpy },
-  addEventListener: vi.fn(),
+  addEventListener: addEventListenerSpy,
+  removeEventListener: removeEventListenerSpy,
   dispatchEvent: dispatchEventSpy,
   postMessage: selfPostMessageSpy,
+  setTimeout: (...args: Parameters<typeof setTimeout>) => setTimeout(...args),
+  clearTimeout: (timer: ReturnType<typeof setTimeout>) => clearTimeout(timer),
   location: {
     origin: "http://localhost:3000",
     pathname: "/",
     search: "",
   },
-});
+};
+vi.stubGlobal("window", windowStub);
 vi.stubGlobal("fetch", fetchSpy);
 
 const {
   _resetAgentChatContextForTests,
+  _resetAgentChatSubmitBufferForTests,
   addContextToAgentChat,
+  claimAgentChatSubmit,
   clearAgentChatContext,
+  drainBufferedAgentChatSubmits,
   formatAgentChatContextItemsForPrompt,
   generateTabId,
   insertAgentComposerReference,
   listAgentChatContext,
   normalizeAgentComposerReference,
   removeAgentChatContextItem,
+  reportAgentChatSubmitResult,
   sendToAgentChat,
+  sendToAgentChatAndConfirm,
   setAgentChatContextItem,
   setContextToAgentChat,
 } = await import("./agent-chat.js");
@@ -75,6 +106,7 @@ function createMemoryStorage(): Storage {
 
 describe("sendToAgentChat", () => {
   beforeEach(() => {
+    windowListeners.clear();
     frameState.inBuilderFrame = false;
     (window as unknown as { parent: unknown }).parent = {
       postMessage: parentPostMessageSpy,
@@ -99,6 +131,7 @@ describe("sendToAgentChat", () => {
     window.sessionStorage?.clear();
     _resetEmbedAuthForTests();
     _resetAgentChatContextForTests();
+    _resetAgentChatSubmitBufferForTests();
   });
 
   afterEach(() => {
@@ -479,6 +512,115 @@ describe("sendToAgentChat", () => {
     expect(id1).not.toBe(id2);
   });
 
+  it("confirms a local submit after the receiving chat accepts it", async () => {
+    vi.useFakeTimers();
+    const resultPromise = sendToAgentChatAndConfirm({
+      message: "apply these annotations",
+      submit: true,
+      chatTarget: "local",
+    });
+
+    vi.advanceTimersByTime(0);
+    const payload = selfPostMessageSpy.mock.calls.at(-1)?.[0];
+    expect(payload?.data?.submitMessageId).toEqual(expect.any(String));
+    reportAgentChatSubmitResult(payload.data.submitMessageId, true);
+
+    await expect(resultPromise).resolves.toMatchObject({ delivered: true });
+  });
+
+  it("preserves an explicit local rejection reason", async () => {
+    vi.useFakeTimers();
+    const resultPromise = sendToAgentChatAndConfirm({
+      message: "apply these annotations",
+      submit: true,
+      chatTarget: "local",
+    });
+    vi.advanceTimersByTime(0);
+    const submitMessageId = selfPostMessageSpy.mock.calls.at(-1)?.[0]?.data
+      ?.submitMessageId as string;
+    reportAgentChatSubmitResult(submitMessageId, false, "missing-engine");
+
+    await expect(resultPromise).resolves.toMatchObject({
+      delivered: false,
+      reason: "missing-engine",
+    });
+  });
+
+  it("rejects non-local confirmation targets without sending", async () => {
+    const result = await sendToAgentChatAndConfirm({
+      message: "route to a parent chat",
+      submit: true,
+    });
+
+    expect(result).toMatchObject({
+      delivered: false,
+      reason: "unsupported-target",
+    });
+    expect(parentPostMessageSpy).not.toHaveBeenCalled();
+    expect(selfPostMessageSpy).not.toHaveBeenCalled();
+  });
+
+  it("short-circuits safely without window", async () => {
+    vi.stubGlobal("window", undefined);
+    const result = await sendToAgentChatAndConfirm({
+      message: "server render",
+      submit: true,
+      chatTarget: "local",
+    });
+    vi.stubGlobal("window", windowStub);
+
+    expect(result).toMatchObject({
+      delivered: false,
+      reason: "no-window",
+    });
+    expect(parentPostMessageSpy).not.toHaveBeenCalled();
+    expect(selfPostMessageSpy).not.toHaveBeenCalled();
+  });
+
+  it("tombstones a timed-out submit so a late receiver cannot claim it", async () => {
+    vi.useFakeTimers();
+    const resultPromise = sendToAgentChatAndConfirm(
+      {
+        message: "do not arrive late",
+        submit: true,
+        chatTarget: "local",
+      },
+      { timeoutMs: 5 },
+    );
+    vi.advanceTimersByTime(0);
+    const submitMessageId = selfPostMessageSpy.mock.calls.at(-1)?.[0]?.data
+      ?.submitMessageId as string;
+
+    vi.advanceTimersByTime(5);
+    await expect(resultPromise).resolves.toMatchObject({
+      delivered: false,
+      reason: "timeout",
+    });
+    expect(drainBufferedAgentChatSubmits()).toEqual([]);
+    expect(claimAgentChatSubmit(submitMessageId)).toBe(false);
+  });
+
+  it("keeps the default confirmation alive beyond the replay buffer TTL", async () => {
+    vi.useFakeTimers();
+    let settled = false;
+    const resultPromise = sendToAgentChatAndConfirm({
+      message: "wait for the lazy panel",
+      submit: true,
+      chatTarget: "local",
+    }).then((result) => {
+      settled = true;
+      return result;
+    });
+    vi.advanceTimersByTime(8001);
+    await flushMicrotasks();
+    expect(settled).toBe(false);
+
+    const submitMessageId = selfPostMessageSpy.mock.calls.at(-1)?.[0]?.data
+      ?.submitMessageId as string;
+    reportAgentChatSubmitResult(submitMessageId, true);
+    await expect(resultPromise).resolves.toMatchObject({ delivered: true });
+  });
+
   it("keeps legacy context helper names as aliases", () => {
     expect(setContextToAgentChat).toBe(setAgentChatContextItem);
     expect(addContextToAgentChat).toBe(setAgentChatContextItem);
diff --git a/packages/core/src/client/agent-chat.ts b/packages/core/src/client/agent-chat.ts
index 31213de79f..7b85149069 100644
--- a/packages/core/src/client/agent-chat.ts
+++ b/packages/core/src/client/agent-chat.ts
@@ -96,6 +96,11 @@ export interface AgentChatMessage {
    * focusing it or opening the sidebar. The message runs silently.
    */
   background?: boolean;
+  /**
+   * Stable id used to deduplicate a submit and correlate it with
+   * {@link AGENT_CHAT_SUBMIT_RESULT_EVENT}. Auto-generated if omitted.
+   */
+  submitMessageId?: string;
 }
 
 export interface AgentChatContextItem {
@@ -210,6 +215,45 @@ export const AGENT_CHAT_INSERT_REFERENCE_EVENT =
   "agentNative:insert-composer-reference";
 const AGENT_PANEL_PREPARE_EVENT = "agent-panel:prepare";
 
+/**
+ * Fired once a submitted turn's fate is known: `delivered: true` once the
+ * receiving AssistantChat has actually committed the turn (added it to the
+ * visible thread, independent of whether the agent's response later
+ * succeeds), or `delivered: false` when it was rejected before ever
+ * appearing — e.g. no LLM/agent engine configured. Callers that must know
+ * whether their submit truly landed (rather than fire-and-forget) should use
+ * {@link sendToAgentChatAndConfirm} instead of listening for this directly.
+ */
+export const AGENT_CHAT_SUBMIT_RESULT_EVENT = "agentNative.chatSubmitResult";
+
+export interface AgentChatSubmitResult {
+  submitMessageId: string;
+  delivered: boolean;
+  reason?: string;
+}
+
+/** Report a submit's definitive outcome so `sendToAgentChatAndConfirm` (or any
+ * other correlated listener) can resolve. No-ops without a submitMessageId or
+ * a window (SSR). */
+export function reportAgentChatSubmitResult(
+  submitMessageId: string | undefined,
+  delivered: boolean,
+  reason?: string,
+): void {
+  if (
+    !submitMessageId ||
+    cancelledSubmitIds.has(submitMessageId) ||
+    typeof window === "undefined"
+  ) {
+    return;
+  }
+  window.dispatchEvent(
+    new CustomEvent<AgentChatSubmitResult>(AGENT_CHAT_SUBMIT_RESULT_EVENT, {
+      detail: { submitMessageId, delivered, reason },
+    }),
+  );
+}
+
 let agentChatContextState: AgentChatContextState = {
   items: [],
   updatedAt: 0,
@@ -262,6 +306,7 @@ interface BufferedSelfSubmit {
 const SELF_SUBMIT_BUFFER_TTL_MS = 8000;
 const bufferedSelfSubmits: BufferedSelfSubmit[] = [];
 const claimedSubmitIds = new Set<string>();
+const cancelledSubmitIds = new Set<string>();
 
 interface BufferedOpenRequest extends BufferedAgentChatOpenRequest {
   at: number;
@@ -289,6 +334,28 @@ function bufferSelfSubmit(data: Record<string, unknown>): void {
   bufferedSelfSubmits.push({ id, data, at: now });
 }
 
+/**
+ * Permanently tombstone a submit for this page lifetime and remove its
+ * cold-start replay. A confirmation timeout must be terminal: callers may
+ * retry while preserving their own state, so the original submit cannot be
+ * allowed to appear later when a lazy panel or thread ref finally mounts.
+ */
+export function cancelAgentChatSubmit(id: string | undefined): void {
+  if (!id) return;
+  cancelledSubmitIds.add(id);
+  claimedSubmitIds.add(id);
+  for (let index = bufferedSelfSubmits.length - 1; index >= 0; index -= 1) {
+    if (bufferedSelfSubmits[index]?.id === id) {
+      bufferedSelfSubmits.splice(index, 1);
+    }
+  }
+}
+
+/** Whether a confirmed-submit timeout has made this delivery terminal. */
+export function isAgentChatSubmitCancelled(id: string | undefined): boolean {
+  return Boolean(id && cancelledSubmitIds.has(id));
+}
+
 function pruneOpenRequestBuffer(now: number): void {
   for (let i = bufferedOpenRequests.length - 1; i >= 0; i -= 1) {
     if (now - bufferedOpenRequests[i].at > OPEN_REQUEST_BUFFER_TTL_MS) {
@@ -328,6 +395,7 @@ export function drainBufferedAgentChatSubmits(): Array<
 /** Claim a submit; false if already handled. Idless submits always pass. */
 export function claimAgentChatSubmit(id: string | undefined): boolean {
   if (!id) return true;
+  if (cancelledSubmitIds.has(id)) return false;
   if (claimedSubmitIds.has(id)) return false;
   claimedSubmitIds.add(id);
   return true;
@@ -353,6 +421,7 @@ export function claimAgentChatOpenRequest(id: unknown): boolean {
 export function _resetAgentChatSubmitBufferForTests(): void {
   bufferedSelfSubmits.length = 0;
   claimedSubmitIds.clear();
+  cancelledSubmitIds.clear();
   bufferedOpenRequests.length = 0;
   claimedOpenRequestIds.clear();
 }
@@ -896,7 +965,7 @@ export function sendToAgentChat(opts: AgentChatMessage): string {
     return tabId;
   }
 
-  const submitMessageId = generateSubmitMessageId();
+  const submitMessageId = opts.submitMessageId ?? generateSubmitMessageId();
   const payload = {
     type: AGENT_CHAT_MESSAGE_TYPE,
     data: {
@@ -977,6 +1046,101 @@ export function sendToAgentChat(opts: AgentChatMessage): string {
   return tabId;
 }
 
+// Must exceed SELF_SUBMIT_BUFFER_TTL_MS. Otherwise confirmation can time out
+// while its replay is still eligible to mount and deliver later.
+const DEFAULT_SUBMIT_CONFIRM_TIMEOUT_MS = SELF_SUBMIT_BUFFER_TTL_MS + 2000;
+
+export interface SendToAgentChatAndConfirmResult {
+  tabId: string;
+  /** True once the message actually became a visible turn in the chat. */
+  delivered: boolean;
+  /** Set when `delivered` is false: "missing-engine", "timeout", etc. */
+  reason?: string;
+}
+
+/**
+ * Like {@link sendToAgentChat}, but resolves once the submit's fate is known
+ * instead of firing and forgetting. Use this whenever the caller must decide
+ * whether to keep/restore its own state on failure (e.g. a draw/annotate
+ * overlay that should not discard the user's work unless the message actually
+ * reached the chat) — see the `AGENT_CHAT_SUBMIT_RESULT_EVENT` contract.
+ * This acknowledgement is intentionally limited to submitted, non-code
+ * messages with `chatTarget: "local"`; parent-frame and MCP host chats use
+ * different delivery protocols and return `unsupported-target` here.
+ *
+ * Resolves `delivered: false` if the receiving chat explicitly rejects the
+ * submit (e.g. no LLM/agent engine configured) OR if no result arrives within
+ * `timeoutMs` — a silently-stuck submit (panel never mounts, thread never
+ * gets a ref, message type not handled by this build) must fail the same way
+ * an explicit rejection does, since the caller cannot otherwise tell the
+ * difference between "still in flight" and "dropped."
+ */
+export function sendToAgentChatAndConfirm(
+  opts: Omit<AgentChatMessage, "submitMessageId">,
+  options?: { timeoutMs?: number },
+): Promise<SendToAgentChatAndConfirmResult> {
+  const tabId = opts.tabId ?? generateTabId();
+  if (typeof window === "undefined") {
+    return Promise.resolve({ tabId, delivered: false, reason: "no-window" });
+  }
+  // Confirmation is deliberately a same-window/local-chat contract. Parent
+  // frames, Builder code chat, and MCP host relays have independent protocols
+  // and cannot answer this window-local CustomEvent acknowledgement.
+  if (
+    opts.chatTarget !== "local" ||
+    opts.type === "code" ||
+    opts.requiresCode === true ||
+    opts.submit === false
+  ) {
+    return Promise.resolve({
+      tabId,
+      delivered: false,
+      reason: "unsupported-target",
+    });
+  }
+
+  const submitMessageId = generateSubmitMessageId();
+  const timeoutMs = Math.max(
+    0,
+    options?.timeoutMs ?? DEFAULT_SUBMIT_CONFIRM_TIMEOUT_MS,
+  );
+
+  return new Promise<SendToAgentChatAndConfirmResult>((resolve) => {
+    let settled = false;
+    let timer: number | undefined;
+    const cleanup = () => {
+      window.removeEventListener(
+        AGENT_CHAT_SUBMIT_RESULT_EVENT,
+        onResult as EventListener,
+      );
+      if (timer !== undefined) window.clearTimeout(timer);
+    };
+    const finish = (delivered: boolean, reason?: string, cancel = false) => {
+      if (settled) return;
+      settled = true;
+      if (cancel) cancelAgentChatSubmit(submitMessageId);
+      cleanup();
+      resolve({ tabId, delivered, reason });
+    };
+    const onResult = (event: Event) => {
+      const detail = (event as CustomEvent<AgentChatSubmitResult>).detail;
+      if (!detail || detail.submitMessageId !== submitMessageId) return;
+      finish(detail.delivered, detail.reason);
+    };
+
+    window.addEventListener(
+      AGENT_CHAT_SUBMIT_RESULT_EVENT,
+      onResult as EventListener,
+    );
+    timer = window.setTimeout(() => finish(false, "timeout", true), timeoutMs);
+    try {
+      sendToAgentChat({ ...opts, tabId, submitMessageId });
+    } catch {
+      finish(false, "send-failed", true);
+    }
+  });
+}
+
 /**
  * Add or replace a keyed context nugget in the active agent chat composer.
  * The context is not submitted until the user sends the prompt.
diff --git a/packages/core/src/client/chat/index.ts b/packages/core/src/client/chat/index.ts
index 305371e68e..6653da2943 100644
--- a/packages/core/src/client/chat/index.ts
+++ b/packages/core/src/client/chat/index.ts
@@ -59,7 +59,15 @@ export {
 } from "../code-agent-chat-adapter.js";
 export * from "./connectors.js";
 export * from "./runtime.js";
-export { sendToAgentChat, type AgentChatMessage } from "../agent-chat.js";
+export {
+  sendToAgentChat,
+  sendToAgentChatAndConfirm,
+  reportAgentChatSubmitResult,
+  AGENT_CHAT_SUBMIT_RESULT_EVENT,
+  type AgentChatMessage,
+  type AgentChatSubmitResult,
+  type SendToAgentChatAndConfirmResult,
+} from "../agent-chat.js";
 export { useAgentChatGenerating } from "../use-agent-chat.js";
 export { useSendToAgentChat } from "../use-send-to-agent-chat.js";
 export {
diff --git a/packages/core/src/client/extensions/EmbeddedExtension.spec.ts b/packages/core/src/client/extensions/EmbeddedExtension.spec.ts
new file mode 100644
index 0000000000..ac8bdc7dca
--- /dev/null
+++ b/packages/core/src/client/extensions/EmbeddedExtension.spec.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import { sanitizeSlotContextForPostMessage } from "./EmbeddedExtension.js";
+
+/**
+ * Regression test for a DataCloneError bug: EmbeddedExtension's onLoad
+ * handler and its "context changed" effect both posted the raw slot
+ * `context` object straight into `window.postMessage`. Real slot contexts
+ * (e.g. Design's DesignExtensionSlotContext) carry live callback functions
+ * the host uses internally (onShaderFillPreview, onShaderFillApplied, ...).
+ * `postMessage` uses the structured clone algorithm, which throws
+ * `DataCloneError: ... could not be cloned` on any function-valued
+ * property — so every extension iframe load logged a console error and
+ * never actually received the context update. The fix round-trips the
+ * context through JSON (matching the `contextJson` string already computed
+ * for the effect's dependency array) before posting it.
+ */
+describe("sanitizeSlotContextForPostMessage", () => {
+  it("drops function-valued properties", () => {
+    const sanitized = sanitizeSlotContextForPostMessage({
+      designId: "abc123",
+      onShaderFillPreview: (_descriptor: unknown, _css: string) => {},
+      onShaderFillPreviewClear: () => {},
+    });
+    expect(sanitized).toEqual({ designId: "abc123" });
+    expect("onShaderFillPreview" in sanitized).toBe(false);
+  });
+
+  it("preserves plain nested data untouched", () => {
+    const sanitized = sanitizeSlotContextForPostMessage({
+      designId: "abc123",
+      screens: [{ id: "f1", filename: "index.html" }],
+      selectedElement: { selector: "#hero", nodeId: "n1" },
+      zoom: 1.5,
+    });
+    expect(sanitized).toEqual({
+      designId: "abc123",
+      screens: [{ id: "f1", filename: "index.html" }],
+      selectedElement: { selector: "#hero", nodeId: "n1" },
+      zoom: 1.5,
+    });
+  });
+
+  it("returns an empty object for null/undefined context", () => {
+    expect(sanitizeSlotContextForPostMessage(null)).toEqual({});
+    expect(sanitizeSlotContextForPostMessage(undefined)).toEqual({});
+  });
+
+  it("fails safe to an empty object on a circular reference", () => {
+    const circular: Record<string, unknown> = { designId: "abc123" };
+    circular.self = circular;
+    expect(sanitizeSlotContextForPostMessage(circular)).toEqual({});
+  });
+});
diff --git a/packages/core/src/client/extensions/EmbeddedExtension.tsx b/packages/core/src/client/extensions/EmbeddedExtension.tsx
index 03102dbed2..7f164c895f 100644
--- a/packages/core/src/client/extensions/EmbeddedExtension.tsx
+++ b/packages/core/src/client/extensions/EmbeddedExtension.tsx
@@ -85,6 +85,31 @@ function serializeChatValue(value: unknown): string | undefined {
   }
 }
 
+/**
+ * Slot contexts (e.g. Design's `DesignExtensionSlotContext`) commonly carry
+ * live callback functions alongside plain data — the host component uses
+ * those callbacks itself, but `window.postMessage` uses the structured clone
+ * algorithm, which throws a `DataCloneError` on any function-valued property
+ * (see MDN's postMessage docs). Round-tripping through JSON drops functions
+ * (and other non-cloneable values like symbols) the same way
+ * `JSON.stringify` already silently omits them, producing a payload that's
+ * safe to post. Exported so a test can verify functions never reach the
+ * iframe instead of only reading the code.
+ */
+export function sanitizeSlotContextForPostMessage(
+  context: Record<string, unknown> | null | undefined,
+): Record<string, unknown> {
+  try {
+    return JSON.parse(JSON.stringify(context ?? {}));
+  } catch {
+    // Circular reference or other non-serializable shape — fail safe to an
+    // empty context rather than letting postMessage throw and skip every
+    // other message this handler sends in the same tick (theme update,
+    // ready signal).
+    return {};
+  }
+}
+
 export interface EmbeddedExtensionProps {
   extensionId: string;
   /** Slot identifier passed via the iframe URL so the extension runtime knows it's
@@ -243,8 +268,16 @@ export function EmbeddedExtension({
   useEffect(() => {
     const win = iframeRef.current?.contentWindow;
     if (!win) return;
+    // Post the JSON-round-tripped context, not the raw `context` object —
+    // slot contexts (e.g. Design's DesignExtensionSlotContext) carry live
+    // callback functions the host uses internally, and postMessage's
+    // structured clone throws a DataCloneError on any function-valued
+    // property. See sanitizeSlotContextForPostMessage's docblock.
     win.postMessage(
-      { type: "agent-native-slot-context", context: context ?? {} },
+      {
+        type: "agent-native-slot-context",
+        context: sanitizeSlotContextForPostMessage(context),
+      },
       "*",
     );
   }, [contextJson]);
@@ -400,7 +433,10 @@ export function EmbeddedExtension({
         style={{ width: "100%", border: 0, height, display: "block" }}
         onLoad={() => {
           iframeRef.current?.contentWindow?.postMessage(
-            { type: "agent-native-slot-context", context: context ?? {} },
+            {
+              type: "agent-native-slot-context",
+              context: sanitizeSlotContextForPostMessage(context),
+            },
             "*",
           );
           // Re-assert theme once the iframe document is live. The src bakes in
diff --git a/packages/core/src/client/index.ts b/packages/core/src/client/index.ts
index 6b136bca52..413b43f1d5 100644
--- a/packages/core/src/client/index.ts
+++ b/packages/core/src/client/index.ts
@@ -19,6 +19,9 @@ export {
   requestAgentChatThreadOpen,
   requestAgentTaskOpen,
   sendToAgentChat,
+  sendToAgentChatAndConfirm,
+  reportAgentChatSubmitResult,
+  AGENT_CHAT_SUBMIT_RESULT_EVENT,
   parseSubmitChatMessage,
   setAgentChatContextItem,
   setContextToAgentChat,
@@ -33,6 +36,8 @@ export {
   type AgentChatContextSetOptions,
   type AgentChatContextState,
   type AgentChatMessage,
+  type AgentChatSubmitResult,
+  type SendToAgentChatAndConfirmResult,
   type AgentComposerReference,
   type AgentComposerReferenceInsertOptions,
   type AgentComposerReferenceInsertPayload,
diff --git a/packages/core/src/client/rich-markdown-editor/useCollabReconcile.concurrent.spec.ts b/packages/core/src/client/rich-markdown-editor/useCollabReconcile.concurrent.spec.ts
index 8113951b55..cdcef92dca 100644
--- a/packages/core/src/client/rich-markdown-editor/useCollabReconcile.concurrent.spec.ts
+++ b/packages/core/src/client/rich-markdown-editor/useCollabReconcile.concurrent.spec.ts
@@ -55,6 +55,7 @@ interface Captured {
   editor: Editor | null;
   emitted: string[];
   setContentCalls: number;
+  registerEmitted?: (markdown: string) => boolean;
 }
 
 function makeHarness() {
@@ -100,6 +101,7 @@ function makeHarness() {
       },
     });
     guardsRef.current = guards;
+    captured.registerEmitted = guards.registerEmitted;
 
     return React.createElement("div", null);
   }
@@ -270,6 +272,64 @@ describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
     expect(getEditorMarkdown(captured.editor!)).toBe("# V1 content");
   });
 
+  it("applies a newer authoritative revert that matches a prior mount-time emission", async () => {
+    const { captured, Harness } = makeHarness();
+
+    render(root, Harness, {
+      value: "# V1 content",
+      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+    });
+    await flush();
+    render(root, Harness, {
+      value: "# V2 content",
+      contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+    });
+    await flush();
+    expect(getEditorMarkdown(captured.editor!)).toBe("# V2 content");
+
+    // A collab mount/schema-normalization transaction can emit the old V1
+    // bytes even though the authoritative apply has already moved the editor
+    // to V2. Record that echo without focusing/typing in the editor.
+    expect(captured.registerEmitted?.("# V1 content")).toBe(true);
+
+    render(root, Harness, {
+      value: "# V1 content",
+      contentUpdatedAt: "2024-01-01T00:00:03.000Z",
+    });
+    await flush();
+
+    expect(getEditorMarkdown(captured.editor!)).toBe("# V1 content");
+  });
+
+  it("ignores local-looking editor updates until collaborative seeding completes", async () => {
+    const results: boolean[] = [];
+
+    function Probe() {
+      const editor = useEditor({
+        extensions: createRichMarkdownExtensions({ dialect: "gfm" }),
+        content: "",
+      });
+      const fakeYdoc = { clientID: 1, getXmlFragment: () => ({ length: 0 }) };
+      const guards = useCollabReconcile({
+        editor,
+        ydoc: fakeYdoc as never,
+        collabSynced: false,
+        value: "authoritative content",
+        contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+        editable: true,
+      });
+      if (editor && results.length === 0) {
+        results.push(guards.shouldIgnoreUpdate(editor.state.tr));
+      }
+      return React.createElement("div", null);
+    }
+
+    act(() => root.render(React.createElement(Probe)));
+    await flush();
+
+    expect(results).toEqual([true]);
+  });
+
   it("refuses to persist an empty doc in collab mode (registerEmitted guard)", async () => {
     // Directly exercise the guard contract: in collab mode an empty markdown
     // string must not be registered/persisted (would clobber stored content
diff --git a/packages/core/src/client/rich-markdown-editor/useCollabReconcile.ts b/packages/core/src/client/rich-markdown-editor/useCollabReconcile.ts
index d9a389e123..2d1d19f3e2 100644
--- a/packages/core/src/client/rich-markdown-editor/useCollabReconcile.ts
+++ b/packages/core/src/client/rich-markdown-editor/useCollabReconcile.ts
@@ -385,6 +385,8 @@ export function useCollabReconcile({
       const editorUnchangedSinceApply =
         lastAppliedSerializedRef.current !== null &&
         currentMarkdown === lastAppliedSerializedRef.current;
+      const typingRecently =
+        editor.isFocused && Date.now() - lastTypedAtRef.current < 1500;
 
       // Doc-equivalence skip. Never re-apply content the editor already
       // represents — comparing by DOC EQUIVALENCE, not raw strings/timestamps:
@@ -407,11 +409,15 @@ export function useCollabReconcile({
       //      `<p>` → `&lt;p&gt;` → `&amp;lt;p&amp;gt;` escalation.
       if (
         currentMarkdown === normalizedValue ||
-        value === lastEmittedRef.current ||
-        // A stale-but-recent echo of our own (possibly partial) save — applying
-        // it would clobber the freshly-typed tail. External edits never match.
-        recentEmittedRef.current.includes(value) ||
-        recentEmittedRef.current.includes(normalizedValue) ||
+        (typingRecently &&
+          // A stale echo of our own (possibly partial) save while the user is
+          // actively typing would clobber the fresh tail. Outside active
+          // typing, the same bytes can be a deliberate newer external revert
+          // (history restore / provider conflict choice) and must be allowed
+          // through even if mount-time normalization emitted them.
+          (value === lastEmittedRef.current ||
+            recentEmittedRef.current.includes(value) ||
+            recentEmittedRef.current.includes(normalizedValue))) ||
         (editorUnchangedSinceApply &&
           (value === lastAppliedValueRef.current ||
             normalizedValue === lastAppliedSerializedRef.current))
@@ -442,8 +448,6 @@ export function useCollabReconcile({
       // for non-idempotent input, fight every keystroke. Newer external content
       // retries so it still lands once they pause; older-or-equal content is a
       // stale poll and is dropped outright while focused.
-      const typingRecently =
-        editor.isFocused && Date.now() - lastTypedAtRef.current < 1500;
       if (typingRecently) {
         if (externalNewer) {
           retry = setTimeout(() => apply(deferred), 700);
@@ -549,6 +553,13 @@ export function useCollabReconcile({
 
   const shouldIgnoreUpdate = (transaction: Transaction): boolean => {
     if (!editable || isSettingContentRef.current) return true;
+    // Collaboration can emit schema/default-paragraph transactions while the
+    // persisted Y.Doc is still loading and before the authoritative value has
+    // seeded/reconciled. Never let those transient pre-seed updates reach an
+    // app's local mirror or autosave path (Content serializes an empty paragraph
+    // as `<empty-block/>`, which is non-empty text and bypasses the generic
+    // registerEmitted empty-string guard).
+    if (collab && !seededRef.current) return true;
     if (transaction.getMeta(RICH_MARKDOWN_PROGRAMMATIC_TRANSACTION)) {
       return true;
     }
diff --git a/packages/core/src/collab/awareness-store.spec.ts b/packages/core/src/collab/awareness-store.spec.ts
index e5d36ea3ee..ad00e79bd8 100644
--- a/packages/core/src/collab/awareness-store.spec.ts
+++ b/packages/core/src/collab/awareness-store.spec.ts
@@ -89,6 +89,7 @@ import {
   _resetAwarenessStoreForTests,
   deleteAwarenessRow,
   loadAwarenessRows,
+  loadAwarenessRowsStrict,
   upsertAwarenessRow,
 } from "./awareness-store.js";
 
@@ -167,5 +168,8 @@ describe("awareness-store", () => {
     ).resolves.toBeUndefined();
     await expect(deleteAwarenessRow("doc-6", 1)).resolves.toBeUndefined();
     await expect(loadAwarenessRows("doc-6")).resolves.toEqual([]);
+    await expect(loadAwarenessRowsStrict("doc-6")).rejects.toThrow(
+      "db not configured",
+    );
   });
 });
diff --git a/packages/core/src/collab/awareness-store.ts b/packages/core/src/collab/awareness-store.ts
index 3f1c350596..5d1f71c3fb 100644
--- a/packages/core/src/collab/awareness-store.ts
+++ b/packages/core/src/collab/awareness-store.ts
@@ -149,23 +149,34 @@ export async function loadAwarenessRows(
   now: number = Date.now(),
 ): Promise<AwarenessEntry[]> {
   try {
-    await ensureTable();
-    const client = getDbExec();
-    const { rows } = await client.execute({
-      sql: `SELECT client_id, state, last_seen FROM _collab_awareness
-            WHERE doc_id = ? AND last_seen >= ?`,
-      args: [docId, now - ROW_TTL_MS],
-    });
-    return rows.map((row: any) => ({
-      clientId: Number(row.client_id),
-      state: String(row.state),
-      lastSeen: Number(row.last_seen),
-    }));
+    return await loadAwarenessRowsStrict(docId, now);
   } catch {
     return [];
   }
 }
 
+/**
+ * Strict awareness read for safety-critical callers that must distinguish
+ * "no active participants" from "presence storage could not be read."
+ */
+export async function loadAwarenessRowsStrict(
+  docId: string,
+  now: number = Date.now(),
+): Promise<AwarenessEntry[]> {
+  await ensureTable();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT client_id, state, last_seen FROM _collab_awareness
+          WHERE doc_id = ? AND last_seen >= ?`,
+    args: [docId, now - ROW_TTL_MS],
+  });
+  return rows.map((row: any) => ({
+    clientId: Number(row.client_id),
+    state: String(row.state),
+    lastSeen: Number(row.last_seen),
+  }));
+}
+
 async function maybePurge(docId: string, now: number): Promise<void> {
   const last = _lastPurges.get(docId) ?? 0;
   if (now - last < PURGE_INTERVAL_MS) return;
diff --git a/packages/core/src/collab/client.registry.spec.tsx b/packages/core/src/collab/client.registry.spec.tsx
index e320269897..1485656c94 100644
--- a/packages/core/src/collab/client.registry.spec.tsx
+++ b/packages/core/src/collab/client.registry.spec.tsx
@@ -26,16 +26,23 @@ import {
   type UseCollaborativeDocResult,
 } from "./client.js";
 
-/** Minimal EventSource stand-in so the shared transport never opens SSE. */
+/**
+ * Minimal EventSource stand-in so the shared transport never opens a real
+ * SSE connection. Tracks every constructed instance so tests can push
+ * synthetic push events without going through a real EventSource.
+ */
 class FakeEventSource {
   static readonly CONNECTING = 0;
   static readonly OPEN = 1;
   static readonly CLOSED = 2;
+  static instances: FakeEventSource[] = [];
   readyState = FakeEventSource.CONNECTING;
   onopen: (() => void) | null = null;
   onerror: (() => void) | null = null;
   onmessage: ((message: { data: string }) => void) | null = null;
-  constructor(readonly url: string) {}
+  constructor(readonly url: string) {
+    FakeEventSource.instances.push(this);
+  }
   close(): void {
     this.readyState = FakeEventSource.CLOSED;
   }
@@ -64,11 +71,13 @@ function makeFetchMock() {
 function Probe({
   docId,
   onResult,
+  user,
 }: {
   docId: string | null;
   onResult: (result: UseCollaborativeDocResult) => void;
+  user?: { name: string; email: string; color: string };
 }) {
-  const result = useCollaborativeDoc({ docId });
+  const result = useCollaborativeDoc({ docId, user });
   onResult(result);
   return null;
 }
@@ -92,6 +101,7 @@ describe("useCollaborativeDoc connection registry", () => {
   beforeEach(() => {
     vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
     vi.stubGlobal("EventSource", FakeEventSource);
+    FakeEventSource.instances = [];
     vi.useFakeTimers();
     _resetCollabDocRegistryForTests();
     _resetSyncTransportRegistryForTests();
@@ -252,4 +262,73 @@ describe("useCollaborativeDoc connection registry", () => {
     expect(_collabDocRegistrySizeForTests()).toBe(1);
     expect(result?.ydoc?.isDestroyed).toBe(false);
   });
+
+  it("does not re-broadcast local awareness state when a REMOTE awareness event arrives (no storm)", async () => {
+    const { mock } = makeFetchMock();
+    vi.stubGlobal("fetch", mock);
+
+    mount(
+      <Probe
+        docId="doc-1"
+        onResult={() => {}}
+        user={{ name: "Local", email: "local@example.com", color: "#111" }}
+      />,
+    );
+    // Flush the initial state fetch + first poll cycle, then let the local
+    // `setUser` awareness push (origin "local") land.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+      await vi.advanceTimersByTimeAsync(200);
+    });
+
+    const source = FakeEventSource.instances.at(-1);
+    expect(source).toBeTruthy();
+    source!.onopen?.();
+
+    const awarenessPostsBefore = mock.mock.calls.filter(
+      ([input, init]) =>
+        String(input).includes("/awareness") &&
+        (init as RequestInit | undefined)?.method === "POST",
+    ).length;
+
+    // Simulate a REMOTE peer's cursor move arriving over the shared SSE
+    // transport — this is what `applyAwarenessEvent` receives, and it emits
+    // `awareness.emit("change", [changes, "remote"])` after reconciling.
+    await act(async () => {
+      source!.onmessage?.({
+        data: JSON.stringify({
+          source: "awareness",
+          type: "awareness-change",
+          docId: "doc-1",
+          states: [
+            {
+              clientId: 999_001,
+              state: JSON.stringify({
+                user: {
+                  name: "Remote",
+                  email: "remote@example.com",
+                  color: "#222",
+                },
+                cursor: { x: 0.5, y: 0.5 },
+              }),
+            },
+          ],
+        }),
+      });
+      // Past the 150ms fast-awareness-push throttle window.
+      await vi.advanceTimersByTimeAsync(200);
+    });
+
+    const awarenessPostsAfter = mock.mock.calls.filter(
+      ([input, init]) =>
+        String(input).includes("/awareness") &&
+        (init as RequestInit | undefined)?.method === "POST",
+    ).length;
+
+    // A remote-originated awareness change must not cause THIS client to
+    // re-broadcast its own (unchanged) state — otherwise every peer's cursor
+    // move would fan out into an extra POST from every other connected
+    // client (an awareness storm that gets worse as more people join).
+    expect(awarenessPostsAfter).toBe(awarenessPostsBefore);
+  });
 });
diff --git a/packages/core/src/collab/client.ts b/packages/core/src/collab/client.ts
index c79772a63a..9a4f8f09e5 100644
--- a/packages/core/src/collab/client.ts
+++ b/packages/core/src/collab/client.ts
@@ -579,7 +579,10 @@ class CollabDocConnection {
     this.awareness.setLocalStateField("visible", !isDocumentHidden());
   }
 
-  private handleAwarenessChange = (): void => {
+  private handleAwarenessChange = (
+    _changes?: { added: number[]; updated: number[]; removed: number[] },
+    origin?: unknown,
+  ): void => {
     const users: CollabUser[] = [];
     let hasAgent = false;
     this.awareness.getStates().forEach((state, clientId) => {
@@ -616,12 +619,20 @@ class CollabDocConnection {
       this.setSnapshot({ activeUsers, agentPresent: hasAgent });
     }
 
-    // Fast awareness push: whenever awareness changes (e.g. cursor moves,
-    // setPresence() calls), schedule a throttled POST so peers receive updates
-    // at ~150ms instead of waiting for the next poll cycle. Only active once a
+    // Fast awareness push: whenever OUR OWN awareness state changes (e.g.
+    // cursor moves, setPresence() calls), schedule a throttled POST so peers
+    // receive updates at ~150ms instead of waiting for the next poll cycle.
+    // Gated on origin === "local": this listener also fires for remote
+    // awareness changes (poll/SSE call `awareness.emit("change", [changes,
+    // "remote"])` after reconciling incoming states — see
+    // applyAwarenessEvent/poll above). Without the origin check, every
+    // peer's cursor move would also re-trigger THIS client to re-broadcast
+    // its own unchanged state, turning one person moving their mouse into
+    // O(n) redundant POSTs from every other connected client (an awareness
+    // storm that gets worse as more people join the doc). Only active once a
     // local user identity has been published (matches the previous per-hook
     // gating on `user`). The poll cycle remains the authoritative baseline.
-    if (this.lastSetUser && !this.disposed) {
+    if (this.lastSetUser && origin === "local" && !this.disposed) {
       scheduleAwarenessPush(
         this.baseUrl,
         this.docId,
diff --git a/packages/core/src/collab/index.ts b/packages/core/src/collab/index.ts
index 6f1f408fd0..74dd334dc1 100644
--- a/packages/core/src/collab/index.ts
+++ b/packages/core/src/collab/index.ts
@@ -126,6 +126,10 @@ export {
   type AwarenessEntry,
   type AwarenessChangeEvent,
 } from "./awareness.js";
+export {
+  loadAwarenessRows,
+  loadAwarenessRowsStrict,
+} from "./awareness-store.js";
 
 // Presence kit
 export {
diff --git a/packages/core/src/collab/recent-edits.spec.ts b/packages/core/src/collab/recent-edits.spec.ts
index 5ab975b039..1109e91b59 100644
--- a/packages/core/src/collab/recent-edits.spec.ts
+++ b/packages/core/src/collab/recent-edits.spec.ts
@@ -50,6 +50,57 @@ describe("appendRecentEdit", () => {
     appendRecentEdit(original, { descriptor: { kind: "doc" }, at: 2 });
     expect(original).toHaveLength(1);
   });
+
+  it("truncates an oversized quote so a caller forgetting to trim can't blow up the awareness payload", () => {
+    const hugeQuote = "x".repeat(50_000);
+    const [entry] = appendRecentEdit(undefined, {
+      descriptor: { kind: "text", quote: hugeQuote },
+      at: 1,
+    });
+    expect(
+      (entry.descriptor as { kind: "text"; quote: string }).quote.length,
+    ).toBe(500);
+  });
+
+  it("truncates an oversized selector and each oversized path entry", () => {
+    const huge = "a".repeat(10_000);
+    const [selectorEntry] = appendRecentEdit(undefined, {
+      descriptor: { kind: "selector", selector: huge },
+      at: 1,
+    });
+    expect(
+      (selectorEntry.descriptor as { kind: "selector"; selector: string })
+        .selector.length,
+    ).toBe(500);
+
+    const [pathsEntry] = appendRecentEdit(undefined, {
+      descriptor: { kind: "paths", paths: [huge, "short.path"] },
+      at: 1,
+    });
+    const paths = (pathsEntry.descriptor as { kind: "paths"; paths: string[] })
+      .paths;
+    expect(paths[0]!.length).toBe(500);
+    expect(paths[1]).toBe("short.path");
+  });
+
+  it("truncates an oversized label", () => {
+    const [entry] = appendRecentEdit(undefined, {
+      descriptor: { kind: "doc" },
+      label: "y".repeat(2_000),
+      at: 1,
+    });
+    expect(entry.label!.length).toBe(500);
+  });
+
+  it("leaves short descriptors and labels untouched", () => {
+    const [entry] = appendRecentEdit(undefined, {
+      descriptor: { kind: "text", quote: "hello world" },
+      label: "Edited",
+      at: 1,
+    });
+    expect(entry.descriptor).toEqual({ kind: "text", quote: "hello world" });
+    expect(entry.label).toBe("Edited");
+  });
 });
 
 describe("collectRecentEdits", () => {
diff --git a/packages/core/src/collab/recent-edits.ts b/packages/core/src/collab/recent-edits.ts
index b379cf85e5..9b73d53c18 100644
--- a/packages/core/src/collab/recent-edits.ts
+++ b/packages/core/src/collab/recent-edits.ts
@@ -21,6 +21,7 @@ import {
   RECENT_EDIT_TTL_MS,
   type AttributedRecentEdit,
   type RecentEdit,
+  type RecentEditDescriptor,
 } from "@agent-native/toolkit/collab-ui";
 import { useEffect, useRef, useState } from "react";
 
@@ -34,16 +35,78 @@ export {
   type RecentEditDescriptor,
 } from "@agent-native/toolkit/collab-ui";
 
+/**
+ * Hard cap on any single string carried in a recentEdits entry (quote,
+ * selector, path segment, label). Callers are expected to pass short
+ * excerpts already (existing call sites trim to 80–120 chars for a "what
+ * changed" snippet), but this is the ring's own size ceiling — a caller that
+ * forgets to trim (e.g. passing a whole paragraph/document as `quote`) must
+ * not blow up the awareness payload every connected client receives on the
+ * fast-push path, nor the `_collab_awareness` SQL row it gets mirrored into.
+ */
+const RECENT_EDIT_STRING_MAX = 500;
+
+function truncateString(value: string): string {
+  return value.length > RECENT_EDIT_STRING_MAX
+    ? value.slice(0, RECENT_EDIT_STRING_MAX)
+    : value;
+}
+
+function truncateDescriptor(
+  descriptor: RecentEditDescriptor,
+): RecentEditDescriptor {
+  // The union's last member (`{ kind: string; [key: string]: unknown }`) is an
+  // open-ended catch-all whose `kind` is a plain `string`, so a `switch` on
+  // `descriptor.kind` can't discriminate it away from the literal-kind
+  // members for the compiler — every property still type-checks as
+  // `unknown`. Read/write through an untyped view instead and lean on
+  // runtime checks; the return value is cast back to the real type below.
+  const d = descriptor as Record<string, unknown> & { kind: string };
+  if (d.kind === "text" && typeof d.quote === "string") {
+    return { ...d, quote: truncateString(d.quote) } as RecentEditDescriptor;
+  }
+  if (d.kind === "selector" && typeof d.selector === "string") {
+    return {
+      ...d,
+      selector: truncateString(d.selector),
+    } as RecentEditDescriptor;
+  }
+  if (d.kind === "paths" && Array.isArray(d.paths)) {
+    return {
+      ...d,
+      paths: d.paths.map((p) =>
+        typeof p === "string" ? truncateString(p) : p,
+      ),
+    } as RecentEditDescriptor;
+  }
+  if (d.kind === "doc") {
+    return descriptor;
+  }
+  // Open-ended shape — trim any string-valued fields defensively without
+  // knowing their names.
+  const trimmed: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(d)) {
+    trimmed[key] = typeof value === "string" ? truncateString(value) : value;
+  }
+  return trimmed as RecentEditDescriptor;
+}
+
 /**
  * Append an edit to a recentEdits ring, keeping the newest
- * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array.
+ * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array. Descriptor
+ * strings and the label are truncated to {@link RECENT_EDIT_STRING_MAX}
+ * characters as a defensive cap on the awareness payload size.
  */
 export function appendRecentEdit(
   existing: RecentEdit[] | undefined,
   edit: RecentEdit,
 ): RecentEdit[] {
   const ring = Array.isArray(existing) ? existing.slice() : [];
-  ring.push(edit);
+  ring.push({
+    ...edit,
+    descriptor: truncateDescriptor(edit.descriptor),
+    label: edit.label ? truncateString(edit.label) : edit.label,
+  });
   if (ring.length > RECENT_EDITS_MAX) {
     ring.splice(0, ring.length - RECENT_EDITS_MAX);
   }
diff --git a/packages/core/src/index.browser.ts b/packages/core/src/index.browser.ts
index ad3c0421f9..298f2b1227 100644
--- a/packages/core/src/index.browser.ts
+++ b/packages/core/src/index.browser.ts
@@ -10,6 +10,7 @@ export {
   refreshAgentChatContext,
   removeAgentChatContextItem,
   sendToAgentChat,
+  sendToAgentChatAndConfirm,
   setAgentChatContextItem,
   setContextToAgentChat,
   isEmbedMcpChatBridgeActive,
diff --git a/packages/core/src/server/agent-chat-plugin.ts b/packages/core/src/server/agent-chat-plugin.ts
index d17f4e7655..2b5165b244 100644
--- a/packages/core/src/server/agent-chat-plugin.ts
+++ b/packages/core/src/server/agent-chat-plugin.ts
@@ -8561,10 +8561,34 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
       // covers the initial dispatch (a connected client is polling the claim),
       // but a server-chained CONTINUATION handoff has no foreground watching
       // it: if the dispatch is lost after the successor row was inserted, the
-      // row would sit at dispatch_mode='background' forever and the turn hangs
-      // silently. This sweep reaps such rows into a loud, attributable error
-      // (`background_worker_never_started`) that the client renders, instead
-      // of an idle spinner. Cheap: one indexed-ish query per 2-min window.
+      // row would otherwise sit at dispatch_mode='background' forever and the
+      // turn hangs silently. `chainServerDrivenContinuation` (production-agent.ts)
+      // leaves exactly such a row behind — status='running', dispatch_mode=
+      // 'background', `dispatch_payload` intact — when it exhausts its own
+      // dispatch retry budget, instead of erroring it immediately. This sweep
+      // gives that row a real chance to RECOVER: within
+      // `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS` of its original
+      // `started_at` it redispatches the handoff (same `_process-run`
+      // processor, same persisted payload); past that bound it falls back to
+      // the existing loud reap (`background_worker_never_started`) so a
+      // genuinely dead handoff still fails loud, never silently. A
+      // redispatch is always safe to attempt — even a duplicate or
+      // late-arriving one — because the worker's `claimBackgroundRun` atomic
+      // CAS (status='running' AND dispatch_mode='background' -> 'background-
+      // processing') is the sole gate on actual execution; a row that was
+      // already claimed or already reaped by a concurrent path just loses the
+      // CAS and no-ops. Cheap: one indexed-ish query per 2-min window.
+      //
+      // THREE-SITE INVARIANT (keep in lockstep): this sweep only ever sees the
+      // deferred successor because the ~1s client poll in
+      // `getActiveRunForThreadAsync` (run-manager.ts) skips its own
+      // `reapUnclaimedBackgroundRun` while the row is within the redispatch
+      // bound (`shouldRedispatchUnclaimedBackgroundRun`). If a future change
+      // makes that client poll reap deferred successors at the 25s grace
+      // again, this sweep will almost never win the race for connected clients.
+      // Do not edit one site without the others (producer:
+      // chainServerDrivenContinuation in production-agent.ts; guard:
+      // run-manager.ts; recovery actor: here).
       (() => {
         let lastSweep = 0;
         const SWEEP_INTERVAL_MS = 2 * 60 * 1000;
@@ -8577,22 +8601,85 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
 
             (async () => {
               const {
-                listUnclaimedBackgroundRunIds,
+                listUnclaimedBackgroundRunRows,
                 reapUnclaimedBackgroundRun,
+                updateRunHeartbeat,
+                shouldRedispatchUnclaimedBackgroundRun,
               } = await import("../agent/run-store.js");
-              let runIds: string[];
+              const { resolveAgentChatProcessRunDispatchPath } =
+                await import("../agent/durable-background.js");
+              const { fireInternalDispatch } =
+                await import("./self-dispatch.js");
+              let rows: { id: string; startedAt: number }[];
               try {
-                runIds = await listUnclaimedBackgroundRunIds();
+                rows = await listUnclaimedBackgroundRunRows();
               } catch {
                 return; // Table may not exist yet on first boot
               }
-              for (const staleRunId of runIds) {
+              for (const row of rows) {
                 try {
-                  const reaped = await reapUnclaimedBackgroundRun(staleRunId);
+                  if (shouldRedispatchUnclaimedBackgroundRun(row)) {
+                    // Bump liveness BEFORE attempting the redispatch so the
+                    // row doesn't look freshly-stale again the instant this
+                    // tick returns — best-effort, the CAS is what actually
+                    // matters for correctness, not this timing.
+                    await updateRunHeartbeat(row.id).catch(() => {});
+                    try {
+                      // DELIBERATE: this marker omits `continuationCount`.
+                      // `chainServerDrivenContinuation` (production-agent.ts)
+                      // reads `backgroundRunMarker.continuationCount` to
+                      // compute `backgroundContinuationCount`, defaulting to 0
+                      // when absent — so a chunk recovered here always starts
+                      // a fresh nested-dispatch segment at depth 0, regardless
+                      // of how deep the chain was before this sweep picked it
+                      // up. This is what makes the sweep a genuine CHAIN
+                      // BREAK, not just a retry: this redispatch fires from an
+                      // unrelated, timer-driven invocation rather than from
+                      // inside the prior chain's own live execution, so
+                      // starting its nested-depth count over at 0 here is
+                      // correct — see `MAX_NESTED_SELF_DISPATCH_DEPTH` in
+                      // production-agent.ts for why nested depth is bounded
+                      // and how this reset keeps a long turn progressing past
+                      // Netlify's undocumented self-invocation loop-protection
+                      // limit instead of dying at it. Do not "fix" this by
+                      // adding `continuationCount` back without re-reading
+                      // that constant's doc comment.
+                      await fireInternalDispatch({
+                        path: resolveAgentChatProcessRunDispatchPath(),
+                        taskId: row.id,
+                        body: {
+                          internalContinuation: true,
+                          [AGENT_CHAT_BACKGROUND_RUN_FIELD]: {
+                            runId: row.id,
+                            payloadRef: true,
+                          },
+                        },
+                        awaitResponse: true,
+                        responseTimeoutMs: 15_000,
+                      });
+                      console.error(
+                        "[agent-chat] redispatched unclaimed background run (handoff recovery):",
+                        row.id,
+                      );
+                    } catch (redispatchErr) {
+                      console.error(
+                        "[agent-chat] unclaimed background run redispatch attempt failed (retrying until the redispatch bound, then reaping):",
+                        row.id,
+                        redispatchErr instanceof Error
+                          ? redispatchErr.message
+                          : redispatchErr,
+                      );
+                    }
+                    continue;
+                  }
+                  // Redispatch bound exceeded — this handoff is not
+                  // recovering. Fall back to the pre-existing loud reap so
+                  // the turn fails loud instead of retrying forever.
+                  const reaped = await reapUnclaimedBackgroundRun(row.id);
                   if (reaped) {
                     console.error(
-                      "[agent-chat] swept unclaimed background run (handoff lost):",
-                      staleRunId,
+                      "[agent-chat] swept unclaimed background run (handoff lost, redispatch bound exceeded):",
+                      row.id,
                     );
                   }
                 } catch {
diff --git a/packages/core/src/server/builder-design-systems.spec.ts b/packages/core/src/server/builder-design-systems.spec.ts
index 57f856f7b5..6d3226f575 100644
--- a/packages/core/src/server/builder-design-systems.spec.ts
+++ b/packages/core/src/server/builder-design-systems.spec.ts
@@ -53,6 +53,41 @@ describe("Builder design-system helpers", () => {
     expect(files.map((file) => file.name)).toEqual(["ok.css", "also-ok.css"]);
   });
 
+  it("base64-decodes a binary .fig file instead of UTF-8-mangling it (regression: .fig upload silently corrupted binary bytes)", () => {
+    // A real .fig is a zip container -- PK\x03\x04 magic, per the fig-writer
+    // spike's own README -- and its bytes are NOT valid UTF-8 (many bytes
+    // are >= 0x80 with no valid continuation sequence). Round-tripping
+    // arbitrary binary through TextEncoder().encode() (the old
+    // default-and-only path) corrupts it; through base64 + Buffer.from it
+    // must come back byte-identical.
+    const binaryBytes = new Uint8Array([
+      0x50, 0x4b, 0x03, 0x04, 0x00, 0xff, 0x80, 0x81, 0xfe, 0x7f, 0x10, 0x20,
+    ]);
+    const base64Content = Buffer.from(binaryBytes).toString("base64");
+
+    const files = buildBuilderDesignSystemIndexFiles({
+      codeFiles: [
+        {
+          filename: "spike-output.fig",
+          content: base64Content,
+          encoding: "base64",
+        },
+      ],
+    });
+
+    expect(files).toHaveLength(1);
+    expect(files[0].name).toBe("spike-output.fig");
+    expect(files[0].mimeType).toBe("application/octet-stream");
+    expect(Array.from(files[0].data)).toEqual(Array.from(binaryBytes));
+  });
+
+  it("still treats codeFiles as UTF-8 text by default when encoding is omitted (no behavior change for existing text callers)", () => {
+    const files = buildBuilderDesignSystemIndexFiles({
+      codeFiles: [{ filename: "tokens.css", content: ":root{--x:1}" }],
+    });
+    expect(new TextDecoder().decode(files[0].data)).toBe(":root{--x:1}");
+  });
+
   it("creates a local proxy that preserves the Builder DSI reference", () => {
     const fields = createBuilderDesignSystemProxyFields({
       result: {
diff --git a/packages/core/src/server/builder-design-systems.ts b/packages/core/src/server/builder-design-systems.ts
index 3fc01af452..eeb3bcc943 100644
--- a/packages/core/src/server/builder-design-systems.ts
+++ b/packages/core/src/server/builder-design-systems.ts
@@ -16,6 +16,21 @@ export interface BuilderDesignSystemCodeFileInput {
   filename: string;
   content: string;
   mimeType?: string;
+  /**
+   * How `content` is encoded. Defaults to `"utf8"` (existing behavior,
+   * unchanged for every current text-file caller). Pass `"base64"` for
+   * binary files -- most importantly `.fig` (a zip/kiwi binary container,
+   * never valid UTF-8 text). Without this, a `.fig` upload silently
+   * corrupts: `mimeTypeForBuilderDesignSystemFilename` already special-cases
+   * `.fig` as `application/octet-stream`, but the actual byte pipeline ran
+   * every file through `TextEncoder().encode()` regardless, which mangles
+   * any byte >= 0x80 in a binary-as-string payload (or, if the caller
+   * base64-encoded first with no decode step here, stores the literal
+   * base64 text instead of the decoded binary). Callers sending `.fig`/PDF/
+   * other binary bytes must base64-encode `content` and set this to
+   * `"base64"`.
+   */
+  encoding?: "utf8" | "base64";
 }
 
 export interface BuildBuilderDesignSystemIndexFilesOptions {
@@ -184,9 +199,20 @@ export function buildBuilderDesignSystemIndexFiles({
   const files: BuilderDesignSystemIndexFile[] = [];
   let totalBytes = 0;
 
-  function pushTextFile(filename: string, content: string, mimeType?: string) {
+  function pushFile(
+    filename: string,
+    content: string,
+    mimeType?: string,
+    encoding?: "utf8" | "base64",
+  ) {
     const normalizedName = filename.replace(/^\/+/, "") || "code.txt";
-    const data = encoder.encode(content);
+    // `.fig`/PDF/other binary payloads must round-trip through base64, not
+    // UTF-8 -- TextEncoder().encode() on a binary-as-string payload mangles
+    // any byte >= 0x80. See BuilderDesignSystemCodeFileInput.encoding.
+    const data =
+      encoding === "base64"
+        ? new Uint8Array(Buffer.from(content, "base64"))
+        : encoder.encode(content);
     if (data.byteLength === 0) return;
     if (totalBytes + data.byteLength > maxTotalCodeBytes) return;
     totalBytes += data.byteLength;
@@ -201,7 +227,7 @@ export function buildBuilderDesignSystemIndexFiles({
   }
 
   if (designMd?.trim()) {
-    pushTextFile(
+    pushFile(
       designMdFilename?.trim() || "design.md",
       designMd,
       "text/markdown",
@@ -209,7 +235,7 @@ export function buildBuilderDesignSystemIndexFiles({
   }
 
   for (const file of (codeFiles ?? []).slice(0, maxCodeFiles)) {
-    pushTextFile(file.filename, file.content, file.mimeType);
+    pushFile(file.filename, file.content, file.mimeType, file.encoding);
   }
 
   return files;
diff --git a/packages/core/src/server/ssr-handler.spec.ts b/packages/core/src/server/ssr-handler.spec.ts
index 572cf0baee..82fdce6c72 100644
--- a/packages/core/src/server/ssr-handler.spec.ts
+++ b/packages/core/src/server/ssr-handler.spec.ts
@@ -9,6 +9,7 @@ import {
   AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER,
   AGENT_NATIVE_SOCIAL_IMAGE_PATH,
 } from "../shared/social-meta.js";
+import { registerErrorCaptureProvider } from "./capture-error.js";
 import { getRequestUserEmail } from "./request-context.js";
 import {
   createH3SSRHandler,
@@ -100,6 +101,37 @@ describe("createH3SSRHandler", () => {
     expect(mocks.requestHandler).toHaveBeenCalledTimes(1);
   });
 
+  it("captures SSR exceptions with request context before returning a safe 500", async () => {
+    const error = new Error("render failed");
+    const provider = vi.fn();
+    const unregister = registerErrorCaptureProvider(
+      "ssr-handler-test",
+      provider,
+    );
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    mocks.requestHandler.mockImplementationOnce(async () => {
+      throw error;
+    });
+    const handler = createH3SSRHandler(() => ({})) as any;
+
+    try {
+      const response = await handler(createEvent("/recaps/recap_test"));
+
+      expect(response.status).toBe(500);
+      expect(provider).toHaveBeenCalledWith(error, {
+        route: "/recaps/recap_test",
+        method: "GET",
+        userAgent: undefined,
+        tags: { renderMode: "anonymous-public", surface: "ssr" },
+      });
+    } finally {
+      consoleError.mockRestore();
+      unregister();
+    }
+  });
+
   it("strips APP_BASE_PATH from React Router lazy route manifest paths", async () => {
     process.env.APP_BASE_PATH = "/dispatch";
     const handler = createH3SSRHandler(() => ({})) as any;
diff --git a/packages/core/src/server/ssr-handler.ts b/packages/core/src/server/ssr-handler.ts
index 251392cc23..4c42122bd2 100644
--- a/packages/core/src/server/ssr-handler.ts
+++ b/packages/core/src/server/ssr-handler.ts
@@ -34,6 +34,7 @@ import {
   getAppBasePathFromViteEnv,
   stripAppBasePath as canonicalStripAppBasePath,
 } from "./app-base-path.js";
+import { captureError } from "./capture-error.js";
 import { runWithRequestContext } from "./request-context.js";
 import { getSentryClientConfigScript } from "./sentry-config.js";
 
@@ -391,6 +392,12 @@ export function createH3SSRHandler(getBuild: () => Promise<unknown> | unknown) {
       // that aid reconnaissance attacks. In dev we surface the message text
       // so devtools shows something useful; in prod we return a bare 500.
       console.error("[ssr-handler] SSR error:", err);
+      captureError(err, {
+        route: p,
+        method: event.req.method,
+        userAgent: event.req.headers.get("user-agent") ?? undefined,
+        tags: { renderMode: "anonymous-public", surface: "ssr" },
+      });
       const isProd = process.env.NODE_ENV === "production";
       const body = isProd
         ? "Internal Server Error"
diff --git a/scripts/i18n-raw-literal-baseline.txt b/scripts/i18n-raw-literal-baseline.txt
index 632ffe48a8..422ab84a85 100644
--- a/scripts/i18n-raw-literal-baseline.txt
+++ b/scripts/i18n-raw-literal-baseline.txt
@@ -9,6 +9,7 @@ templates/clips/app/components/workspace/notifications-list.tsx|["formatDate"],
 templates/design/app/components/design/DesignCanvas.tsx|handle ? [
 templates/design/app/components/design/FusionAppBanner.tsx|Publish failed
 templates/design/app/components/design/FusionAppBanner.tsx|Push failed
+templates/design/app/components/design/bridge/editor-chrome.bridge.ts|parentRect.right || clientY
 templates/design/app/components/design/code-workbench/commands.ts|Command failed
 templates/design/app/components/design/code-workbench/commands.ts|Could not save file
 templates/design/app/components/design/code-workbench/editor/EditorTabs.tsx|Could not save file
@@ -20,6 +21,7 @@ templates/design/app/components/design/code-workbench/search/search-engine.ts|In
 templates/design/app/components/design/code-workbench/store.tsx|Could not read file
 templates/design/app/components/design/code-workbench/workspace/localhost-provider.ts|File changed on disk since it was last read
 templates/design/app/components/design/code-workbench/workspace/types.ts|` or `localhost:
+templates/design/app/components/design/edit-panel/effects-properties.tsx|, elementKey: string, nextLayers: readonly Pick
 templates/design/app/components/design/multi-screen/screen-content-cache.ts|, existingScreenIds: ReadonlySet
 templates/design/app/components/design/multi-screen/screen-content-cache.ts|, liveScreenIds: ReadonlySet
 templates/design/app/pages/design-editor/pending-edits.ts|, primaryInfo?: Pick
diff --git a/skills/visual-edit/SKILL.md b/skills/visual-edit/SKILL.md
index 79437cb8f0..9f2875e166 100644
--- a/skills/visual-edit/SKILL.md
+++ b/skills/visual-edit/SKILL.md
@@ -205,6 +205,20 @@ replace them with copied `srcdoc` HTML unless the user explicitly asks for a
 frozen snapshot. To change a state, rerun `add-localhost-screens` with the new
 path/query or duplicate the screen and update the copy's URL metadata.
 
+## React Source Writeback
+
+- Use compiler/debug provenance (project-relative file, line, column,
+  component, and runtime multiplicity) to locate React/TSX source. Treat it as
+  evidence, not as permission for a generic AST structural transform.
+- Reparenting, grouping/ungrouping, wrappers, dynamic expressions, repeated
+  `.map()` instances, shared components, and cross-file changes go through the
+  coding agent with exact subject/target anchors and their runtime
+  relationship.
+- Before each write, read the file and pass its exact `versionHash` to
+  `write-local-file` with `requireExpectedVersionHash: true`; on conflict,
+  re-read and re-plan. Keep the optimistic preview until HMR/runtime confirms
+  the result. Human write consent remains mandatory and agents cannot grant it.
+
 ## Verification
 
 - `list-localhost-connections` returns the expected connection and routes.
diff --git a/templates/clips/.agents/skills/ai-video-tools/SKILL.md b/templates/clips/.agents/skills/ai-video-tools/SKILL.md
index 1423ea415e..dd30c013c0 100644
--- a/templates/clips/.agents/skills/ai-video-tools/SKILL.md
+++ b/templates/clips/.agents/skills/ai-video-tools/SKILL.md
@@ -126,7 +126,7 @@ Transcription takes an audio file and returns text + segments. That's not a prom
 **Provider priority:**
 
 1. **Native (highest priority).** The browser's Web Speech API, desktop local Whisper/macOS SFSpeech when available, and desktop Web Speech fallback on non-mac run during recording and save results via `save-browser-transcript`. This gives an instant transcript with no API key when the local/browser recognizer is available. When `request-transcript` runs afterward, it preserves the ready native transcript and only falls back to a cloud provider if native text is missing.
-2. **Cloud fallback — Builder.io managed (Gemini).** When a Builder account is connected (`BUILDER_PRIVATE_KEY` or per-user OAuth, no separate API key needed), `request-transcript` calls `transcribeWithBuilder()`, which routes audio to Builder.io's managed Gemini transcription. Returns text plus timestamped segments.
+2. **Cloud fallback — Builder.io managed (Gemini).** When a Builder account is connected (`BUILDER_PRIVATE_KEY` or per-user OAuth, no separate API key needed), `request-transcript` calls `transcribeWithBuilder()`, which routes audio to Builder.io's managed Gemini transcription. Returns text plus timestamped segments. Retry a failed transcript with `force: true`; pass `regenerate: true` to replace an existing ready transcript from the stored recording media. Regeneration keeps the prior ready transcript available if the new provider attempt fails.
 3. **Cloud fallback — Groq Whisper.** `GROQ_API_KEY` → `https://api.groq.com/openai/v1/audio/transcriptions`, model `whisper-large-v3-turbo`. Fast (~$0.04/hour of audio) Whisper-compatible speech-to-text used when Builder is unavailable.
 
 Clips never routes recording/meeting audio to OpenAI for transcription. (Groq's endpoint is OpenAI-_compatible_ in request shape only — the audio goes to Groq, not OpenAI.)
diff --git a/templates/clips/.agents/skills/video-sharing/SKILL.md b/templates/clips/.agents/skills/video-sharing/SKILL.md
index 63e9eedb44..861625a988 100644
--- a/templates/clips/.agents/skills/video-sharing/SKILL.md
+++ b/templates/clips/.agents/skills/video-sharing/SKILL.md
@@ -14,6 +14,12 @@ description: >-
 
 Recording sharing uses the framework `sharing` system — not a custom share table. Recordings are registered via `registerShareableResource({ type: "recording", ... })` in `server/db/index.ts`. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted and handle per-user grants, per-org grants, and the three visibility levels (`private` / `org` / `public`).
 
+Unlike the framework-wide private default, normal Clips recordings and uploaded
+videos default to **public** so their copied share links work immediately.
+Embedded bug-report recordings are the exception and default to organization
+visibility. Callers can still explicitly create a private or organization-only
+recording, and owners/admins can change visibility from the Share dialog.
+
 Clips **adds two things** on top of the framework system:
 
 1. **Password** — an optional bcrypt'd string on the `recordings` row. When set, all non-owner viewers must enter it to play the recording.
@@ -62,7 +68,7 @@ import { ShareDialog } from "@agent-native/core/client";
     </>
   }
   embedTabContent={<EmbedSnippetAndOptions recordingId={recording.id} />}
-/>
+/>;
 ```
 
 - `shareUrl` / `embedUrl` — the copy-link and embed URLs the framework renders in its tabs.
@@ -163,11 +169,11 @@ Required Slack app setup:
 Recordings can expose URLs meant for external agents without handing over raw
 video bytes:
 
-| Endpoint | Meaning |
-| -------- | ------- |
-| `/api/agent-context.json?id=<recordingId>` | Clip metadata, transcript summary, recommended frames, and API discovery links |
-| `/api/agent-transcript.json?id=<recordingId>` | Timestamped transcript segments with `startMs`, `endMs`, `timestamp`, `range`, `text`, and optional `source` |
-| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | JPEG frame extracted from the video at the requested original-video timestamp |
+| Endpoint                                          | Meaning                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `/api/agent-context.json?id=<recordingId>`        | Clip metadata, transcript summary, recommended frames, and API discovery links                               |
+| `/api/agent-transcript.json?id=<recordingId>`     | Timestamped transcript segments with `startMs`, `endMs`, `timestamp`, `range`, `text`, and optional `source` |
+| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | JPEG frame extracted from the video at the requested original-video timestamp                                |
 
 These endpoints follow the same access model as `/api/public-recording`, plus a
 temporary agent-link path:
diff --git a/templates/clips/AGENTS.md b/templates/clips/AGENTS.md
index 26087b0831..273dbc82b9 100644
--- a/templates/clips/AGENTS.md
+++ b/templates/clips/AGENTS.md
@@ -34,6 +34,10 @@ Detailed media, meeting, dictation, editing, and sharing rules live in
   download the original from Loom and use "Upload video".
 - Native transcript first. Cleanup and title generation can run in the
   background; do not hide a usable native transcript behind a failed cleanup.
+- Use `request-transcript --recordingId=<id> --force=true` to retry a failed
+  transcript. Pass `--regenerate=true` to replace an existing ready transcript
+  from the stored recording media; if regeneration fails, keep the prior ready
+  transcript available.
 - Dictation cleanup, Clip title/cleanup, and meeting summaries should pass
   bounded `voiceContext` to the shared cleanup/transcription path when active
   app context, learned vocabulary, user notes, or AGENTS.md preferences are
diff --git a/templates/clips/actions/create-recording.test.ts b/templates/clips/actions/create-recording.test.ts
index 98877d1830..ad1b0a74db 100644
--- a/templates/clips/actions/create-recording.test.ts
+++ b/templates/clips/actions/create-recording.test.ts
@@ -3,6 +3,15 @@ import { describe, expect, it } from "vitest";
 import { createRecordingSchema } from "./lib/create-recording-schema";
 
 describe("create-recording schema", () => {
+  it("defaults new recordings to public visibility", () => {
+    const parsed = createRecordingSchema.parse({
+      title: "Uploaded demo",
+      titleSource: "upload",
+    });
+
+    expect(parsed.visibility).toBe("public");
+  });
+
   it("does not require spaceIds for recorder clients", () => {
     const parsed = createRecordingSchema.safeParse({
       title: "Screen recording - 12 May 2026",
diff --git a/templates/clips/actions/create-recording.ts b/templates/clips/actions/create-recording.ts
index ccef44ddac..bb911f2c03 100644
--- a/templates/clips/actions/create-recording.ts
+++ b/templates/clips/actions/create-recording.ts
@@ -24,6 +24,7 @@ import {
 } from "../server/lib/recordings.js";
 import { setResumableSession } from "../server/lib/resumable-session.js";
 import { shouldEnableStreamingUpload } from "../server/lib/streaming-upload-mode.js";
+import { allowsSqlRecordingChunkScratch } from "../server/lib/video-storage.js";
 import { createRecordingSchema } from "./lib/create-recording-schema.js";
 import { DEFAULT_RECORDING_TITLE } from "./lib/title-source.js";
 
@@ -92,6 +93,7 @@ export default defineAction({
       shouldEnableStreamingUpload({
         client: args.streamingUploadClient,
         mimeType: args.mimeType,
+        bufferedFallbackAvailable: allowsSqlRecordingChunkScratch(),
       }) &&
       uploadProvider?.resumable
     ) {
diff --git a/templates/clips/actions/lib/create-recording-schema.ts b/templates/clips/actions/lib/create-recording-schema.ts
index 8f9792d4d2..e4e46a5fa6 100644
--- a/templates/clips/actions/lib/create-recording-schema.ts
+++ b/templates/clips/actions/lib/create-recording-schema.ts
@@ -62,8 +62,10 @@ export const createRecordingSchema = z.object({
     .describe("Height of the recording in pixels (may be 0 until finalized)"),
   visibility: z
     .enum(["private", "org", "public"])
-    .optional()
-    .describe("Initial share visibility for the recording"),
+    .default("public")
+    .describe(
+      "Initial share visibility for the recording (defaults to public)",
+    ),
   mimeType: z
     .string()
     .optional()
@@ -74,7 +76,7 @@ export const createRecordingSchema = z.object({
     .boolean()
     .optional()
     .describe(
-      "Request the resumable streaming upload path. Deployments must also set CLIPS_ENABLE_STREAMING_UPLOAD; otherwise recordings use the buffered fallback.",
+      "Request the resumable streaming upload path. Hosted deployments use it automatically because SQL chunk buffering is unavailable; local deployments can opt in with CLIPS_ENABLE_STREAMING_UPLOAD.",
     ),
   streamingUploadClient: z
     .enum(["desktop-native"])
diff --git a/templates/clips/actions/request-transcript.test.ts b/templates/clips/actions/request-transcript.test.ts
index 6d10b4e427..544e8bd3cd 100644
--- a/templates/clips/actions/request-transcript.test.ts
+++ b/templates/clips/actions/request-transcript.test.ts
@@ -31,6 +31,11 @@ const mockExportToBrainRun = vi.hoisted(() => vi.fn());
 const mockCleanupTranscriptRun = vi.hoisted(() => vi.fn());
 const mockRegenerateTitleRun = vi.hoisted(() => vi.fn());
 const mockQueueTitleRegenerationRequest = vi.hoisted(() => vi.fn());
+const mockResolveHasBuilderPrivateKey = vi.hoisted(() => vi.fn());
+const mockTranscribeWithBuilder = vi.hoisted(() => vi.fn());
+const mockSsrfSafeFetch = vi.hoisted(() => vi.fn());
+const mockPrepareAudioOnlyTranscriptionMedia = vi.hoisted(() => vi.fn());
+const mockAssertAccess = vi.hoisted(() => vi.fn());
 
 vi.mock("@agent-native/core", () => ({
   defineAction: (options: unknown) => options,
@@ -51,11 +56,11 @@ vi.mock("@agent-native/core/credentials", () => ({
 }));
 
 vi.mock("@agent-native/core/extensions/url-safety", () => ({
-  ssrfSafeFetch: vi.fn(),
+  ssrfSafeFetch: (...args: unknown[]) => mockSsrfSafeFetch(...args),
 }));
 
 vi.mock("@agent-native/core/secrets", () => ({
-  readAppSecret: vi.fn(),
+  readAppSecret: vi.fn(async () => null),
 }));
 
 vi.mock("@agent-native/core/server/request-context", () => ({
@@ -64,11 +69,17 @@ vi.mock("@agent-native/core/server/request-context", () => ({
 }));
 
 vi.mock("@agent-native/core/server", () => ({
-  resolveHasBuilderPrivateKey: vi.fn(async () => false),
+  resolveHasBuilderPrivateKey: (...args: unknown[]) =>
+    mockResolveHasBuilderPrivateKey(...args),
 }));
 
 vi.mock("@agent-native/core/transcription/builder", () => ({
-  transcribeWithBuilder: vi.fn(),
+  transcribeWithBuilder: (...args: unknown[]) =>
+    mockTranscribeWithBuilder(...args),
+}));
+
+vi.mock("@agent-native/core/sharing", () => ({
+  assertAccess: (...args: unknown[]) => mockAssertAccess(...args),
 }));
 
 vi.mock("drizzle-orm", () => ({
@@ -87,6 +98,7 @@ vi.mock("../server/db/index.js", () => ({
       durationMs: "recordings.durationMs",
       videoUrl: "recordings.videoUrl",
       videoFormat: "recordings.videoFormat",
+      videoSizeBytes: "recordings.videoSizeBytes",
       hasAudio: "recordings.hasAudio",
       sourceAppName: "recordings.sourceAppName",
       sourceWindowTitle: "recordings.sourceWindowTitle",
@@ -98,6 +110,7 @@ vi.mock("../server/db/index.js", () => ({
       segmentsJson: "recordingTranscripts.segmentsJson",
       updatedAt: "recordingTranscripts.updatedAt",
       language: "recordingTranscripts.language",
+      retryCount: "recordingTranscripts.retryCount",
     },
   },
 }));
@@ -133,7 +146,9 @@ vi.mock("./lib/audio-only-transcription.js", () => ({
   AudioOnlyExtractionError: class AudioOnlyExtractionError extends Error {},
   assertAudioHasAudibleSignal: vi.fn(),
   isNoExtractableAudioError: vi.fn(() => false),
-  prepareAudioOnlyTranscriptionMedia: vi.fn(),
+  isTransientExtractionError: vi.fn(() => false),
+  prepareAudioOnlyTranscriptionMedia: (...args: unknown[]) =>
+    mockPrepareAudioOnlyTranscriptionMedia(...args),
 }));
 
 vi.mock("./lib/loom-transcript.js", () => ({
@@ -144,7 +159,9 @@ vi.mock("./lib/loom-transcript.js", () => ({
 import {
   builderTranscriptionTimeoutMs,
   importLoomTranscriptForRecording,
+  recordingMediaFetchTimeoutMs,
 } from "./request-transcript";
+import requestTranscript from "./request-transcript";
 
 const existingSegments = JSON.stringify([
   { startMs: 0, endMs: 1200, text: "Saved transcript." },
@@ -173,6 +190,158 @@ describe("builderTranscriptionTimeoutMs", () => {
   });
 });
 
+describe("recordingMediaFetchTimeoutMs", () => {
+  it("gives long recordings enough time to download before extraction", () => {
+    expect(recordingMediaFetchTimeoutMs(null, null)).toBe(45_000);
+    expect(recordingMediaFetchTimeoutMs(250 * 1024 * 1024, null)).toBe(80_000);
+    expect(recordingMediaFetchTimeoutMs(null, 55 * 60_000)).toBe(90_000);
+  });
+
+  it("allows a bounded operator override", () => {
+    vi.stubEnv("CLIPS_TRANSCRIPTION_MEDIA_FETCH_TIMEOUT_MS", "100000");
+    expect(recordingMediaFetchTimeoutMs(null, null)).toBe(100_000);
+
+    vi.stubEnv("CLIPS_TRANSCRIPTION_MEDIA_FETCH_TIMEOUT_MS", "300000");
+    expect(recordingMediaFetchTimeoutMs(null, null)).toBe(120_000);
+  });
+});
+
+describe("requestTranscript regeneration", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSelectRows.queue = [];
+    mockResolveHasBuilderPrivateKey.mockResolvedValue(true);
+    mockAssertAccess.mockResolvedValue({ role: "editor" });
+    mockSsrfSafeFetch.mockResolvedValue(
+      new Response(new Blob(["recording"], { type: "video/webm" })),
+    );
+    mockPrepareAudioOnlyTranscriptionMedia.mockResolvedValue({
+      audioBytes: new Uint8Array([1, 2, 3]),
+      mimeType: "audio/webm",
+      filename: "recording.webm",
+    });
+    mockTranscribeWithBuilder.mockResolvedValue({
+      text: "Fresh transcript.",
+      language: "en",
+      segments: [{ startMs: 0, endMs: 1200, text: "Fresh transcript." }],
+    });
+    mockExportToBrainRun.mockResolvedValue({ status: "skipped" });
+  });
+
+  it("replaces a ready transcript when regeneration is explicitly requested", async () => {
+    mockSelectRows.queue = [
+      [
+        {
+          status: "ready",
+          fullText: "Old transcript.",
+          segmentsJson: JSON.stringify([
+            { startMs: 0, endMs: 1200, text: "Old transcript." },
+          ]),
+          updatedAt: "2026-07-09T00:00:00.000Z",
+          language: "en",
+          retryCount: 0,
+        },
+      ],
+      [
+        {
+          videoUrl: "https://cdn.example.com/recording.webm",
+          videoFormat: "webm",
+          hasAudio: true,
+          durationMs: 1200,
+          title: "Human title",
+        },
+      ],
+      [{ recordingId: "rec_ready" }],
+      [{ title: "Human title", titleSource: "manual" }],
+    ];
+
+    const result = await requestTranscript.run({
+      recordingId: "rec_ready",
+      force: true,
+      regenerate: true,
+    });
+
+    expect(mockAssertAccess).toHaveBeenCalledWith(
+      "recording",
+      "rec_ready",
+      "editor",
+    );
+    expect(result).toMatchObject({
+      recordingId: "rec_ready",
+      status: "ready",
+      provider: "builder",
+    });
+    expect(mockUpdateSet).toHaveBeenCalledWith(
+      expect.objectContaining({
+        status: "ready",
+        fullText: "Fresh transcript.",
+        failureReason: null,
+      }),
+    );
+    expect(
+      mockUpdateSet.mock.calls.some(
+        ([patch]) => (patch as { status?: string }).status === "pending",
+      ),
+    ).toBe(false);
+  });
+
+  it("keeps the ready transcript when regeneration fails", async () => {
+    mockTranscribeWithBuilder.mockRejectedValue(
+      new Error("Builder transcription failed (503 Service Unavailable)"),
+    );
+    mockSelectRows.queue = [
+      [
+        {
+          status: "ready",
+          fullText: "Saved transcript.",
+          segmentsJson: existingSegments,
+          updatedAt: "2026-07-09T00:00:00.000Z",
+          language: "en",
+          retryCount: 0,
+        },
+      ],
+      [
+        {
+          videoUrl: "https://cdn.example.com/recording.webm",
+          videoFormat: "webm",
+          hasAudio: true,
+          durationMs: 1200,
+          title: "Human title",
+        },
+      ],
+      [
+        {
+          status: "ready",
+          fullText: "Saved transcript.",
+          segmentsJson: existingSegments,
+          language: "en",
+        },
+      ],
+      [
+        {
+          title: "Human title",
+          titleSource: "manual",
+          durationMs: 1200,
+        },
+      ],
+    ];
+
+    const result = await requestTranscript.run({
+      recordingId: "rec_ready",
+      force: true,
+      regenerate: true,
+    });
+
+    expect(result).toMatchObject({
+      recordingId: "rec_ready",
+      status: "ready",
+      provider: "existing",
+      preserved: true,
+    });
+    expect(mockUpdateSet).not.toHaveBeenCalled();
+  });
+});
+
 describe("importLoomTranscriptForRecording", () => {
   beforeEach(() => {
     vi.clearAllMocks();
diff --git a/templates/clips/actions/request-transcript.ts b/templates/clips/actions/request-transcript.ts
index b137f5dcae..c3e5481451 100644
--- a/templates/clips/actions/request-transcript.ts
+++ b/templates/clips/actions/request-transcript.ts
@@ -45,6 +45,7 @@ import {
   getCredentialContext,
 } from "@agent-native/core/server/request-context";
 import { getSetting, getUserSetting } from "@agent-native/core/settings";
+import { assertAccess } from "@agent-native/core/sharing";
 import { transcribeWithBuilder } from "@agent-native/core/transcription/builder";
 import { and, eq } from "drizzle-orm";
 import { z } from "zod";
@@ -110,6 +111,7 @@ type TranscriptionProvider = {
 type RecordingMediaRow = {
   videoUrl: string | null;
   videoFormat?: "webm" | "mp4" | null;
+  videoSizeBytes?: number | null;
   hasAudio?: boolean | null;
   sourceAppName?: string | null;
   sourceWindowTitle?: string | null;
@@ -127,6 +129,11 @@ const BUILDER_TRANSCRIPTION_MIN_TIMEOUT_MS = 45_000;
 const BUILDER_TRANSCRIPTION_MAX_TIMEOUT_MS = 65_000;
 const BUILDER_TRANSCRIPTION_BASE_TIMEOUT_MS = 30_000;
 const BUILDER_TRANSCRIPTION_PER_MINUTE_MS = 3_000;
+const MEDIA_FETCH_MIN_TIMEOUT_MS = 45_000;
+const MEDIA_FETCH_MAX_TIMEOUT_MS = 120_000;
+const MEDIA_FETCH_BASE_TIMEOUT_MS = 30_000;
+const MEDIA_FETCH_PER_50MB_MS = 10_000;
+const ESTIMATED_VIDEO_BYTES_PER_MINUTE = 5 * 1024 * 1024;
 
 function clampTimeoutMs(value: number): number {
   return Math.max(
@@ -154,6 +161,38 @@ export function builderTranscriptionTimeoutMs(
   );
 }
 
+export function recordingMediaFetchTimeoutMs(
+  videoSizeBytes: number | null | undefined,
+  durationMs: number | null | undefined,
+): number {
+  const override = Number(
+    process.env.CLIPS_TRANSCRIPTION_MEDIA_FETCH_TIMEOUT_MS,
+  );
+  if (Number.isFinite(override) && override > 0) {
+    return Math.max(
+      MEDIA_FETCH_MIN_TIMEOUT_MS,
+      Math.min(MEDIA_FETCH_MAX_TIMEOUT_MS, Math.floor(override)),
+    );
+  }
+
+  const estimatedBytes =
+    videoSizeBytes && Number.isFinite(videoSizeBytes) && videoSizeBytes > 0
+      ? videoSizeBytes
+      : durationMs && Number.isFinite(durationMs) && durationMs > 0
+        ? Math.ceil(durationMs / 60_000) * ESTIMATED_VIDEO_BYTES_PER_MINUTE
+        : 0;
+  if (!estimatedBytes) return MEDIA_FETCH_MIN_TIMEOUT_MS;
+
+  const fiftyMbUnits = Math.ceil(estimatedBytes / (50 * 1024 * 1024));
+  return Math.max(
+    MEDIA_FETCH_MIN_TIMEOUT_MS,
+    Math.min(
+      MEDIA_FETCH_MAX_TIMEOUT_MS,
+      MEDIA_FETCH_BASE_TIMEOUT_MS + fiftyMbUnits * MEDIA_FETCH_PER_50MB_MS,
+    ),
+  );
+}
+
 // Bounded automatic retry for transient failures (ffmpeg timeout, transient
 // provider network/5xx errors) — NOT for permanent failures like "no audio
 // track" or a missing/rejected API key. Mirrors the fire-and-forget
@@ -301,10 +340,12 @@ async function loadRecordingMediaBlob({
   recordingId,
   videoUrl,
   fallbackMimeType,
+  timeoutMs,
 }: {
   recordingId: string;
   videoUrl: string;
   fallbackMimeType: string;
+  timeoutMs: number;
 }): Promise<{ blob: Blob; sourceMimeType: string }> {
   const isLocalBlob =
     videoUrl.startsWith("/api/video/") ||
@@ -334,10 +375,10 @@ async function loadRecordingMediaBlob({
     resolvedVideoUrl = `${origin}${resolvedVideoUrl}`;
   }
   const vidRes = isAppRelativeUrl
-    ? await fetch(resolvedVideoUrl, { signal: AbortSignal.timeout(30_000) })
+    ? await fetch(resolvedVideoUrl, { signal: AbortSignal.timeout(timeoutMs) })
     : await ssrfSafeFetch(
         resolvedVideoUrl,
-        { signal: AbortSignal.timeout(30_000) },
+        { signal: AbortSignal.timeout(timeoutMs) },
         { maxRedirects: 3 },
       );
   if (!vidRes.ok) {
@@ -899,7 +940,7 @@ async function pickProvider(
 
 const requestTranscriptAction = defineAction({
   description:
-    "Ensure a recording has a transcript. Preserves native Web Speech/macOS Speech transcripts first, then uses configured backup transcription only when needed.",
+    "Ensure a recording has a transcript, or explicitly regenerate it from the recording media. Preserves native Web Speech/macOS Speech transcripts unless regenerate is true, then uses Builder.io managed transcription or the configured Groq fallback.",
   schema: z.object({
     recordingId: z.string().describe("Recording ID"),
     force: z
@@ -908,6 +949,12 @@ const requestTranscriptAction = defineAction({
       .describe(
         "Bypass the recent pending guard for explicit retries or the finalize-recording background worker.",
       ),
+    regenerate: z
+      .boolean()
+      .optional()
+      .describe(
+        "Generate a fresh transcript from the recording media even when a ready transcript already exists. The existing ready transcript is kept if regeneration fails.",
+      ),
     retryAttempt: z
       .number()
       .int()
@@ -918,6 +965,8 @@ const requestTranscriptAction = defineAction({
       ),
   }),
   run: async (args) => {
+    await assertAccess("recording", args.recordingId, "editor");
+
     const db = getDb();
     const ownerEmail = getCurrentOwnerEmail();
     const now = new Date().toISOString();
@@ -944,6 +993,10 @@ const requestTranscriptAction = defineAction({
           recordingId: args.recordingId,
           videoUrl,
           fallbackMimeType,
+          timeoutMs: recordingMediaFetchTimeoutMs(
+            rec.videoSizeBytes,
+            rec.durationMs,
+          ),
         });
         return prepareAudioOnlyTranscriptionMedia({
           blob: media.blob,
@@ -980,6 +1033,11 @@ const requestTranscriptAction = defineAction({
     // manual retry can still top the budget back up for one more bounded
     // automatic pass if it fails transiently again.
     const currentRetryCount = existingNativeTranscript?.retryCount ?? 0;
+    const regeneratingReadyTranscript = Boolean(
+      args.regenerate &&
+      existingNativeTranscript?.status === "ready" &&
+      existingNativeTranscript.fullText?.trim(),
+    );
     if (args.retryAttempt !== undefined) {
       console.log(
         `[clips] auto-retry transcription attempt ${args.retryAttempt} for ${args.recordingId}`,
@@ -987,6 +1045,7 @@ const requestTranscriptAction = defineAction({
     }
 
     if (
+      !args.regenerate &&
       existingNativeTranscript?.status === "ready" &&
       existingNativeTranscript.fullText?.trim()
     ) {
@@ -1032,19 +1091,22 @@ const requestTranscriptAction = defineAction({
     // is set at the deployment level. Use the per-user-aware resolver so
     // a sidebar OAuth connection actually wires through to transcription.
     if (await resolveHasBuilderPrivateKey()) {
-      await upsertTranscriptRow(db, {
-        recordingId: args.recordingId,
-        ownerEmail,
-        status: "pending",
-        failureReason: null,
-        now,
-      });
-      await writeAppState("refresh-signal", { ts: Date.now() });
+      if (!regeneratingReadyTranscript) {
+        await upsertTranscriptRow(db, {
+          recordingId: args.recordingId,
+          ownerEmail,
+          status: "pending",
+          failureReason: null,
+          now,
+        });
+        await writeAppState("refresh-signal", { ts: Date.now() });
+      }
 
       const [rec] = await db
         .select({
           videoUrl: schema.recordings.videoUrl,
           videoFormat: schema.recordings.videoFormat,
+          videoSizeBytes: schema.recordings.videoSizeBytes,
           hasAudio: schema.recordings.hasAudio,
           sourceAppName: schema.recordings.sourceAppName,
           sourceWindowTitle: schema.recordings.sourceWindowTitle,
@@ -1121,13 +1183,15 @@ const requestTranscriptAction = defineAction({
         );
         const fullText = normalizedTranscript.fullText;
 
-        const preserved = await preserveReadyTranscriptIfAvailable({
-          db,
-          recordingId: args.recordingId,
-          ownerEmail,
-          allowLikelyLanguageMismatch: false,
-        });
-        if (preserved) return preserved;
+        if (!regeneratingReadyTranscript) {
+          const preserved = await preserveReadyTranscriptIfAvailable({
+            db,
+            recordingId: args.recordingId,
+            ownerEmail,
+            allowLikelyLanguageMismatch: false,
+          });
+          if (preserved) return preserved;
+        }
 
         if (!fullText) {
           return failEmptyProviderTranscript({
@@ -1251,15 +1315,17 @@ const requestTranscriptAction = defineAction({
     }
 
     // Upsert a pending row so the UI can show "Transcribing…".
-    await upsertTranscriptRow(db, {
-      recordingId: args.recordingId,
-      ownerEmail,
-      status: "pending",
-      failureReason: null,
-      now,
-    });
+    if (!regeneratingReadyTranscript) {
+      await upsertTranscriptRow(db, {
+        recordingId: args.recordingId,
+        ownerEmail,
+        status: "pending",
+        failureReason: null,
+        now,
+      });
 
-    await writeAppState("refresh-signal", { ts: Date.now() });
+      await writeAppState("refresh-signal", { ts: Date.now() });
+    }
 
     // Load the recording's media URL and prepare audio-only bytes. We never
     // send video frames to a transcription provider; screen-only recordings
@@ -1269,6 +1335,7 @@ const requestTranscriptAction = defineAction({
       .select({
         videoUrl: schema.recordings.videoUrl,
         videoFormat: schema.recordings.videoFormat,
+        videoSizeBytes: schema.recordings.videoSizeBytes,
         hasAudio: schema.recordings.hasAudio,
         sourceAppName: schema.recordings.sourceAppName,
         sourceWindowTitle: schema.recordings.sourceWindowTitle,
@@ -1369,13 +1436,15 @@ const requestTranscriptAction = defineAction({
       );
       const fullText = normalizedTranscript.fullText;
 
-      const preserved = await preserveReadyTranscriptIfAvailable({
-        db,
-        recordingId: args.recordingId,
-        ownerEmail,
-        allowLikelyLanguageMismatch: false,
-      });
-      if (preserved) return preserved;
+      if (!regeneratingReadyTranscript) {
+        const preserved = await preserveReadyTranscriptIfAvailable({
+          db,
+          recordingId: args.recordingId,
+          ownerEmail,
+          allowLikelyLanguageMismatch: false,
+        });
+        if (preserved) return preserved;
+      }
 
       if (!fullText) {
         return failEmptyProviderTranscript({
diff --git a/templates/clips/app/components/library/library-grid.tsx b/templates/clips/app/components/library/library-grid.tsx
index e6edc6d2cf..c77478bd62 100644
--- a/templates/clips/app/components/library/library-grid.tsx
+++ b/templates/clips/app/components/library/library-grid.tsx
@@ -253,6 +253,7 @@ export function LibraryGrid({
         <ShareRecordingDialog
           recordingId={sharingRec.id}
           recordingTitle={sharingRec.title}
+          initialVisibility={sharingRec.visibility}
           open={!!sharingRec}
           onOpenChange={(open) => {
             if (!open) setSharingRec(null);
diff --git a/templates/clips/app/components/player/share-dialog.test.ts b/templates/clips/app/components/player/share-dialog.test.ts
index ae3dd18af5..d578f01f96 100644
--- a/templates/clips/app/components/player/share-dialog.test.ts
+++ b/templates/clips/app/components/player/share-dialog.test.ts
@@ -19,8 +19,16 @@ describe("recording share popover", () => {
   it("keeps agent sharing private-only and lazy", () => {
     const shareDialogSource = readSource("./share-dialog.tsx");
 
-    expect(shareDialogSource).toContain("{!isPublic ? (");
+    expect(shareDialogSource).toContain("{sharesLoaded && !isPublic ? (");
     expect(shareDialogSource).toContain("if (!isPublic && agentShareOpen)");
     expect(shareDialogSource).toContain("{isPublic ? <SlackShareHint");
   });
+
+  it("uses known recording access while share details load", () => {
+    const shareDialogSource = readSource("./share-dialog.tsx");
+
+    expect(shareDialogSource).toContain("data?.role ?? initialRole");
+    expect(shareDialogSource).toContain("initialVisibility ??");
+    expect(shareDialogSource).not.toContain('?? "private"');
+  });
 });
diff --git a/templates/clips/app/components/player/share-dialog.tsx b/templates/clips/app/components/player/share-dialog.tsx
index 19407a54c3..c78e69ab80 100644
--- a/templates/clips/app/components/player/share-dialog.tsx
+++ b/templates/clips/app/components/player/share-dialog.tsx
@@ -62,6 +62,8 @@ function absoluteAppUrl(path: string): string {
 export interface ShareRecordingPopoverProps {
   recordingId: string;
   recordingTitle?: string;
+  initialVisibility?: Visibility | null;
+  initialRole?: "owner" | "admin" | "editor" | "viewer";
   videoUrl?: string | null;
   animatedThumbnailUrl?: string | null;
   isLoomRecording?: boolean;
@@ -90,6 +92,8 @@ type ShareRecordingDialogProps = Omit<
 export function ShareRecordingPopover({
   recordingId,
   recordingTitle,
+  initialVisibility,
+  initialRole,
   videoUrl,
   animatedThumbnailUrl,
   isLoomRecording = false,
@@ -108,6 +112,8 @@ export function ShareRecordingPopover({
         <ShareRecordingContent
           recordingId={recordingId}
           recordingTitle={recordingTitle}
+          initialVisibility={initialVisibility}
+          initialRole={initialRole}
           videoUrl={videoUrl}
           animatedThumbnailUrl={animatedThumbnailUrl}
           isLoomRecording={isLoomRecording}
@@ -125,6 +131,8 @@ export function ShareRecordingPopover({
 export function ShareRecordingDialog({
   recordingId,
   recordingTitle,
+  initialVisibility,
+  initialRole,
   videoUrl,
   animatedThumbnailUrl,
   isLoomRecording = false,
@@ -143,6 +151,8 @@ export function ShareRecordingDialog({
         <ShareRecordingContent
           recordingId={recordingId}
           recordingTitle={recordingTitle}
+          initialVisibility={initialVisibility}
+          initialRole={initialRole}
           videoUrl={videoUrl}
           animatedThumbnailUrl={animatedThumbnailUrl}
           isLoomRecording={isLoomRecording}
@@ -156,6 +166,8 @@ export function ShareRecordingDialog({
 function ShareRecordingContent({
   recordingId,
   recordingTitle,
+  initialVisibility,
+  initialRole,
   videoUrl,
   animatedThumbnailUrl,
   isLoomRecording = false,
@@ -163,6 +175,8 @@ function ShareRecordingContent({
 }: {
   recordingId: string;
   recordingTitle?: string;
+  initialVisibility?: Visibility | null;
+  initialRole?: "owner" | "admin" | "editor" | "viewer";
   videoUrl?: string | null;
   animatedThumbnailUrl?: string | null;
   isLoomRecording?: boolean;
@@ -175,7 +189,12 @@ function ShareRecordingContent({
   });
 
   const data = sharesQuery.data;
-  const canManage = data?.role === "owner" || data?.role === "admin";
+  const role = data?.role ?? initialRole;
+  const canManage = role === "owner" || role === "admin";
+  const visibility =
+    (data?.visibility as Visibility | null | undefined) ??
+    initialVisibility ??
+    null;
 
   // Attribution `via` must be a stable non-PII id, never an email. The only
   // owner id available client-side is the *current* session's userId, which is
@@ -226,6 +245,7 @@ function ShareRecordingContent({
             recordingId={recordingId}
             shareUrl={shareUrl}
             sharesQuery={sharesQuery}
+            visibility={visibility}
             canManage={canManage}
             videoUrl={videoUrl}
             animatedThumbnailUrl={animatedThumbnailUrl}
@@ -247,6 +267,7 @@ function ShareRecordingContent({
           <ClipsEmbedConfigurator
             recordingId={recordingId}
             sharesQuery={sharesQuery}
+            visibility={visibility}
             canManage={canManage}
             ownerViaId={ownerViaId}
           />
@@ -264,6 +285,7 @@ function LinkTab({
   recordingId,
   shareUrl,
   sharesQuery,
+  visibility,
   canManage,
   videoUrl,
   animatedThumbnailUrl,
@@ -272,6 +294,7 @@ function LinkTab({
   recordingId: string;
   shareUrl: string;
   sharesQuery: SharesQuery;
+  visibility: Visibility | null;
   canManage: boolean;
   videoUrl?: string | null;
   animatedThumbnailUrl?: string | null;
@@ -283,11 +306,9 @@ function LinkTab({
     recordingId,
     sharesQuery,
   );
-  const data = sharesQuery.data;
-  const visibility: Visibility =
-    (data?.visibility as Visibility | null) ?? "private";
   const isPublic = visibility === "public";
-  const sharesLoaded = data !== undefined;
+  const sharesLoaded = visibility !== null;
+  const visibilityPending = isPending || sharesQuery.isLoading;
   const isLoomRecording = isLoomRecordingProp || isLoomEmbedUrl(videoUrl);
   const createAgentLink = useActionMutation(
     "create-recording-agent-link" as any,
@@ -355,25 +376,34 @@ function LinkTab({
 
   return (
     <div className="space-y-4">
-      <GeneralAccessSelect
-        visibility={visibility}
-        canManage={canManage}
-        isPending={isPending}
-        onChange={(next) => setResourceVisibility(next)}
-        publicDescription={t("shareDialog.publicDescription")}
-      />
+      {visibility ? (
+        <GeneralAccessSelect
+          visibility={visibility}
+          canManage={canManage}
+          isPending={visibilityPending}
+          onChange={(next) => setResourceVisibility(next)}
+          publicDescription={t("shareDialog.publicDescription")}
+        />
+      ) : (
+        <div className="space-y-2" aria-hidden>
+          <div className="h-3 w-24 animate-pulse rounded bg-muted" />
+          <div className="h-12 w-full animate-pulse rounded bg-muted" />
+        </div>
+      )}
 
       <CopyField
         label={t("shareDialog.shareLink")}
         value={shareUrl}
-        disabled={isPending || (!isPublic && canManage)}
+        disabled={
+          visibilityPending || !sharesLoaded || (!isPublic && canManage)
+        }
       />
 
       {/* Public links unfurl into a playable video in Slack; surface that here
           (and a connect link) instead of leaving it buried in Settings. */}
       {isPublic ? <SlackShareHint canManage={canManage} /> : null}
 
-      {!isPublic ? (
+      {sharesLoaded && !isPublic ? (
         <Collapsible open={agentShareOpen} onOpenChange={setAgentShareOpen}>
           <CollapsibleTrigger asChild>
             <Button
@@ -431,7 +461,7 @@ function LinkTab({
         </Collapsible>
       ) : null}
 
-      {!isPublic && canManage ? (
+      {sharesLoaded && !isPublic && canManage ? (
         <MakePublicCard
           isPending={isPending}
           onMakePublic={() =>
@@ -485,11 +515,13 @@ function LinkTab({
 function ClipsEmbedConfigurator({
   recordingId,
   sharesQuery,
+  visibility,
   canManage,
   ownerViaId,
 }: {
   recordingId: string;
   sharesQuery: SharesQuery;
+  visibility: Visibility | null;
   canManage: boolean;
   ownerViaId?: string;
 }) {
@@ -500,11 +532,10 @@ function ClipsEmbedConfigurator({
   const [width, setWidth] = useState(640);
   const [height, setHeight] = useState(360);
 
-  const data = sharesQuery.data;
-  const visibility: Visibility =
-    (data?.visibility as Visibility | null) ?? "private";
   const isPublic = visibility === "public";
-  const visibilityLabel = t(`shareUi.visibility.${visibility}.label`);
+  const visibilityLabel = visibility
+    ? t(`shareUi.visibility.${visibility}.label`)
+    : "";
   const { setResourceVisibility, isPending } = useResourceVisibilityMutation(
     "recording",
     recordingId,
@@ -529,6 +560,15 @@ function ClipsEmbedConfigurator({
       ? `<div style="position:relative;padding-bottom:56.25%;height:0;background:#000;overflow:hidden"><iframe src="${src}" title="${t("shareDialog.embedIframeTitle")}" frameborder="0" scrolling="no" allowfullscreen allow="autoplay; fullscreen; picture-in-picture" style="position:absolute;inset:0;width:100%;height:100%;border:0;background:#000;overflow:hidden"></iframe></div>`
       : `<iframe src="${src}" title="${t("shareDialog.embedIframeTitle")}" width="${width}" height="${height}" frameborder="0" scrolling="no" allowfullscreen allow="autoplay; fullscreen; picture-in-picture" style="display:block;max-width:100%;border:0;background:#000;overflow:hidden"></iframe>`;
 
+  if (!visibility) {
+    return (
+      <div className="space-y-2" aria-hidden>
+        <div className="h-16 w-full animate-pulse rounded bg-muted" />
+        <div className="h-24 w-full animate-pulse rounded bg-muted" />
+      </div>
+    );
+  }
+
   return (
     <div className="space-y-3">
       {!isPublic ? (
diff --git a/templates/clips/app/components/player/transcript-panel.tsx b/templates/clips/app/components/player/transcript-panel.tsx
index f166d88d50..1c2b7b2ce8 100644
--- a/templates/clips/app/components/player/transcript-panel.tsx
+++ b/templates/clips/app/components/player/transcript-panel.tsx
@@ -19,6 +19,7 @@ import {
   IconBolt,
   IconChevronDown,
   IconChevronUp,
+  IconRefresh,
 } from "@tabler/icons-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
@@ -56,6 +57,9 @@ export interface TranscriptPanelProps {
   recordingTitle?: string;
   /** Called when the user asks us to retry transcription after fixing an error. */
   onRetry?: () => void;
+  /** Called when the user asks for a fresh transcript from the recording media. */
+  onRegenerate?: () => void;
+  isRegenerating?: boolean;
 }
 
 export function TranscriptPanel(props: TranscriptPanelProps) {
@@ -71,6 +75,8 @@ export function TranscriptPanel(props: TranscriptPanelProps) {
     cleanup,
     recordingTitle,
     onRetry,
+    onRegenerate,
+    isRegenerating = false,
   } = props;
   const [query, setQuery] = useState("");
   const [copied, setCopied] = useState(false);
@@ -170,8 +176,18 @@ export function TranscriptPanel(props: TranscriptPanelProps) {
           </p>
         </div>
         {onRetry ? (
-          <Button size="sm" variant="outline" onClick={onRetry}>
-            {t("transcriptPanel.retry")}
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={onRetry}
+            disabled={isRegenerating}
+          >
+            {isRegenerating ? (
+              <IconLoader2 className="size-4 animate-spin" />
+            ) : null}
+            {isRegenerating
+              ? t("transcriptPanel.transcribing")
+              : t("transcriptPanel.regenerate")}
           </Button>
         ) : null}
       </div>
@@ -188,8 +204,18 @@ export function TranscriptPanel(props: TranscriptPanelProps) {
         </div>
         <div className="flex items-center gap-2">
           {onRetry ? (
-            <Button size="sm" variant="outline" onClick={onRetry}>
-              {t("transcriptPanel.retry")}
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={onRetry}
+              disabled={isRegenerating}
+            >
+              {isRegenerating ? (
+                <IconLoader2 className="size-4 animate-spin" />
+              ) : null}
+              {isRegenerating
+                ? t("transcriptPanel.transcribing")
+                : t("transcriptPanel.regenerate")}
             </Button>
           ) : null}
         </div>
@@ -229,6 +255,24 @@ export function TranscriptPanel(props: TranscriptPanelProps) {
           </TooltipTrigger>
           <TooltipContent>{t("transcriptPanel.downloadSrt")}</TooltipContent>
         </Tooltip>
+        {onRegenerate ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="ghost"
+                size="icon"
+                onClick={onRegenerate}
+                disabled={isRegenerating}
+                aria-label={t("transcriptPanel.regenerate")}
+              >
+                <IconRefresh
+                  className={cn("h-4 w-4", isRegenerating && "animate-spin")}
+                />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>{t("transcriptPanel.regenerate")}</TooltipContent>
+          </Tooltip>
+        ) : null}
       </div>
 
       {cleanup?.status === "running" ? (
diff --git a/templates/clips/app/components/player/video-player.test.ts b/templates/clips/app/components/player/video-player.test.ts
index 31e4b4aec4..28b885a10e 100644
--- a/templates/clips/app/components/player/video-player.test.ts
+++ b/templates/clips/app/components/player/video-player.test.ts
@@ -54,14 +54,35 @@ describe("video player mobile controls", () => {
     expect(videoPlayerSource).toContain("onSeekRelative={seekByMs}");
   });
 
-  it("routes video surface clicks and taps through the same playback activation", () => {
+  it("reveals controls on touch while mouse clicks toggle playback", () => {
     const videoPlayerSource = readSource("./video-player.tsx");
     const activation = videoPlayerSource.indexOf("const activateVideoSurface");
-    const touchTap = videoPlayerSource.indexOf("activateVideoSurface();");
-    const clickTap = videoPlayerSource.lastIndexOf("activateVideoSurface();");
+    const touchBehavior = videoPlayerSource.indexOf(
+      'if (input === "touch" && !hideChrome)',
+      activation,
+    );
+    const revealControls = videoPlayerSource.indexOf(
+      "bumpControls();",
+      touchBehavior,
+    );
+    const playbackToggle = videoPlayerSource.indexOf(
+      "togglePlayback();",
+      revealControls,
+    );
+    const touchTap = videoPlayerSource.indexOf(
+      'activateVideoSurface("touch");',
+      playbackToggle,
+    );
+    const clickTap = videoPlayerSource.indexOf(
+      'activateVideoSurface("mouse");',
+      touchTap,
+    );
 
     expect(activation).toBeGreaterThan(-1);
-    expect(touchTap).toBeGreaterThan(activation);
+    expect(touchBehavior).toBeGreaterThan(activation);
+    expect(revealControls).toBeGreaterThan(touchBehavior);
+    expect(playbackToggle).toBeGreaterThan(revealControls);
+    expect(touchTap).toBeGreaterThan(playbackToggle);
     expect(clickTap).toBeGreaterThan(touchTap);
   });
 });
diff --git a/templates/clips/app/components/player/video-player.tsx b/templates/clips/app/components/player/video-player.tsx
index 26b8cd399d..eab79bf52c 100644
--- a/templates/clips/app/components/player/video-player.tsx
+++ b/templates/clips/app/components/player/video-player.tsx
@@ -563,16 +563,21 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
       requestPlay();
     }, [isPlaying, pauseVideo, requestPlay]);
 
-    const activateVideoSurface = useCallback(() => {
-      const v = videoRef.current;
-      if (!v) return;
-      if (!v.paused || isPlaying) {
-        pauseVideo();
-      } else {
-        requestPlay();
-      }
-      bumpControls();
-    }, [bumpControls, isPlaying, pauseVideo, requestPlay]);
+    const activateVideoSurface = useCallback(
+      (input: "mouse" | "touch") => {
+        // Match native mobile players: touching the video reveals the controls
+        // without unexpectedly pausing or resuming it. Embeds that explicitly
+        // hide their chrome keep surface-tap playback so they remain usable.
+        if (input === "touch" && !hideChrome) {
+          bumpControls();
+          return;
+        }
+
+        togglePlayback();
+        bumpControls();
+      },
+      [bumpControls, hideChrome, togglePlayback],
+    );
 
     const handlePlayerPointerDown = useCallback(
       (e: React.PointerEvent<HTMLDivElement>) => {
@@ -610,7 +615,7 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
 
         e.preventDefault();
         suppressNextClickRef.current = true;
-        activateVideoSurface();
+        activateVideoSurface("touch");
       },
       [activateVideoSurface, isLoomEmbed],
     );
@@ -1115,7 +1120,7 @@ export const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
           // keep their own behavior.
           if (isPlayerUiTarget(e.target)) return;
           if (isLoomEmbed) return;
-          activateVideoSurface();
+          activateVideoSurface("mouse");
         }}
       >
         {isLoomEmbed && loomIframeSrc ? (
diff --git a/templates/clips/app/i18n/ar-SA.ts b/templates/clips/app/i18n/ar-SA.ts
index aa3a60f015..27fba51dba 100644
--- a/templates/clips/app/i18n/ar-SA.ts
+++ b/templates/clips/app/i18n/ar-SA.ts
@@ -379,6 +379,7 @@ const messages = {
     searchPlaceholder: "نص البحث",
     copyTranscript: "نسخ النص",
     downloadSrt: "تحميل .srt",
+    regenerate: "إعادة إنشاء النص",
     cleanupRunning: "تنظيف النص في الخلفية.",
     noMatches: "لا توجد مباريات.",
     noTranscript: "لا يوجد نسخة بعد.",
diff --git a/templates/clips/app/i18n/de-DE.ts b/templates/clips/app/i18n/de-DE.ts
index ccd5b2f172..974afcd4df 100644
--- a/templates/clips/app/i18n/de-DE.ts
+++ b/templates/clips/app/i18n/de-DE.ts
@@ -388,6 +388,7 @@ const messages = {
     searchPlaceholder: "Transkript durchsuchen",
     copyTranscript: "Transkript kopieren",
     downloadSrt: "Laden Sie .srt herunter",
+    regenerate: "Transkript neu erstellen",
     cleanupRunning: "Bereinigen des Transkripts im Hintergrund.",
     noMatches: "Keine Übereinstimmungen.",
     noTranscript: "Noch kein Transkript.",
diff --git a/templates/clips/app/i18n/en-US.ts b/templates/clips/app/i18n/en-US.ts
index b8b4101ff3..712e5c6753 100644
--- a/templates/clips/app/i18n/en-US.ts
+++ b/templates/clips/app/i18n/en-US.ts
@@ -373,6 +373,7 @@ const messages = {
     searchPlaceholder: "Search transcript",
     copyTranscript: "Copy transcript",
     downloadSrt: "Download .srt",
+    regenerate: "Regenerate transcript",
     cleanupRunning: "Cleaning up transcript in the background.",
     noMatches: "No matches.",
     noTranscript: "No transcript yet.",
diff --git a/templates/clips/app/i18n/es-ES.ts b/templates/clips/app/i18n/es-ES.ts
index 701fdfc508..5954a3af13 100644
--- a/templates/clips/app/i18n/es-ES.ts
+++ b/templates/clips/app/i18n/es-ES.ts
@@ -386,6 +386,7 @@ const messages = {
     searchPlaceholder: "Transcripción de búsqueda",
     copyTranscript: "Copiar transcripción",
     downloadSrt: "Descargar .srt",
+    regenerate: "Regenerar transcripción",
     cleanupRunning: "Limpiando la transcripción en segundo plano.",
     noMatches: "Sin coincidencias.",
     noTranscript: "Aún no hay transcripción.",
diff --git a/templates/clips/app/i18n/fr-FR.ts b/templates/clips/app/i18n/fr-FR.ts
index 1a1076385e..0c90b37e2c 100644
--- a/templates/clips/app/i18n/fr-FR.ts
+++ b/templates/clips/app/i18n/fr-FR.ts
@@ -386,6 +386,7 @@ const messages = {
     searchPlaceholder: "Rechercher la transcription",
     copyTranscript: "Copier la transcription",
     downloadSrt: "Télécharger .srt",
+    regenerate: "Régénérer la transcription",
     cleanupRunning: "Nettoyage de la transcription en arrière-plan.",
     noMatches: "Aucun match.",
     noTranscript: "Pas encore de transcription.",
diff --git a/templates/clips/app/i18n/hi-IN.ts b/templates/clips/app/i18n/hi-IN.ts
index 3de0630c25..0db4f6cfc5 100644
--- a/templates/clips/app/i18n/hi-IN.ts
+++ b/templates/clips/app/i18n/hi-IN.ts
@@ -371,6 +371,7 @@ const messages = {
     searchPlaceholder: "प्रतिलेख खोजें",
     copyTranscript: "प्रतिलेख कॉपी करें",
     downloadSrt: "डाउनलोड .srt",
+    regenerate: "प्रतिलेख फिर से बनाएँ",
     cleanupRunning: "पृष्ठभूमि में प्रतिलेख साफ़ करना.",
     noMatches: "कोई मेल नहीं।",
     noTranscript: "अभी तक कोई प्रतिलेख नहीं.",
diff --git a/templates/clips/app/i18n/ja-JP.ts b/templates/clips/app/i18n/ja-JP.ts
index eb7c5acbfa..21ffcc0caa 100644
--- a/templates/clips/app/i18n/ja-JP.ts
+++ b/templates/clips/app/i18n/ja-JP.ts
@@ -381,6 +381,7 @@ const messages = {
     searchPlaceholder: "トランスクリプトの検索",
     copyTranscript: "トランスクリプトをコピーする",
     downloadSrt: ".srtをダウンロード",
+    regenerate: "トランスクリプトを再生成",
     cleanupRunning:
       "バックグラウンドでトランスクリプトをクリーンアップしています。",
     noMatches: "一致はありません。",
diff --git a/templates/clips/app/i18n/ko-KR.ts b/templates/clips/app/i18n/ko-KR.ts
index 5c2c5f2e26..e7b3796665 100644
--- a/templates/clips/app/i18n/ko-KR.ts
+++ b/templates/clips/app/i18n/ko-KR.ts
@@ -376,6 +376,7 @@ const messages = {
     searchPlaceholder: "성적표 검색",
     copyTranscript: "성적표 복사",
     downloadSrt: ".srt 다운로드",
+    regenerate: "스크립트 다시 생성",
     cleanupRunning: "백그라운드에서 기록을 정리합니다.",
     noMatches: "일치하는 항목이 없습니다.",
     noTranscript: "아직 성적표가 없습니다.",
diff --git a/templates/clips/app/i18n/pt-BR.ts b/templates/clips/app/i18n/pt-BR.ts
index 403abb2bed..20282eca75 100644
--- a/templates/clips/app/i18n/pt-BR.ts
+++ b/templates/clips/app/i18n/pt-BR.ts
@@ -383,6 +383,7 @@ const messages = {
     searchPlaceholder: "Transcrição da pesquisa",
     copyTranscript: "Copiar transcrição",
     downloadSrt: "Baixe .srt",
+    regenerate: "Gerar transcrição novamente",
     cleanupRunning: "Limpando a transcrição em segundo plano.",
     noMatches: "Nenhuma correspondência.",
     noTranscript: "Nenhuma transcrição ainda.",
diff --git a/templates/clips/app/i18n/zh-CN.ts b/templates/clips/app/i18n/zh-CN.ts
index 9f3a08128b..3f28f87920 100644
--- a/templates/clips/app/i18n/zh-CN.ts
+++ b/templates/clips/app/i18n/zh-CN.ts
@@ -361,6 +361,7 @@ const messages = {
     searchPlaceholder: "搜索成绩单",
     copyTranscript: "复制成绩单",
     downloadSrt: "下载.srt",
+    regenerate: "重新生成转录文本",
     cleanupRunning: "在后台清理成绩单。",
     noMatches: "没有匹配项。",
     noTranscript: "还没有文字记录。",
diff --git a/templates/clips/app/i18n/zh-TW.ts b/templates/clips/app/i18n/zh-TW.ts
index 43112ef4a6..5bb2c3b010 100644
--- a/templates/clips/app/i18n/zh-TW.ts
+++ b/templates/clips/app/i18n/zh-TW.ts
@@ -361,6 +361,7 @@ const messages = {
     searchPlaceholder: "搜尋逐字稿",
     copyTranscript: "複製逐字稿",
     downloadSrt: "下載 .srt",
+    regenerate: "重新產生逐字稿",
     cleanupRunning: "在背景清理逐字稿。",
     noMatches: "沒有符合項目。",
     noTranscript: "還沒有逐字稿。",
diff --git a/templates/clips/app/routes/r.$recordingId.tsx b/templates/clips/app/routes/r.$recordingId.tsx
index f2e186f74a..09c73d9fc0 100644
--- a/templates/clips/app/routes/r.$recordingId.tsx
+++ b/templates/clips/app/routes/r.$recordingId.tsx
@@ -59,7 +59,6 @@ import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import {
   DropdownMenu,
-  DropdownMenuCheckboxItem,
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuLabel,
@@ -67,6 +66,7 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { Spinner } from "@/components/ui/spinner";
+import { Switch } from "@/components/ui/switch";
 import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";
 import {
   Tooltip,
@@ -499,6 +499,15 @@ export default function RecordingPage() {
   const firstCta = ctas[0] ?? null;
   const handleAiError = (err: Error) =>
     toast.error(err?.message ?? t("recordingPage.aiRequestFailed"));
+  const requestTranscript = useActionMutation("request-transcript" as any, {
+    onSuccess: () => void playerDataQ.refetch(),
+    onError: (err: Error) =>
+      toast.error(
+        t("recordingPage.retryFailed", {
+          message: err?.message ?? t("recordingPage.networkError"),
+        }),
+      ),
+  });
   const regenerateTitle = useActionMutation("regenerate-title" as any, {
     onSuccess: (result: any) => {
       if (result?.updated) {
@@ -913,36 +922,34 @@ export default function RecordingPage() {
             durationMs={recording.durationMs}
             currentMs={currentMs}
             onSeek={(ms) => playerRef.current?.seek(ms)}
-            status={transcriptStatus}
+            status={
+              requestTranscript.isPending && transcriptStatus === "failed"
+                ? "pending"
+                : transcriptStatus
+            }
             failureReason={transcriptFailureReason}
             cleanup={transcriptCleanup}
             recordingTitle={recording.title}
-            onRetry={() => {
-              // Force a fresh transcript job, then let polling swap the panel
-              // back to the pending state while it runs.
-              fetch(
-                agentNativePath("/_agent-native/actions/request-transcript"),
-                {
-                  method: "POST",
-                  headers: { "Content-Type": "application/json" },
-                  body: JSON.stringify({
-                    recordingId: recording.id,
-                    force: true,
-                  }),
-                },
-              )
-                .then((res) => {
-                  if (!res.ok) throw new Error(`HTTP ${res.status}`);
-                })
-                .catch((err) =>
-                  toast.error(
-                    t("recordingPage.retryFailed", {
-                      message: err?.message ?? t("recordingPage.networkError"),
-                    }),
-                  ),
-                )
-                .finally(() => playerDataQ.refetch());
-            }}
+            onRetry={
+              canEdit
+                ? () =>
+                    requestTranscript.mutate({
+                      recordingId: recording.id,
+                      force: true,
+                    } as any)
+                : undefined
+            }
+            onRegenerate={
+              canEdit && transcriptStatus === "ready"
+                ? () =>
+                    requestTranscript.mutate({
+                      recordingId: recording.id,
+                      force: true,
+                      regenerate: true,
+                    } as any)
+                : undefined
+            }
+            isRegenerating={requestTranscript.isPending}
           />
         </TabsContent>
         <TabsContent
@@ -1061,16 +1068,21 @@ export default function RecordingPage() {
                   {t("recordingPage.enhanceRecording")}
                 </DropdownMenuLabel>
                 <DropdownMenuSeparator />
-                <DropdownMenuCheckboxItem
-                  checked={includeFullVideoInAi}
-                  disabled={aiPrefsQ.isLoading || updateAiPrefs.isPending}
-                  onCheckedChange={handleIncludeFullVideoChange}
-                  onSelect={(event) => event.preventDefault()}
-                  title={t("recordingPage.includeFullVideoDescription")}
+                <DropdownMenuItem
+                  disabled={requestTranscript.isPending}
+                  onSelect={() =>
+                    requestTranscript.mutate({
+                      recordingId: recording.id,
+                      force: true,
+                      regenerate: true,
+                    } as any)
+                  }
                 >
-                  {t("recordingPage.includeFullVideo")}
-                </DropdownMenuCheckboxItem>
-                <DropdownMenuSeparator />
+                  {requestTranscript.isPending ? (
+                    <Spinner className="size-4" />
+                  ) : null}
+                  {t("transcriptPanel.regenerate")}
+                </DropdownMenuItem>
                 <DropdownMenuItem
                   disabled={regenerateTitle.isPending}
                   onSelect={() =>
@@ -1161,6 +1173,25 @@ export default function RecordingPage() {
                     </Tooltip>
                   );
                 })}
+                <DropdownMenuSeparator />
+                <DropdownMenuItem
+                  disabled={aiPrefsQ.isLoading || updateAiPrefs.isPending}
+                  onSelect={(event) => {
+                    event.preventDefault();
+                    handleIncludeFullVideoChange(!includeFullVideoInAi);
+                  }}
+                  title={t("recordingPage.includeFullVideoDescription")}
+                  className="justify-between gap-3"
+                >
+                  <span>{t("recordingPage.includeFullVideo")}</span>
+                  <Switch
+                    checked={includeFullVideoInAi}
+                    disabled={aiPrefsQ.isLoading || updateAiPrefs.isPending}
+                    tabIndex={-1}
+                    aria-hidden="true"
+                    className="pointer-events-none"
+                  />
+                </DropdownMenuItem>
               </DropdownMenuContent>
             </DropdownMenu>
           ) : null}
@@ -1168,6 +1199,8 @@ export default function RecordingPage() {
           <ShareRecordingPopover
             recordingId={recording.id}
             recordingTitle={recording.title}
+            initialVisibility={recording.visibility}
+            initialRole={role}
             videoUrl={recording.videoUrl}
             animatedThumbnailUrl={recording.animatedThumbnailUrl}
             isLoomRecording={isLoomEmbedBacked}
diff --git a/templates/clips/app/routes/record.tsx b/templates/clips/app/routes/record.tsx
index 6fe8655d20..49d82b6844 100644
--- a/templates/clips/app/routes/record.tsx
+++ b/templates/clips/app/routes/record.tsx
@@ -12,6 +12,7 @@ import {
   waitForReadyRecordingAfterFinalizeError,
 } from "@shared/finalize-recovery";
 import {
+  chunkUploadParallelism,
   chunkUploadUrl,
   pickMimeType,
   type UploadMode,
@@ -1576,11 +1577,11 @@ export default function RecordRoute() {
               hasAudio: true,
               width: meta.width,
               height: meta.height,
-              visibility: reportContext ? "org" : undefined,
+              visibility: reportContext ? "org" : "public",
               spaceIds: spaceIdFromUrl ? [spaceIdFromUrl] : undefined,
               folderId: folderIdFromUrl ?? undefined,
               mimeType: uploadMimeType,
-              requestStreaming: false,
+              requestStreaming: true,
             }),
           },
         );
@@ -1596,10 +1597,16 @@ export default function RecordRoute() {
           );
         }
         const created = (await res.json()) as {
-          result?: { id: string; uploadChunkUrl: string; abortUrl?: string };
+          result?: {
+            id: string;
+            uploadChunkUrl: string;
+            abortUrl?: string;
+            uploadMode?: UploadMode;
+          };
           id?: string;
           uploadChunkUrl?: string;
           abortUrl?: string;
+          uploadMode?: UploadMode;
         };
         const info =
           created.result ??
@@ -1607,6 +1614,7 @@ export default function RecordRoute() {
             id: string;
             uploadChunkUrl: string;
             abortUrl?: string;
+            uploadMode?: UploadMode;
           });
         if (!info?.id) {
           throw new Error("create-recording did not return an id");
@@ -1707,7 +1715,12 @@ export default function RecordRoute() {
 
         await Promise.all(
           Array.from(
-            { length: Math.min(UPLOAD_PARALLELISM, parallelChunks.length) },
+            {
+              length: Math.min(
+                chunkUploadParallelism(info.uploadMode, UPLOAD_PARALLELISM),
+                parallelChunks.length,
+              ),
+            },
             worker,
           ),
         );
diff --git a/templates/clips/app/routes/share.$shareId.tsx b/templates/clips/app/routes/share.$shareId.tsx
index d3fd1399d2..1874d9d347 100644
--- a/templates/clips/app/routes/share.$shareId.tsx
+++ b/templates/clips/app/routes/share.$shareId.tsx
@@ -903,6 +903,8 @@ export default function ShareRoute() {
               <ShareRecordingPopover
                 recordingId={recording.id}
                 recordingTitle={recording.title}
+                initialVisibility={recording.visibility}
+                initialRole={viewerIsOwner ? "owner" : undefined}
                 videoUrl={recording.videoUrl}
                 animatedThumbnailUrl={recording.animatedThumbnailUrl}
                 isLoomRecording={isLoomEmbedBacked}
diff --git a/templates/clips/changelog/2026-07-09-desktop-popover-sits-closer-to-the-menu-bar.md b/templates/clips/changelog/2026-07-09-desktop-popover-sits-closer-to-the-menu-bar.md
new file mode 100644
index 0000000000..79c8e4a84d
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-desktop-popover-sits-closer-to-the-menu-bar.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+The Clips desktop popover now sits closer to its menu-bar icon.
diff --git a/templates/clips/changelog/2026-07-09-desktop-recording-optimization-progress-stays-visible-until-the-clip-opens.md b/templates/clips/changelog/2026-07-09-desktop-recording-optimization-progress-stays-visible-until-the-clip-opens.md
new file mode 100644
index 0000000000..26cefeb76f
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-desktop-recording-optimization-progress-stays-visible-until-the-clip-opens.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Desktop recording optimization progress stays visible from Stop until the finished clip opens.
diff --git a/templates/clips/changelog/2026-07-09-fixed-large-video-file-uploads-failing-before-their-resumabl.md b/templates/clips/changelog/2026-07-09-fixed-large-video-file-uploads-failing-before-their-resumabl.md
new file mode 100644
index 0000000000..97c9e9c438
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-fixed-large-video-file-uploads-failing-before-their-resumabl.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Fixed long desktop recordings and large video file uploads failing without a resumable upload session.
diff --git a/templates/clips/changelog/2026-07-09-fixed-new-video-uploads-defaulting-to-private.md b/templates/clips/changelog/2026-07-09-fixed-new-video-uploads-defaulting-to-private.md
new file mode 100644
index 0000000000..2ba84de1b1
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-fixed-new-video-uploads-defaulting-to-private.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+New video uploads are public by default, and owners can change sharing visibility as soon as they open the Share dialog.
diff --git a/templates/clips/changelog/2026-07-09-long-recordings-now-get-enough-time-to-download-their-media-.md b/templates/clips/changelog/2026-07-09-long-recordings-now-get-enough-time-to-download-their-media-.md
new file mode 100644
index 0000000000..c9201835a1
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-long-recordings-now-get-enough-time-to-download-their-media-.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Long recordings now get enough time to download their media before transcription starts.
diff --git a/templates/clips/changelog/2026-07-09-meeting-notes-no-longer-lowers-your-microphone-volume-for-ot.md b/templates/clips/changelog/2026-07-09-meeting-notes-no-longer-lowers-your-microphone-volume-for-ot.md
new file mode 100644
index 0000000000..af273f0204
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-meeting-notes-no-longer-lowers-your-microphone-volume-for-ot.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Meeting Notes no longer lowers your microphone volume for other people in Zoom, Meet, or Teams.
diff --git a/templates/clips/changelog/2026-07-09-on-mobile-tapping-a-playing-clip-reveals-playback-controls-w.md b/templates/clips/changelog/2026-07-09-on-mobile-tapping-a-playing-clip-reveals-playback-controls-w.md
new file mode 100644
index 0000000000..a6acc0fd96
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-on-mobile-tapping-a-playing-clip-reveals-playback-controls-w.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+On mobile, tapping a playing clip reveals playback controls without interrupting the video.
diff --git a/templates/clips/changelog/2026-07-09-regenerate-any-clip-transcript-from-its-saved-recording-or-r.md b/templates/clips/changelog/2026-07-09-regenerate-any-clip-transcript-from-its-saved-recording-or-r.md
new file mode 100644
index 0000000000..212fe1fd8a
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-regenerate-any-clip-transcript-from-its-saved-recording-or-r.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+Regenerate any clip transcript from its saved recording, or retry one that failed.
diff --git a/templates/clips/changelog/2026-07-09-slack-previews-now-show-the-clip-length-alongside-its-descri.md b/templates/clips/changelog/2026-07-09-slack-previews-now-show-the-clip-length-alongside-its-descri.md
new file mode 100644
index 0000000000..ad6b2abd3c
--- /dev/null
+++ b/templates/clips/changelog/2026-07-09-slack-previews-now-show-the-clip-length-alongside-its-descri.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Slack previews now show the clip length alongside its description.
diff --git a/templates/clips/desktop/src-tauri/src/clips/mod.rs b/templates/clips/desktop/src-tauri/src/clips/mod.rs
index 5105ecc8a9..043bc4cb52 100644
--- a/templates/clips/desktop/src-tauri/src/clips/mod.rs
+++ b/templates/clips/desktop/src-tauri/src/clips/mod.rs
@@ -46,6 +46,15 @@ const REGION_GUIDES_LABEL: &str = "region-guides";
 const REGION_GUIDE_EDITOR_LABEL: &str = "region-guide-editor";
 const REGION_RECORD_BORDER_LABEL: &str = "region-record-border";
 const ONBOARDING_LABEL: &str = "onboarding";
+const OVERLAY_LABELS: &[&str] = &[
+    COUNTDOWN_LABEL,
+    TOOLBAR_LABEL,
+    BUBBLE_LABEL,
+    FINALIZING_LABEL,
+    FLOW_BAR_LABEL,
+    REGION_GUIDES_LABEL,
+    REGION_RECORD_BORDER_LABEL,
+];
 const ONBOARDING_WIDTH_LOGICAL: f64 = 560.0;
 const ONBOARDING_HEIGHT_LOGICAL: f64 = 640.0;
 
@@ -952,19 +961,21 @@ pub async fn set_bubble_capture_excluded(app: AppHandle, excluded: bool) -> Resu
     Ok(())
 }
 
+fn overlay_labels_to_hide(preserve_finalizing: bool) -> impl Iterator<Item = &'static str> {
+    OVERLAY_LABELS
+        .iter()
+        .copied()
+        .filter(move |label| !preserve_finalizing || *label != FINALIZING_LABEL)
+}
+
 #[tauri::command]
-pub async fn hide_overlays(app: AppHandle) -> Result<(), String> {
+pub async fn hide_overlays(
+    app: AppHandle,
+    preserve_finalizing: Option<bool>,
+) -> Result<(), String> {
     stop_countdown_control_tracking();
     let _ = app.emit("clips:countdown-shortcuts-active", false);
-    for label in [
-        COUNTDOWN_LABEL,
-        TOOLBAR_LABEL,
-        BUBBLE_LABEL,
-        FINALIZING_LABEL,
-        FLOW_BAR_LABEL,
-        REGION_GUIDES_LABEL,
-        REGION_RECORD_BORDER_LABEL,
-    ] {
+    for label in overlay_labels_to_hide(preserve_finalizing.unwrap_or(false)) {
         if let Some(w) = app.get_webview_window(label) {
             let _ = w.close();
         }
@@ -1524,9 +1535,16 @@ fn remembered_voice_target_bundle(app: &AppHandle) -> Option<String> {
 #[cfg(test)]
 mod tests {
     use super::{
-        strip_trailing_period_for_messaging, text_insertion_strategy, TextInsertionStrategy,
+        overlay_labels_to_hide, strip_trailing_period_for_messaging, text_insertion_strategy,
+        TextInsertionStrategy, FINALIZING_LABEL,
     };
 
+    #[test]
+    fn overlay_cleanup_can_preserve_finalizing_progress() {
+        assert!(!overlay_labels_to_hide(true).any(|label| label == FINALIZING_LABEL));
+        assert!(overlay_labels_to_hide(false).any(|label| label == FINALIZING_LABEL));
+    }
+
     #[test]
     fn uses_clipboard_paste_for_chrome() {
         assert!(matches!(
diff --git a/templates/clips/desktop/src-tauri/src/native_screen.rs b/templates/clips/desktop/src-tauri/src/native_screen.rs
index 46f4c012e2..be2288ebe3 100644
--- a/templates/clips/desktop/src-tauri/src/native_screen.rs
+++ b/templates/clips/desktop/src-tauri/src/native_screen.rs
@@ -2254,7 +2254,7 @@ fn preferred_default_microphone_device(devices: &[AudioInputDevice]) -> Option<A
 }
 
 #[cfg(target_os = "macos")]
-fn resolve_microphone_capture_device(
+pub(crate) fn resolve_microphone_capture_device(
     device_id: Option<&str>,
     device_label: Option<&str>,
 ) -> Result<Option<AudioInputDevice>, String> {
diff --git a/templates/clips/desktop/src-tauri/src/system_audio.rs b/templates/clips/desktop/src-tauri/src/system_audio.rs
index 37b3fd5ff3..8763feefee 100644
--- a/templates/clips/desktop/src-tauri/src/system_audio.rs
+++ b/templates/clips/desktop/src-tauri/src/system_audio.rs
@@ -25,8 +25,8 @@
 //! | `audio_transcription_reset_timeline`| Rebase transcript timestamps to now.     |
 //! | `audio_transcription_stop`         | Stop the capture.                         |
 //!
-//! `start_raw_system_capture` (in the `macos` submodule) is the capture entry
-//! point the Whisper engine calls directly.
+//! `start_raw_system_capture` and `start_raw_meeting_capture` (in the `macos`
+//! submodule) are the capture entry points the Whisper engine calls directly.
 //!
 //! ## Events
 //!   - `voice:audio-level` `{ level, source: "system" }` — waveform meter.
@@ -124,7 +124,10 @@ pub async fn audio_transcription_start(
         mic_device_id,
         mic_device_label,
         capture_system.unwrap_or(true),
-        voice_processing.unwrap_or(true),
+        // Fail safe for meeting/recording callers: an omitted flag must not
+        // create a second VoiceProcessingIO stack beside a live call app.
+        // Short dictation sessions opt in explicitly from the renderer.
+        voice_processing.unwrap_or(false),
         owner,
     )
     .await
@@ -246,6 +249,8 @@ pub(crate) mod macos {
         app: AppHandle,
         cancelled: Arc<AtomicBool>,
         level_tick: Arc<AtomicU32>,
+        output_type: SCStreamOutputType,
+        source: &'static str,
     }
 
     // SAFETY: `Retained<SFSpeech*>` and `Retained<AVAudioFormat>` wrap
@@ -261,7 +266,7 @@ pub(crate) mod macos {
             sample_buffer: CMSampleBuffer,
             of_type: SCStreamOutputType,
         ) {
-            if of_type != SCStreamOutputType::Audio {
+            if of_type != self.output_type {
                 return;
             }
             if self.cancelled.load(Ordering::SeqCst) {
@@ -287,7 +292,7 @@ pub(crate) mod macos {
                         "voice:audio-level",
                         AudioLevelPayload {
                             level,
-                            source: "system",
+                            source: self.source,
                         },
                     );
                 }
@@ -295,17 +300,18 @@ pub(crate) mod macos {
         }
     }
 
-    /// Handle for a running raw system capture. `stop()` ends the SCK stream.
-    pub(crate) struct RawSystemCapture {
+    /// Handle for a running raw SCK audio capture. A meeting capture can carry
+    /// both system and microphone output handlers on this one stream.
+    pub(crate) struct RawSckAudioCapture {
         stream: SCStream,
         cancelled: Arc<AtomicBool>,
     }
 
     // SAFETY: `SCStream` is `Send` (the crate marks it so); the atomic is
     // trivially `Send`. We only move the handle through ownership.
-    unsafe impl Send for RawSystemCapture {}
+    unsafe impl Send for RawSckAudioCapture {}
 
-    impl RawSystemCapture {
+    impl RawSckAudioCapture {
         pub(crate) fn stop(self) {
             self.cancelled.store(true, Ordering::SeqCst);
             let _ = self.stream.stop_capture();
@@ -317,7 +323,50 @@ pub(crate) mod macos {
     pub(crate) fn start_raw_system_capture(
         app: AppHandle,
         on_samples: Arc<dyn Fn(&[f32]) + Send + Sync>,
-    ) -> Result<RawSystemCapture, String> {
+    ) -> Result<RawSckAudioCapture, String> {
+        start_raw_sck_audio_capture(app, true, None, None, Some(on_samples), None)
+    }
+
+    /// Whether this macOS version supports ScreenCaptureKit's independent
+    /// microphone output (`SCStreamOutputType::Microphone`).
+    pub(crate) fn supports_sck_microphone_capture() -> bool {
+        let version = NSProcessInfo::processInfo().operatingSystemVersion();
+        version.majorVersion >= 15
+    }
+
+    /// Start one ScreenCaptureKit stream with independent system-audio and
+    /// microphone callbacks. This avoids opening a second AVAudioEngine /
+    /// VoiceProcessingIO input while Zoom, Meet, or Teams owns the live-call
+    /// microphone uplink.
+    pub(crate) fn start_raw_meeting_capture(
+        app: AppHandle,
+        mic_device_id: Option<String>,
+        mic_device_label: Option<String>,
+        capture_system: bool,
+        on_mic_samples: Arc<dyn Fn(&[f32]) + Send + Sync>,
+        on_system_samples: Option<Arc<dyn Fn(&[f32]) + Send + Sync>>,
+    ) -> Result<RawSckAudioCapture, String> {
+        if !supports_sck_microphone_capture() {
+            return Err("ScreenCaptureKit microphone capture requires macOS 15 or later.".into());
+        }
+        start_raw_sck_audio_capture(
+            app,
+            capture_system,
+            mic_device_id,
+            mic_device_label,
+            on_system_samples,
+            Some(on_mic_samples),
+        )
+    }
+
+    fn start_raw_sck_audio_capture(
+        app: AppHandle,
+        capture_system: bool,
+        mic_device_id: Option<String>,
+        mic_device_label: Option<String>,
+        on_system_samples: Option<Arc<dyn Fn(&[f32]) + Send + Sync>>,
+        on_mic_samples: Option<Arc<dyn Fn(&[f32]) + Send + Sync>>,
+    ) -> Result<RawSckAudioCapture, String> {
         let granted = unsafe { CGPreflightScreenCaptureAccess() };
         if !granted {
             let granted_now = unsafe { CGRequestScreenCaptureAccess() };
@@ -340,13 +389,30 @@ pub(crate) mod macos {
             .with_excluding_windows(&[])
             .build();
 
-        let config = SCStreamConfiguration::new()
-            .with_captures_audio(true)
+        let capture_microphone = on_mic_samples.is_some();
+        let selected_mic = if capture_microphone {
+            crate::native_screen::resolve_microphone_capture_device(
+                mic_device_id.as_deref(),
+                mic_device_label.as_deref(),
+            )?
+        } else {
+            None
+        };
+        let mut config = SCStreamConfiguration::new()
+            .with_captures_audio(capture_system)
+            .with_captures_microphone(capture_microphone)
             .with_excludes_current_process_audio(true)
             .with_sample_rate(48000)
             .with_channel_count(2)
             .with_width(2)
             .with_height(2);
+        if let Some(device) = selected_mic.as_ref() {
+            config.set_microphone_capture_device_id(&device.id);
+            eprintln!(
+                "[whisper] ScreenCaptureKit meeting microphone pinned to {} ({})",
+                device.name, device.id
+            );
+        }
 
         // Mono float32 @ 48 kHz destination format for the mono-mix.
         let speech_format = unsafe {
@@ -357,21 +423,37 @@ pub(crate) mod macos {
 
         let cancelled = Arc::new(AtomicBool::new(false));
         let mut stream = SCStream::new(&filter, &config);
-        let forwarder = RawAudioForwarder {
-            on_samples,
-            speech_format,
-            app: app.clone(),
-            cancelled: cancelled.clone(),
-            level_tick: Arc::new(AtomicU32::new(0)),
-        };
-        stream.add_output_handler(forwarder, SCStreamOutputType::Audio);
+        if let Some(on_samples) = on_system_samples {
+            let forwarder = RawAudioForwarder {
+                on_samples,
+                speech_format: speech_format.clone(),
+                app: app.clone(),
+                cancelled: cancelled.clone(),
+                level_tick: Arc::new(AtomicU32::new(0)),
+                output_type: SCStreamOutputType::Audio,
+                source: "system",
+            };
+            stream.add_output_handler(forwarder, SCStreamOutputType::Audio);
+        }
+        if let Some(on_samples) = on_mic_samples {
+            let forwarder = RawAudioForwarder {
+                on_samples,
+                speech_format,
+                app: app.clone(),
+                cancelled: cancelled.clone(),
+                level_tick: Arc::new(AtomicU32::new(0)),
+                output_type: SCStreamOutputType::Microphone,
+                source: "mic",
+            };
+            stream.add_output_handler(forwarder, SCStreamOutputType::Microphone);
+        }
 
         if let Err(e) = stream.start_capture() {
             cancelled.store(true, Ordering::SeqCst);
             return Err(format!("SCStream start_capture failed: {e:?}"));
         }
 
-        Ok(RawSystemCapture { stream, cancelled })
+        Ok(RawSckAudioCapture { stream, cancelled })
     }
 
     #[derive(Serialize, Clone)]
diff --git a/templates/clips/desktop/src-tauri/src/whisper_speech.rs b/templates/clips/desktop/src-tauri/src/whisper_speech.rs
index 0e87f15674..ce1ac173d0 100644
--- a/templates/clips/desktop/src-tauri/src/whisper_speech.rs
+++ b/templates/clips/desktop/src-tauri/src/whisper_speech.rs
@@ -10,7 +10,9 @@
 //! Capture is reused from the existing modules:
 //!   - mic    → `native_speech::macos::start_raw_mic_capture` (AVAudioEngine +
 //!              optional VoiceProcessingIO AEC, other-audio ducking off)
-//!   - system → `system_audio::macos::start_raw_system_capture` (ScreenCaptureKit)
+//!   - meetings on macOS 15+ → one ScreenCaptureKit stream with independent
+//!              microphone + system-audio outputs
+//!   - legacy system audio → `system_audio::macos::start_raw_system_capture`
 //!
 use tauri::AppHandle;
 
@@ -108,7 +110,10 @@ mod macos {
     use whisper_rs::{FullParams, SamplingStrategy, WhisperContext, WhisperContextParameters};
 
     use crate::native_speech::macos::{start_raw_mic_capture, RawMicCapture};
-    use crate::system_audio::macos::{start_raw_system_capture, RawSystemCapture};
+    use crate::system_audio::macos::{
+        start_raw_meeting_capture, start_raw_system_capture, supports_sck_microphone_capture,
+        RawSckAudioCapture,
+    };
     use crate::whisper_model::{ensure_model, model_file};
 
     /// One transcript segment with real timestamps from whisper, already
@@ -571,11 +576,20 @@ mod macos {
         }
     }
 
+    fn should_use_combined_sck_capture(
+        owner: SessionOwner,
+        microphone_capture_supported: bool,
+    ) -> bool {
+        owner == SessionOwner::Meeting && microphone_capture_supported
+    }
+
     struct Session {
-        mic_cap: RawMicCapture,
+        // macOS 15+ meetings use a combined SCK capture, so there is no
+        // competing AVAudioEngine / VoiceProcessingIO mic input to stop.
+        mic_cap: Option<RawMicCapture>,
         // System capture is optional — skipped when the user turns system
         // audio off, so neither the recording nor the transcript include it.
-        sys_cap: Option<RawSystemCapture>,
+        sys_cap: Option<RawSckAudioCapture>,
         mic: Arc<WhisperStream>,
         sys: Option<Arc<WhisperStream>>,
         /// Who started this session — see `SessionOwner`.
@@ -644,8 +658,10 @@ mod macos {
         let _ = language;
         let lang: Option<String> = None;
 
-        // Mic stream + capture. The real hardware rate is read back from the
-        // capture handle and pushed into the stream (default 48 kHz until then).
+        // Create both Whisper streams first. On macOS 15+ meetings, one
+        // ScreenCaptureKit stream feeds both callbacks without opening a
+        // competing VoiceProcessingIO mic input. Older macOS versions (and a
+        // failed SCK start) keep the existing split-capture fallback.
         let session_start = Instant::now();
         let mic_stream = WhisperStream::new(
             app.clone(),
@@ -655,50 +671,92 @@ mod macos {
             ctx.clone(),
             session_start,
         );
-        let mic_for_cb = mic_stream.clone();
-        let reuse_voice_processing_engine = owner == SessionOwner::Dictation && !capture_system;
-        let mic_cap = start_raw_mic_capture(
-            app.clone(),
-            mic_device_id,
-            mic_device_label,
-            voice_processing,
-            reuse_voice_processing_engine,
-            Arc::new(move |s: &[f32]| mic_for_cb.push(s)),
-        )
-        .map_err(|e| {
-            mic_stream.stop();
-            format!("mic capture failed: {e}")
-        })?;
-        mic_stream.set_src_rate(mic_cap.sample_rate());
-
-        // System stream + capture (SCK delivers 48 kHz). Skipped entirely when
-        // system audio is off.
-        let (sys_stream, sys_cap) = if capture_system {
-            let sys_stream = WhisperStream::new(
+        let sys_stream = capture_system.then(|| {
+            WhisperStream::new(
                 app.clone(),
                 "system",
                 48000.0,
                 lang.clone(),
                 ctx.clone(),
                 session_start,
-            );
-            let sys_for_cb = sys_stream.clone();
-            let sys_cap = match start_raw_system_capture(
+            )
+        });
+        let mic_for_cb = mic_stream.clone();
+        let mic_callback: Arc<dyn Fn(&[f32]) + Send + Sync> =
+            Arc::new(move |samples: &[f32]| mic_for_cb.push(samples));
+        let system_callback: Option<Arc<dyn Fn(&[f32]) + Send + Sync>> =
+            sys_stream.as_ref().map(|stream| {
+                let stream = stream.clone();
+                Arc::new(move |samples: &[f32]| stream.push(samples))
+                    as Arc<dyn Fn(&[f32]) + Send + Sync>
+            });
+
+        let combined_cap = if should_use_combined_sck_capture(
+            owner,
+            supports_sck_microphone_capture(),
+        ) {
+            match start_raw_meeting_capture(
                 app.clone(),
-                Arc::new(move |s: &[f32]| sys_for_cb.push(s)),
+                mic_device_id.clone(),
+                mic_device_label.clone(),
+                capture_system,
+                mic_callback.clone(),
+                system_callback.clone(),
             ) {
-                Ok(cap) => cap,
+                Ok(cap) => {
+                    eprintln!("[whisper] using combined ScreenCaptureKit mic + system capture");
+                    Some(cap)
+                }
                 Err(e) => {
-                    // Roll back the mic side so we don't leave a half-open meeting.
+                    eprintln!(
+                        "[whisper] combined ScreenCaptureKit meeting capture failed: {e}; falling back to split capture"
+                    );
+                    None
+                }
+            }
+        } else {
+            None
+        };
+
+        let (mic_cap, sys_cap) = if let Some(combined_cap) = combined_cap {
+            // Both SCK outputs are configured at 48 kHz.
+            mic_stream.set_src_rate(48000.0);
+            (None, Some(combined_cap))
+        } else {
+            let reuse_voice_processing_engine = owner == SessionOwner::Dictation && !capture_system;
+            let mic_cap = start_raw_mic_capture(
+                app.clone(),
+                mic_device_id,
+                mic_device_label,
+                voice_processing,
+                reuse_voice_processing_engine,
+                mic_callback,
+            )
+            .map_err(|e| {
+                mic_stream.stop();
+                if let Some(sys_stream) = &sys_stream {
                     sys_stream.stop();
-                    mic_stream.stop();
-                    mic_cap.stop();
-                    return Err(format!("system capture failed: {e}"));
                 }
+                format!("mic capture failed: {e}")
+            })?;
+            mic_stream.set_src_rate(mic_cap.sample_rate());
+
+            let sys_cap = if let Some(system_callback) = system_callback {
+                match start_raw_system_capture(app.clone(), system_callback) {
+                    Ok(cap) => Some(cap),
+                    Err(e) => {
+                        if let Some(sys_stream) = &sys_stream {
+                            sys_stream.stop();
+                        }
+                        mic_stream.stop();
+                        mic_cap.stop();
+                        return Err(format!("system capture failed: {e}"));
+                    }
+                }
+            } else {
+                None
             };
-            (Some(sys_stream), Some(sys_cap))
-        } else {
-            (None, None)
+            (Some(mic_cap), sys_cap)
         };
 
         let mut slot = session_slot().lock().map_err(|e| e.to_string())?;
@@ -750,7 +808,9 @@ mod macos {
             sys.stop();
         }
         // Stop captures so no more samples arrive while workers flush.
-        session.mic_cap.stop();
+        if let Some(mic_cap) = session.mic_cap {
+            mic_cap.stop();
+        }
         if let Some(sys_cap) = session.sys_cap {
             sys_cap.stop();
         }
@@ -769,4 +829,22 @@ mod macos {
         }
         eprintln!("[whisper] meeting transcription stopped");
     }
+
+    #[cfg(test)]
+    mod tests {
+        use super::{should_use_combined_sck_capture, SessionOwner};
+
+        #[test]
+        fn combined_sck_capture_is_only_selected_for_supported_meetings() {
+            assert!(should_use_combined_sck_capture(SessionOwner::Meeting, true));
+            assert!(!should_use_combined_sck_capture(
+                SessionOwner::Meeting,
+                false
+            ));
+            assert!(!should_use_combined_sck_capture(
+                SessionOwner::Dictation,
+                true
+            ));
+        }
+    }
 }
diff --git a/templates/clips/desktop/src/app.tsx b/templates/clips/desktop/src/app.tsx
index 734acc7ec6..5236f08fcc 100644
--- a/templates/clips/desktop/src/app.tsx
+++ b/templates/clips/desktop/src/app.tsx
@@ -1527,6 +1527,10 @@ export function App() {
   // from THAT render and stops the camera stream even though recording is
   // still in flight.
   const recordingFlowGateRef = useRef(false);
+  // Stop detaches the recorder state before optimization/upload finishes so a
+  // fresh camera session can recover immediately. Keep that post-stop phase
+  // separate so React cleanup does not close the finalizing progress window.
+  const recordingStopFinalizingRef = useRef(false);
   useEffect(() => {
     recordingFlowGateRef.current = isRecording || recordingFlowActive;
   }, [isRecording, recordingFlowActive]);
@@ -1565,7 +1569,9 @@ export function App() {
       // Hide them from here instead. Guard on !recordingInFlight so
       // we don't rip the toolbar out from under an active recording.
       if (!recordingFlowGateRef.current) {
-        invoke("hide_overlays").catch(() => {});
+        invoke("hide_overlays", {
+          preserveFinalizing: recordingStopFinalizingRef.current,
+        }).catch(() => {});
       }
     };
   }, [toolbarActive]);
@@ -1721,7 +1727,9 @@ export function App() {
       // source changed (e.g. cameraId flip re-runs this effect): hiding
       // would race the re-run's show_bubble and close the window out from under it.
       if (!recordingInFlight && !bubbleActiveRef.current) {
-        invoke("hide_overlays").catch(() => {});
+        invoke("hide_overlays", {
+          preserveFinalizing: recordingStopFinalizingRef.current,
+        }).catch(() => {});
       }
     };
   }, [bubbleActive, cameraId, bubbleSessionEpoch]);
@@ -2351,6 +2359,7 @@ export function App() {
         // finalize; keeping `recorder` set through the whole upload made
         // reopen show a blank preview and made Start a silent no-op.
         const handle = recorder;
+        recordingStopFinalizingRef.current = true;
         bubbleStreamTransferredToRecorder.current = false;
         bubbleStreamRef.current = null;
         recordingFlowGateRef.current = false;
@@ -2381,6 +2390,7 @@ export function App() {
           setRecError(err instanceof Error ? err.message : String(err));
           await loadPendingUploads();
         } finally {
+          recordingStopFinalizingRef.current = false;
           invoke("set_recording_state", { active: false }).catch(() => {});
           if (stopFailed || stopResult?.localOnly) {
             invoke("show_popover").catch(() => {});
diff --git a/templates/clips/desktop/src/hooks/useMeetingTranscription.ts b/templates/clips/desktop/src/hooks/useMeetingTranscription.ts
index 0a311ac2df..d928fbb35a 100644
--- a/templates/clips/desktop/src/hooks/useMeetingTranscription.ts
+++ b/templates/clips/desktop/src/hooks/useMeetingTranscription.ts
@@ -377,7 +377,9 @@ export function useMeetingTranscription({
         };
 
         // Resume the engine that initial start settled on (no fallback here —
-        // the engine choice was already made below).
+        // the engine choice was already made below). Never add a second
+        // VoiceProcessingIO stack beside the meeting app: it can alter the
+        // microphone level that remote participants receive.
         const startAudio = async () => {
           await restartTranscriptionEngine(
             session.engine,
@@ -386,6 +388,7 @@ export function useMeetingTranscription({
               label: selectedMicLabel,
             },
             true,
+            false,
           );
         };
 
@@ -556,6 +559,10 @@ export function useMeetingTranscription({
 
         session.engine = await startTranscriptionEngine({
           mic: { deviceId: selectedMicId, label: selectedMicLabel },
+          // macOS 15+ uses ScreenCaptureKit's independent microphone output.
+          // The legacy fallback must also remain a raw tap so Zoom/Meet/Teams
+          // stay in sole control of their live-call voice processing.
+          voiceProcessing: false,
         });
 
         await invoke("silence_detector_start", {
diff --git a/templates/clips/desktop/src/lib/recorder.ts b/templates/clips/desktop/src/lib/recorder.ts
index 34f262462a..d586320701 100644
--- a/templates/clips/desktop/src/lib/recorder.ts
+++ b/templates/clips/desktop/src/lib/recorder.ts
@@ -2232,11 +2232,14 @@ async function startNativeFullscreenRecording(
             );
           }
 
-          const chromeCmd = wantsCamera
-            ? "hide_recording_chrome"
-            : "hide_overlays";
-          await invoke(chromeCmd).catch((err) =>
-            console.error(`[clips-recorder] ${chromeCmd} failed:`, err),
+          // The finalizing window owns the whole stop -> optimized upload ->
+          // browser-open gap. Only tear down recording chrome here; the outer
+          // finally closes finalizing after the clip has opened or failed.
+          await invoke("hide_recording_chrome").catch((err) =>
+            console.error(
+              "[clips-recorder] hide_recording_chrome failed:",
+              err,
+            ),
           );
           await invoke("native_fullscreen_capture_thumbnail", {
             serverUrl: params.serverUrl,
diff --git a/templates/clips/desktop/src/lib/transcription-engine.test.ts b/templates/clips/desktop/src/lib/transcription-engine.test.ts
index ebb49371a0..bdc2aed5e9 100644
--- a/templates/clips/desktop/src/lib/transcription-engine.test.ts
+++ b/templates/clips/desktop/src/lib/transcription-engine.test.ts
@@ -1,9 +1,58 @@
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import { recordingTranscriptionLanguage } from "./transcription-engine";
+const { invokeMock } = vi.hoisted(() => ({ invokeMock: vi.fn() }));
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: invokeMock }));
+vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
+
+import {
+  recordingTranscriptionLanguage,
+  restartTranscriptionEngine,
+  startTranscriptionEngine,
+} from "./transcription-engine";
+
+beforeEach(() => {
+  invokeMock.mockReset();
+  invokeMock.mockResolvedValue(undefined);
+});
 
 describe("recording transcription language", () => {
   it("leaves local Whisper recordings on auto-detect instead of forcing the UI locale", () => {
     expect(recordingTranscriptionLanguage()).toBeNull();
   });
 });
+
+describe("meeting microphone capture", () => {
+  it("starts without VoiceProcessingIO so call apps keep control of mic gain", async () => {
+    await startTranscriptionEngine({
+      mic: { deviceId: "mic-1", label: "Built-in Microphone" },
+    });
+
+    expect(invokeMock).toHaveBeenCalledWith("audio_transcription_start", {
+      meetingId: null,
+      locale: null,
+      micDeviceId: "mic-1",
+      micDeviceLabel: "Built-in Microphone",
+      captureSystem: true,
+      voiceProcessing: false,
+      owner: "meeting",
+    });
+  });
+
+  it("keeps VoiceProcessingIO off when meeting transcription resumes", async () => {
+    await restartTranscriptionEngine("whisper", {
+      deviceId: "mic-1",
+      label: "Built-in Microphone",
+    });
+
+    expect(invokeMock).toHaveBeenCalledWith("audio_transcription_start", {
+      meetingId: null,
+      locale: null,
+      micDeviceId: "mic-1",
+      micDeviceLabel: "Built-in Microphone",
+      captureSystem: true,
+      voiceProcessing: false,
+      owner: "meeting",
+    });
+  });
+});
diff --git a/templates/clips/desktop/src/lib/transcription-engine.ts b/templates/clips/desktop/src/lib/transcription-engine.ts
index fb866008ef..5b79f9e6c7 100644
--- a/templates/clips/desktop/src/lib/transcription-engine.ts
+++ b/templates/clips/desktop/src/lib/transcription-engine.ts
@@ -119,7 +119,7 @@ export async function restartTranscriptionEngine(
   engine: TranscriptionEngine,
   mic?: MicSelection,
   captureSystem: boolean = true,
-  voiceProcessing: boolean = true,
+  voiceProcessing: boolean = false,
 ): Promise<void> {
   if (engine === "whisper") {
     await invoke("audio_transcription_start", {
@@ -151,14 +151,14 @@ export async function startTranscriptionEngine(opts: {
   /** Capture + transcribe system audio (whisper). Default true. */
   captureSystem?: boolean;
   /**
-   * Enable Apple's voice-processing input mode for the Whisper mic tap. Native
-   * recordings disable this so the transcription tap does not reconfigure the
-   * shared microphone before ScreenCaptureKit opens it.
+   * Enable Apple's voice-processing input mode for the Whisper mic tap.
+   * Meeting and recording capture leave this off so Clips never adds a second
+   * VoIP processor beside Zoom, Meet, or Teams and changes their mic uplink.
    */
   voiceProcessing?: boolean;
 }): Promise<TranscriptionEngine> {
   const captureSystem = opts.captureSystem ?? true;
-  const voiceProcessing = opts.voiceProcessing ?? true;
+  const voiceProcessing = opts.voiceProcessing ?? false;
   try {
     await restartTranscriptionEngine(
       "whisper",
diff --git a/templates/clips/desktop/src/lib/voice-dictation.ts b/templates/clips/desktop/src/lib/voice-dictation.ts
index b169241bed..265a1cd3fc 100644
--- a/templates/clips/desktop/src/lib/voice-dictation.ts
+++ b/templates/clips/desktop/src/lib/voice-dictation.ts
@@ -1254,6 +1254,9 @@ export function installDesktopVoiceDictation(
         micDeviceId: concreteMediaDeviceId(micDeviceId) || null,
         micDeviceLabel: micDeviceLabel || null,
         captureSystem: false,
+        // Short, standalone dictation sessions benefit from Apple's AEC/AGC.
+        // Meeting and recording capture explicitly keep this disabled.
+        voiceProcessing: true,
         owner: "dictation",
       });
       console.log("[voice-dictation] audio_transcription_start ok");
diff --git a/templates/clips/desktop/src/styles.css b/templates/clips/desktop/src/styles.css
index 6fa37464da..15f8931cd1 100644
--- a/templates/clips/desktop/src/styles.css
+++ b/templates/clips/desktop/src/styles.css
@@ -25,9 +25,11 @@
   --radius: 12px;
   --radius-sm: 8px;
   --radius-pill: 999px;
-  /* Must cover `--shadow-md` blur (24px in dark mode) or the transparent
-     Tauri window clips the drop shadow on every edge. */
+  /* Keep the side and bottom shadow clear of the transparent Tauri window.
+     The top is intentionally tighter: the popover should feel attached to
+     its menu-bar icon, where a clipped shadow is not visible anyway. */
   --popover-shadow-gutter: 24px;
+  --popover-shadow-gutter-top: 6px;
   --overlay-shadow-gutter: 18px;
 
   --shadow-sm: 0 1px 2px rgba(23, 23, 23, 0.06);
@@ -106,7 +108,8 @@ button {
 
 body[data-clips-route="popover"] #root {
   min-height: 100vh;
-  padding: var(--popover-shadow-gutter);
+  padding: var(--popover-shadow-gutter-top) var(--popover-shadow-gutter)
+    var(--popover-shadow-gutter);
 }
 
 body[data-clips-route]:not([data-clips-route="popover"]) #root {
diff --git a/templates/clips/server/lib/slack-unfurls.test.ts b/templates/clips/server/lib/slack-unfurls.test.ts
index 2b6aa8b950..1e01df4ff9 100644
--- a/templates/clips/server/lib/slack-unfurls.test.ts
+++ b/templates/clips/server/lib/slack-unfurls.test.ts
@@ -29,6 +29,7 @@ function recording(overrides: Record<string, unknown> = {}) {
     id: "rec-1",
     title: "Launch walkthrough",
     description: "A product walkthrough",
+    durationMs: 222_000,
     thumbnailUrl: "/api/media/thumb",
     animatedThumbnailUrl: null,
     visibility: "public",
@@ -114,12 +115,30 @@ describe("Clips Slack unfurls", () => {
     ).toMatchObject({
       type: "video",
       title_url: "https://clips.example.com/share/rec-1",
+      description: {
+        type: "plain_text",
+        text: "3:42 · A product walkthrough",
+        emoji: true,
+      },
       video_url: "https://clips.example.com/embed/rec-1?autoplay=1",
       thumbnail_url: "https://clips.example.com/api/media/thumb",
       provider_name: "Clips",
     });
   });
 
+  it("omits unknown durations from Slack video descriptions", () => {
+    expect(
+      buildSlackVideoBlock({
+        recording: recording({ durationMs: 0 }),
+        origin: "https://clips.example.com",
+      }),
+    ).toMatchObject({
+      description: {
+        text: "A product walkthrough",
+      },
+    });
+  });
+
   it("does not build playable unfurls for password-protected clips", () => {
     expect(
       buildSlackVideoBlock({
diff --git a/templates/clips/server/lib/slack-unfurls.ts b/templates/clips/server/lib/slack-unfurls.ts
index babec69554..78a140b449 100644
--- a/templates/clips/server/lib/slack-unfurls.ts
+++ b/templates/clips/server/lib/slack-unfurls.ts
@@ -28,6 +28,7 @@ type SlackUnfurlRecording = {
   id: string;
   title: string;
   description: string;
+  durationMs: number;
   thumbnailUrl: string | null;
   animatedThumbnailUrl: string | null;
   visibility: string | null;
@@ -205,6 +206,19 @@ function isExpired(value: string | null): boolean {
   return Number.isFinite(expires) && expires < Date.now();
 }
 
+function formatSlackDuration(durationMs: number): string | null {
+  if (!Number.isFinite(durationMs) || durationMs <= 0) return null;
+  const totalSeconds = Math.floor(durationMs / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return hours > 0
+    ? `${hours}:${minutes.toString().padStart(2, "0")}:${seconds
+        .toString()
+        .padStart(2, "0")}`
+    : `${minutes}:${seconds.toString().padStart(2, "0")}`;
+}
+
 export function isSlackPlayableRecording(
   recording: SlackUnfurlRecording,
 ): boolean {
@@ -236,7 +250,11 @@ export function buildSlackVideoBlock(options: {
     origin,
   ).toString();
   const title = displayRecordingTitle(recording.title);
-  const description = clipsShareDescription(recording);
+  const shareDescription = clipsShareDescription(recording);
+  const duration = formatSlackDuration(recording.durationMs);
+  const description = duration
+    ? `${duration} · ${shareDescription}`
+    : shareDescription;
   const thumbnailUrl = absoluteUrl(
     recording.thumbnailUrl || recording.animatedThumbnailUrl,
     origin,
@@ -265,6 +283,7 @@ export async function loadSlackVideoBlockForUrl(
       id: schema.recordings.id,
       title: schema.recordings.title,
       description: schema.recordings.description,
+      durationMs: schema.recordings.durationMs,
       thumbnailUrl: schema.recordings.thumbnailUrl,
       animatedThumbnailUrl: schema.recordings.animatedThumbnailUrl,
       visibility: schema.recordings.visibility,
diff --git a/templates/clips/server/lib/streaming-upload-mode.test.ts b/templates/clips/server/lib/streaming-upload-mode.test.ts
index 7c21a9bd31..d85d481a26 100644
--- a/templates/clips/server/lib/streaming-upload-mode.test.ts
+++ b/templates/clips/server/lib/streaming-upload-mode.test.ts
@@ -41,6 +41,25 @@ describe("streaming upload mode", () => {
     expect(shouldEnableStreamingUpload({ mimeType: undefined })).toBe(false);
   });
 
+  it("enables requested video streaming when buffered fallback is unavailable", () => {
+    delete process.env.CLIPS_DISABLE_STREAMING_UPLOAD;
+    delete process.env.CLIPS_ENABLE_STREAMING_UPLOAD;
+
+    expect(
+      shouldEnableStreamingUpload({
+        client: "desktop-native",
+        mimeType: "video/mp4",
+        bufferedFallbackAvailable: false,
+      }),
+    ).toBe(true);
+    expect(
+      shouldEnableStreamingUpload({
+        mimeType: "audio/webm",
+        bufferedFallbackAvailable: false,
+      }),
+    ).toBe(false);
+  });
+
   it("honors explicit enable and disable flags", () => {
     process.env.CLIPS_ENABLE_STREAMING_UPLOAD = "true";
     delete process.env.CLIPS_DISABLE_STREAMING_UPLOAD;
diff --git a/templates/clips/server/lib/streaming-upload-mode.ts b/templates/clips/server/lib/streaming-upload-mode.ts
index 9d6a83ddb1..e9af04761a 100644
--- a/templates/clips/server/lib/streaming-upload-mode.ts
+++ b/templates/clips/server/lib/streaming-upload-mode.ts
@@ -1,8 +1,8 @@
 import { enabledFlag } from "./env-flags.js";
 
-// Streaming resumable uploads are deployment opt-in while the provider/finalize
-// path hardens. Set CLIPS_ENABLE_STREAMING_UPLOAD=1 to allow recorder requests;
-// CLIPS_DISABLE_STREAMING_UPLOAD=1 still forces the buffered fallback.
+// Local/dev deployments can opt into resumable uploads while retaining their
+// SQL scratch fallback. Hosted deployments have no safe buffered fallback, so
+// requested video uploads use resumable storage unless explicitly disabled.
 export function isStreamingUploadDisabled(): boolean {
   return enabledFlag(process.env.CLIPS_DISABLE_STREAMING_UPLOAD);
 }
@@ -10,9 +10,15 @@ export function isStreamingUploadDisabled(): boolean {
 export function shouldEnableStreamingUpload(args: {
   client?: string | null;
   mimeType?: string | null;
+  bufferedFallbackAvailable?: boolean;
 }): boolean {
   if (isStreamingUploadDisabled()) return false;
-  if (!enabledFlag(process.env.CLIPS_ENABLE_STREAMING_UPLOAD)) return false;
+  if (
+    args.bufferedFallbackAvailable !== false &&
+    !enabledFlag(process.env.CLIPS_ENABLE_STREAMING_UPLOAD)
+  ) {
+    return false;
+  }
 
   const mimeType = (args.mimeType ?? "").split(";")[0]?.trim().toLowerCase();
   return !mimeType || mimeType.startsWith("video/");
diff --git a/templates/clips/shared/recording-core.test.ts b/templates/clips/shared/recording-core.test.ts
index 2197cffa78..43bdeebc0b 100644
--- a/templates/clips/shared/recording-core.test.ts
+++ b/templates/clips/shared/recording-core.test.ts
@@ -1,8 +1,18 @@
 import { describe, expect, it } from "vitest";
 
-import { chunkUploadQuery, normalizeChunkUploadNumber } from "./recording-core";
+import {
+  chunkUploadParallelism,
+  chunkUploadQuery,
+  normalizeChunkUploadNumber,
+} from "./recording-core";
 
 describe("recording upload URL helpers", () => {
+  it("serializes resumable chunks while keeping buffered upload parallelism", () => {
+    expect(chunkUploadParallelism("streaming", 4)).toBe(1);
+    expect(chunkUploadParallelism("buffered", 4)).toBe(4);
+    expect(chunkUploadParallelism(undefined, 0)).toBe(1);
+  });
+
   it("normalizes finite upload metadata before encoding", () => {
     expect(normalizeChunkUploadNumber("1200.6")).toBe(1201);
     expect(normalizeChunkUploadNumber(-12)).toBe(0);
diff --git a/templates/clips/shared/recording-core.ts b/templates/clips/shared/recording-core.ts
index ebabc8ff60..58a6fb02b9 100644
--- a/templates/clips/shared/recording-core.ts
+++ b/templates/clips/shared/recording-core.ts
@@ -51,6 +51,18 @@ export function pickMimeType(): string {
  *  - `"buffered"`  — full blob assembled after stop() and uploaded in slices */
 export type UploadMode = "streaming" | "buffered";
 
+/**
+ * Resumable providers advance a single byte offset, so their chunks must be
+ * sent in strict index order. Buffered uploads can retain bounded parallelism.
+ */
+export function chunkUploadParallelism(
+  uploadMode: UploadMode | undefined,
+  bufferedParallelism: number,
+): number {
+  if (uploadMode === "streaming") return 1;
+  return Math.max(1, Math.floor(bufferedParallelism));
+}
+
 /** Query params understood by the chunk-upload route
  * (`/api/uploads/:id/chunk`). This is the on-the-wire contract — the route in
  * `server/routes/api/uploads/[recordingId]/chunk.post.ts` reads exactly these. */
diff --git a/templates/content/AGENTS.md b/templates/content/AGENTS.md
index 3ab6e47447..51b42ce2c8 100644
--- a/templates/content/AGENTS.md
+++ b/templates/content/AGENTS.md
@@ -158,13 +158,14 @@ to SQL. `pull-document` closes that gap with a flush handshake — if a live Yjs
 collab session exists for the document it writes a one-shot `flush-request-<id>`
 application-state key (scoped to the browser session, just like `navigate`); the
 open editor sees that key, serializes its current document to markdown through
-its own existing serializer, calls `update-document`, and deletes the key;
-`pull-document` waits for the key to clear and then returns the now-fresh row.
-When no editor is open the SQL column is authoritative and the handshake is
+its own existing serializer, calls `update-document`, and writes an explicit
+request-id-matched success/error acknowledgement. `pull-document` waits for that
+acknowledgement and fails closed if the open editor cannot save; when no active
+human editor is present, the SQL column is authoritative and the handshake is
 skipped. It is GET + read-only + public-agent exposed (`requiresAuth: true`),
-returns `{ id, title, content, format, deepLink }`, and surfaces an
-"Open document" deep link for external agents. Use `--format text` for a
-plain-text strip of the markdown.
+returns `{ id, title, content, format, deepLink }`, and surfaces an "Open
+document" deep link for external agents. Use `--format text` for a plain-text
+strip of the markdown.
 
 ### Local Source Files
 
diff --git a/templates/content/actions/_builder-docs-client.test.ts b/templates/content/actions/_builder-docs-client.test.ts
index 11b0339986..d64630c440 100644
--- a/templates/content/actions/_builder-docs-client.test.ts
+++ b/templates/content/actions/_builder-docs-client.test.ts
@@ -25,6 +25,10 @@ const resolveBuilderCredentialMock = vi.hoisted(() =>
 
 const collabStateMock = vi.hoisted(() => ({
   hasCollabState: vi.fn(async () => false),
+  loadAwarenessRowsStrict: vi.fn(
+    async () =>
+      [] as Array<{ clientId: number; state: string; lastSeen: number }>,
+  ),
 }));
 
 const appStateMock = vi.hoisted(() => ({
@@ -123,7 +127,9 @@ vi.mock("@agent-native/core/server/request-context", () => ({
 }));
 
 vi.mock("@agent-native/core/collab", () => ({
+  AGENT_CLIENT_ID: 0xffffffff,
   hasCollabState: collabStateMock.hasCollabState,
+  loadAwarenessRowsStrict: collabStateMock.loadAwarenessRowsStrict,
 }));
 
 vi.mock("@agent-native/core/application-state", () => ({
@@ -190,6 +196,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   resolveBuilderCredentialMock.mockResolvedValue(null);
   collabStateMock.hasCollabState.mockResolvedValue(false);
+  collabStateMock.loadAwarenessRowsStrict.mockResolvedValue([]);
   appStateMock.appStateGet.mockResolvedValue(null);
   builderWriteMock.executeBuilderCmsWrite.mockResolvedValue({
     ok: true,
@@ -399,6 +406,21 @@ describe("Builder docs DB-backed source", () => {
       sourceUpdatedAt: bundle.mdx.metadata.lastUpdated,
     };
     collabStateMock.hasCollabState.mockResolvedValue(true);
+    collabStateMock.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 123,
+        state: JSON.stringify({
+          visible: true,
+          user: { email: "owner@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+    appStateMock.appStateGet.mockImplementation(async () => ({
+      id: bundle.mdx.documentId,
+      requestId: appStateMock.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "success",
+    }));
 
     await resolveBuilderDocsSource({ documentId: bundle.mdx.documentId });
 
diff --git a/templates/content/actions/_document-flush.test.ts b/templates/content/actions/_document-flush.test.ts
new file mode 100644
index 0000000000..2708b11b44
--- /dev/null
+++ b/templates/content/actions/_document-flush.test.ts
@@ -0,0 +1,370 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  appStateDelete: vi.fn(),
+  appStateGet: vi.fn(),
+  appStatePut: vi.fn(),
+  getRequestUserEmail: vi.fn(),
+  hasCollabState: vi.fn(),
+  loadAwarenessRowsStrict: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/application-state", () => ({
+  appStateDelete: mocks.appStateDelete,
+  appStateGet: mocks.appStateGet,
+  appStatePut: mocks.appStatePut,
+}));
+
+vi.mock("@agent-native/core/collab", () => ({
+  AGENT_CLIENT_ID: 0xffffffff,
+  hasCollabState: mocks.hasCollabState,
+  loadAwarenessRowsStrict: mocks.loadAwarenessRowsStrict,
+}));
+
+vi.mock("@agent-native/core/server/request-context", () => ({
+  getRequestUserEmail: mocks.getRequestUserEmail,
+}));
+
+import { flushOpenDocumentEditorToSql } from "./_document-flush";
+
+describe("flushOpenDocumentEditorToSql", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    mocks.hasCollabState.mockResolvedValue(true);
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 123,
+        state: JSON.stringify({
+          canFlushDocument: true,
+          visible: true,
+          user: { email: "owner@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+    mocks.getRequestUserEmail.mockReturnValue("editor@example.com");
+    mocks.appStatePut.mockResolvedValue(undefined);
+    mocks.appStateDelete.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("completes after an open editor acknowledges the flush", async () => {
+    mocks.appStateGet.mockImplementation(async () => ({
+      id: "doc-1",
+      requestId: mocks.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "success",
+    }));
+
+    const flush = flushOpenDocumentEditorToSql({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+    await vi.advanceTimersByTimeAsync(200);
+
+    await expect(flush).resolves.toBeUndefined();
+    expect(mocks.appStatePut).toHaveBeenCalledWith(
+      "owner@example.com",
+      "flush-request-doc-1",
+      expect.objectContaining({ id: "doc-1" }),
+      { requestSource: "agent" },
+    );
+  });
+
+  it("fails closed when the live editor reports a save error", async () => {
+    mocks.appStateGet.mockImplementation(async () => ({
+      id: "doc-1",
+      requestId: mocks.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "error",
+      error: "The document changed while preparing it for sync.",
+    }));
+
+    const flush = flushOpenDocumentEditorToSql({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+    const rejected = expect(flush).rejects.toThrow(
+      "The document changed while preparing it for sync.",
+    );
+    await vi.advanceTimersByTimeAsync(200);
+
+    await rejected;
+    expect(mocks.appStateDelete).toHaveBeenCalled();
+  });
+
+  it("fails closed when no active editor acknowledges before timeout", async () => {
+    mocks.appStateGet.mockImplementation(async () => ({
+      id: "doc-1",
+      requestId: mocks.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "pending",
+    }));
+
+    const flush = flushOpenDocumentEditorToSql({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+    const rejected = expect(flush).rejects.toThrow(/did not finish saving/i);
+    await vi.advanceTimersByTimeAsync(4_200);
+
+    await rejected;
+  });
+
+  it("fails closed when the flush request cannot be written", async () => {
+    mocks.appStatePut.mockRejectedValue(new Error("connection unavailable"));
+
+    await expect(
+      flushOpenDocumentEditorToSql({
+        documentId: "doc-1",
+        ownerEmail: "owner@example.com",
+      }),
+    ).rejects.toThrow(/could not ask the open document editor/i);
+  });
+
+  it("fails closed when active-editor awareness cannot be read", async () => {
+    mocks.loadAwarenessRowsStrict.mockRejectedValue(
+      new Error("awareness storage unavailable"),
+    );
+
+    await expect(
+      flushOpenDocumentEditorToSql({
+        documentId: "doc-1",
+        ownerEmail: "owner@example.com",
+      }),
+    ).rejects.toThrow("awareness storage unavailable");
+    expect(mocks.appStatePut).not.toHaveBeenCalled();
+  });
+
+  it("skips the handshake when only persisted Yjs state remains", async () => {
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([]);
+
+    await expect(
+      flushOpenDocumentEditorToSql({
+        documentId: "doc-1",
+        ownerEmail: "owner@example.com",
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(mocks.appStatePut).not.toHaveBeenCalled();
+  });
+
+  it("uses SQL immediately when the only active collaborators are modern read-only viewers", async () => {
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 123,
+        state: JSON.stringify({
+          canFlushDocument: false,
+          visible: true,
+          user: { email: "viewer@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+
+    await expect(
+      flushOpenDocumentEditorToSql({
+        documentId: "doc-1",
+        ownerEmail: "owner@example.com",
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(mocks.appStatePut).not.toHaveBeenCalled();
+    expect(mocks.appStateGet).not.toHaveBeenCalled();
+  });
+
+  it("accepts an acknowledgement from a legacy editor without a capability field", async () => {
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 456,
+        state: JSON.stringify({
+          visible: true,
+          user: { email: "legacy-editor@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+    mocks.appStateGet.mockImplementation(async () => ({
+      id: "doc-1",
+      requestId: mocks.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "success",
+    }));
+
+    const flush = flushOpenDocumentEditorToSql({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+    await vi.advanceTimersByTimeAsync(200);
+
+    await expect(flush).resolves.toBeUndefined();
+    expect(mocks.appStatePut).toHaveBeenCalledWith(
+      "legacy-editor@example.com",
+      "flush-request-doc-1",
+      expect.objectContaining({ id: "doc-1" }),
+      { requestSource: "agent" },
+    );
+  });
+
+  it("honors an explicit save error from a legacy editor", async () => {
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 456,
+        state: JSON.stringify({
+          visible: true,
+          user: { email: "legacy-editor@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+    mocks.appStateGet.mockImplementation(async () => ({
+      id: "doc-1",
+      requestId: mocks.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "error",
+      error: "Legacy editor could not serialize the live document.",
+    }));
+
+    const flush = flushOpenDocumentEditorToSql({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+    const rejected = expect(flush).rejects.toThrow(
+      "Legacy editor could not serialize the live document.",
+    );
+    await vi.advanceTimersByTimeAsync(200);
+
+    await rejected;
+  });
+
+  it("falls back to SQL after a legacy-only editor handshake stays silent", async () => {
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 456,
+        state: JSON.stringify({
+          visible: true,
+          user: { email: "legacy-viewer-or-editor@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+    mocks.appStateGet.mockImplementation(async () => ({
+      id: "doc-1",
+      requestId: mocks.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "pending",
+    }));
+
+    const flush = flushOpenDocumentEditorToSql({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+    await vi.advanceTimersByTimeAsync(4_200);
+
+    await expect(flush).resolves.toBeUndefined();
+    expect(mocks.appStatePut).toHaveBeenCalledWith(
+      "legacy-viewer-or-editor@example.com",
+      "flush-request-doc-1",
+      expect.objectContaining({ id: "doc-1" }),
+      { requestSource: "agent" },
+    );
+    expect(mocks.appStateDelete).toHaveBeenCalled();
+  });
+
+  it("falls back to SQL when a legacy-only flush request cannot be written", async () => {
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 456,
+        state: JSON.stringify({
+          visible: true,
+          user: { email: "legacy-editor@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+    mocks.appStatePut.mockRejectedValue(new Error("connection unavailable"));
+
+    await expect(
+      flushOpenDocumentEditorToSql({
+        documentId: "doc-1",
+        ownerEmail: "owner@example.com",
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("still waits when an edit-capable collaborator is present beside viewers", async () => {
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 123,
+        state: JSON.stringify({
+          canFlushDocument: false,
+          visible: true,
+          user: { email: "viewer@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+      {
+        clientId: 456,
+        state: JSON.stringify({
+          canFlushDocument: true,
+          visible: true,
+          user: { email: "shared-editor@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+    mocks.appStateGet.mockImplementation(async () => ({
+      id: "doc-1",
+      requestId: mocks.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "success",
+    }));
+
+    const flush = flushOpenDocumentEditorToSql({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+    await vi.advanceTimersByTimeAsync(200);
+
+    await expect(flush).resolves.toBeUndefined();
+    expect(mocks.appStatePut).toHaveBeenCalledWith(
+      "shared-editor@example.com",
+      "flush-request-doc-1",
+      expect.objectContaining({ id: "doc-1" }),
+      { requestSource: "agent" },
+    );
+  });
+
+  it("still fails closed when a modern editor is silent beside a legacy tab", async () => {
+    mocks.loadAwarenessRowsStrict.mockResolvedValue([
+      {
+        clientId: 123,
+        state: JSON.stringify({
+          canFlushDocument: true,
+          visible: true,
+          user: { email: "modern-editor@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+      {
+        clientId: 456,
+        state: JSON.stringify({
+          visible: true,
+          user: { email: "legacy-viewer-or-editor@example.com" },
+        }),
+        lastSeen: Date.now(),
+      },
+    ]);
+    mocks.appStateGet.mockImplementation(async () => ({
+      id: "doc-1",
+      requestId: mocks.appStatePut.mock.calls[0]?.[2]?.requestId,
+      status: "pending",
+    }));
+
+    const flush = flushOpenDocumentEditorToSql({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+    const rejected = expect(flush).rejects.toThrow(/did not finish saving/i);
+    await vi.advanceTimersByTimeAsync(4_200);
+
+    await rejected;
+  });
+});
diff --git a/templates/content/actions/_document-flush.ts b/templates/content/actions/_document-flush.ts
index cce844c6b1..cd102e79eb 100644
--- a/templates/content/actions/_document-flush.ts
+++ b/templates/content/actions/_document-flush.ts
@@ -1,62 +1,177 @@
+import { randomUUID } from "node:crypto";
+
 import {
   appStateDelete,
   appStateGet,
   appStatePut,
 } from "@agent-native/core/application-state";
-import { hasCollabState } from "@agent-native/core/collab";
+import {
+  AGENT_CLIENT_ID,
+  hasCollabState,
+  loadAwarenessRowsStrict,
+} from "@agent-native/core/collab";
 import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 
 const FLUSH_POLL_INTERVAL_MS = 200;
 const FLUSH_TIMEOUT_MS = 4000;
 
+function parseAwarenessState(state: string): {
+  canFlushDocument?: unknown;
+  visible?: boolean;
+  user?: { email?: unknown };
+} | null {
+  try {
+    return JSON.parse(state) as {
+      canFlushDocument?: unknown;
+      visible?: boolean;
+      user?: { email?: unknown };
+    };
+  } catch {
+    return null;
+  }
+}
+
+function awarenessFlushCandidate(entry: {
+  clientId: number;
+  state: string;
+}): { sessionEmail: string | null; required: boolean } | null {
+  if (entry.clientId === AGENT_CLIENT_ID) return null;
+  const state = parseAwarenessState(entry.state);
+  if (!state || state.visible === false || !state.user) return null;
+  // New clients publish an exact boolean. `false` is a known read-only viewer
+  // and must never block. A missing field is a pre-deploy client which may be
+  // an editor, so offer it the old handshake on a best-effort basis. Invalid
+  // values are neither a trustworthy editor capability nor a legacy omission.
+  if (state.canFlushDocument !== true && state.canFlushDocument !== undefined) {
+    return null;
+  }
+  const email = state.user.email;
+  return {
+    sessionEmail:
+      typeof email === "string" && email.trim() ? email.trim() : null,
+    required: state.canFlushDocument === true,
+  };
+}
+
 export async function flushOpenDocumentEditorToSql(args: {
   documentId: string;
   ownerEmail?: string | null;
 }) {
   // If a live Yjs collab session is open, the in-memory editor doc is fresher
   // than the SQL column. Ask the open editor to serialize + save, then wait
-  // for it to acknowledge by clearing the flush-request key.
+  // for an explicit request-id-matched acknowledgement.
   if (!(await hasCollabState(args.documentId))) return;
 
+  // Persisted Yjs state outlives browser tabs. Modern clients distinguish
+  // editors (`true`) from viewers (`false`), so only the former are a hard
+  // freshness barrier. Pre-deploy tabs omit the field; they still know how to
+  // service this request, but may also be legacy viewers, so offer them the
+  // bounded handshake without failing if they stay silent. This preserves live
+  // legacy editor changes without making viewer-only tabs time out sync actions.
+  const awarenessRows = await loadAwarenessRowsStrict(args.documentId);
+  const flushCandidates = awarenessRows
+    .map(awarenessFlushCandidate)
+    .filter((candidate): candidate is NonNullable<typeof candidate> => {
+      return candidate !== null;
+    });
+  if (flushCandidates.length === 0) return;
+  const acknowledgementRequired = flushCandidates.some(
+    (candidate) => candidate.required,
+  );
+  const activeSessionEmails = flushCandidates
+    .map((candidate) => candidate.sessionEmail)
+    .filter((email): email is string => !!email);
+
   const flushKey = `flush-request-${args.documentId}`;
   // The editor polls `flush-request-<id>` via the framework app-state route,
-  // which scopes reads to the logged-in browser user (the document owner).
-  // Writing under the caller's (external agent's) session alone can miss the
-  // human editor tab, so write under both plausible sessions and de-dupe.
+  // which scopes reads to the logged-in browser user. Target every active
+  // collaborator email plus owner/caller fallbacks so shared editors and
+  // cross-instance actions reach the tab that can serialize the live Y.Doc.
   const callerEmail = getRequestUserEmail() || undefined;
   const targetSessions = Array.from(
     new Set(
-      [args.ownerEmail ?? undefined, callerEmail].filter(
-        (s): s is string => typeof s === "string" && s.length > 0,
-      ),
+      [
+        ...activeSessionEmails,
+        args.ownerEmail ?? undefined,
+        callerEmail,
+      ].filter((s): s is string => typeof s === "string" && s.length > 0),
     ),
   );
-  if (targetSessions.length === 0) return;
+  if (targetSessions.length === 0) {
+    if (!acknowledgementRequired) return;
+    throw new Error("Could not identify the open document editor to flush.");
+  }
 
-  const flushValue = { id: args.documentId, ts: Date.now() };
-  await Promise.all(
+  const requestId = randomUUID();
+  const flushValue = {
+    id: args.documentId,
+    ts: Date.now(),
+    requestId,
+    status: "pending",
+  };
+  const writes = await Promise.allSettled(
     targetSessions.map((session) =>
       appStatePut(session, flushKey, flushValue, {
         requestSource: "agent",
-      }).catch(() => {}),
+      }),
     ),
   );
+  const writtenSessions = targetSessions.filter(
+    (_session, index) => writes[index]?.status === "fulfilled",
+  );
+  if (writtenSessions.length === 0) {
+    if (!acknowledgementRequired) return;
+    throw new Error("Could not ask the open document editor to save.");
+  }
 
   const deadline = Date.now() + FLUSH_TIMEOUT_MS;
+  let flushError: string | null = null;
+  let acknowledged = false;
   while (Date.now() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, FLUSH_POLL_INTERVAL_MS));
-    const pending = await Promise.all(
-      targetSessions.map((session) => appStateGet(session, flushKey)),
+    const reads = await Promise.allSettled(
+      writtenSessions.map((session) => appStateGet(session, flushKey)),
+    );
+    const responses = reads.flatMap((result) =>
+      result.status === "fulfilled" && result.value ? [result.value] : [],
+    );
+    const failed = responses.find(
+      (
+        value,
+      ): value is {
+        requestId: string;
+        status: "error";
+        error?: string;
+      } => value.requestId === requestId && value.status === "error",
+    );
+    if (failed) {
+      flushError =
+        typeof failed.error === "string" && failed.error.trim()
+          ? failed.error
+          : "The live document could not be saved before syncing.";
+      break;
+    }
+    acknowledged = responses.some(
+      (value) => value.requestId === requestId && value.status === "success",
     );
-    if (pending.every((value) => !value)) break;
+    if (acknowledged) break;
   }
 
-  // Best-effort cleanup if the editor never picked it up (no tab open).
+  // Best-effort cleanup after success, explicit failure, or timeout.
   await Promise.all(
-    targetSessions.map((session) =>
+    writtenSessions.map((session) =>
       appStateDelete(session, flushKey, { requestSource: "agent" }).catch(
         () => {},
       ),
     ),
   );
+
+  if (flushError) {
+    throw new Error(flushError);
+  }
+  if (!acknowledged && acknowledgementRequired) {
+    throw new Error(
+      "The open document editor did not finish saving before sync timed out.",
+    );
+  }
 }
diff --git a/templates/content/actions/_notion-action-utils.test.ts b/templates/content/actions/_notion-action-utils.test.ts
index 393b483d04..0839511b74 100644
--- a/templates/content/actions/_notion-action-utils.test.ts
+++ b/templates/content/actions/_notion-action-utils.test.ts
@@ -4,6 +4,7 @@ const mocks = vi.hoisted(() => ({
   getRequestOrgId: vi.fn(),
   getRequestUserEmail: vi.fn(),
   assertAccess: vi.fn(),
+  flushOpenDocumentEditorToSql: vi.fn(),
 }));
 
 vi.mock("@agent-native/core/server", () => ({
@@ -15,7 +16,12 @@ vi.mock("@agent-native/core/sharing", () => ({
   assertAccess: mocks.assertAccess,
 }));
 
+vi.mock("./_document-flush.js", () => ({
+  flushOpenDocumentEditorToSql: mocks.flushOpenDocumentEditorToSql,
+}));
+
 import {
+  flushNotionDocumentEditor,
   getCurrentNotionOwner,
   getNotionDocumentOwner,
   resolveDocumentId,
@@ -25,6 +31,7 @@ beforeEach(() => {
   mocks.getRequestOrgId.mockReset();
   mocks.getRequestUserEmail.mockReset();
   mocks.assertAccess.mockReset();
+  mocks.flushOpenDocumentEditorToSql.mockReset();
 });
 
 describe("getCurrentNotionOwner", () => {
@@ -103,6 +110,19 @@ describe("getNotionDocumentOwner", () => {
   });
 });
 
+describe("flushNotionDocumentEditor", () => {
+  it("flushes the open editor under the document owner's session", async () => {
+    mocks.flushOpenDocumentEditorToSql.mockResolvedValue(undefined);
+
+    await flushNotionDocumentEditor("doc-1", "owner@example.com");
+
+    expect(mocks.flushOpenDocumentEditorToSql).toHaveBeenCalledWith({
+      documentId: "doc-1",
+      ownerEmail: "owner@example.com",
+    });
+  });
+});
+
 describe("resolveDocumentId", () => {
   it("prefers documentId over id", () => {
     expect(resolveDocumentId({ documentId: "a", id: "b" })).toBe("a");
diff --git a/templates/content/actions/_notion-action-utils.ts b/templates/content/actions/_notion-action-utils.ts
index 2e842bb35e..0df8bb36aa 100644
--- a/templates/content/actions/_notion-action-utils.ts
+++ b/templates/content/actions/_notion-action-utils.ts
@@ -4,6 +4,8 @@ import {
 } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
 
+import { flushOpenDocumentEditorToSql } from "./_document-flush.js";
+
 export function getCurrentNotionOwner() {
   const owner = getRequestUserEmail();
   if (!owner) throw new Error("no authenticated user");
@@ -23,6 +25,19 @@ export async function getNotionDocumentOwner(documentId: string) {
   return owner;
 }
 
+/**
+ * Flush the live collaborative editor before a user-triggered Notion operation
+ * reads or replaces SQL content. The Y.Doc can be ahead of the debounced
+ * documents row; without this handshake "Use local" can push a stale snapshot,
+ * while "Use Notion" can discard edits that never reached version history.
+ */
+export async function flushNotionDocumentEditor(
+  documentId: string,
+  ownerEmail: string,
+) {
+  await flushOpenDocumentEditorToSql({ documentId, ownerEmail });
+}
+
 export function resolveDocumentId(args: { documentId?: string; id?: string }) {
   const documentId = args.documentId?.trim() || args.id?.trim();
   if (!documentId) {
diff --git a/templates/content/actions/create-and-link-notion-page.ts b/templates/content/actions/create-and-link-notion-page.ts
index dc33161ccf..753afc5d72 100644
--- a/templates/content/actions/create-and-link-notion-page.ts
+++ b/templates/content/actions/create-and-link-notion-page.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { createAndLinkNotionPage } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -18,6 +19,7 @@ export default defineAction({
   run: async (args) => {
     const documentId = resolveDocumentId(args);
     const owner = await getNotionDocumentOwner(documentId);
+    await flushNotionDocumentEditor(documentId, owner);
     return createAndLinkNotionPage(owner, documentId, args.parentPageIdOrUrl);
   },
 });
diff --git a/templates/content/actions/link-notion-page.ts b/templates/content/actions/link-notion-page.ts
index a7a70e2c66..d035fabaae 100644
--- a/templates/content/actions/link-notion-page.ts
+++ b/templates/content/actions/link-notion-page.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { linkDocumentToNotionPage } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -26,6 +27,7 @@ export default defineAction({
     }
 
     const owner = await getNotionDocumentOwner(documentId);
+    await flushNotionDocumentEditor(documentId, owner);
     return linkDocumentToNotionPage(owner, documentId, pageIdOrUrl);
   },
 });
diff --git a/templates/content/actions/notion-flush-actions.test.ts b/templates/content/actions/notion-flush-actions.test.ts
new file mode 100644
index 0000000000..1ac88354f3
--- /dev/null
+++ b/templates/content/actions/notion-flush-actions.test.ts
@@ -0,0 +1,114 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  createAndLinkNotionPage: vi.fn(),
+  flushNotionDocumentEditor: vi.fn(),
+  getNotionDocumentOwner: vi.fn(),
+  linkDocumentToNotionPage: vi.fn(),
+  pullDocumentFromNotion: vi.fn(),
+  pushDocumentToNotion: vi.fn(),
+  resolveDocumentSyncConflict: vi.fn(),
+}));
+
+vi.mock("../server/lib/notion-sync.js", () => ({
+  createAndLinkNotionPage: mocks.createAndLinkNotionPage,
+  linkDocumentToNotionPage: mocks.linkDocumentToNotionPage,
+  pullDocumentFromNotion: mocks.pullDocumentFromNotion,
+  pushDocumentToNotion: mocks.pushDocumentToNotion,
+  resolveDocumentSyncConflict: mocks.resolveDocumentSyncConflict,
+}));
+
+vi.mock("./_notion-action-utils.js", () => ({
+  flushNotionDocumentEditor: mocks.flushNotionDocumentEditor,
+  getNotionDocumentOwner: mocks.getNotionDocumentOwner,
+  resolveDocumentId: (args: { documentId?: string; id?: string }) =>
+    args.documentId ?? args.id ?? "",
+}));
+
+import createAndLinkAction from "./create-and-link-notion-page";
+import linkAction from "./link-notion-page";
+import pullAction from "./pull-notion-page";
+import pushAction from "./push-notion-page";
+import resolveAction from "./resolve-notion-sync-conflict";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.getNotionDocumentOwner.mockResolvedValue("owner@example.com");
+  mocks.flushNotionDocumentEditor.mockResolvedValue(undefined);
+});
+
+describe("user-triggered Notion action flushes", () => {
+  it("flushes the live editor before pulling", async () => {
+    await pullAction.run({ documentId: "doc-1" });
+
+    expect(mocks.flushNotionDocumentEditor).toHaveBeenCalledWith(
+      "doc-1",
+      "owner@example.com",
+    );
+    expect(
+      mocks.flushNotionDocumentEditor.mock.invocationCallOrder[0],
+    ).toBeLessThan(mocks.pullDocumentFromNotion.mock.invocationCallOrder[0]);
+  });
+
+  it("flushes the live editor before resolving either conflict direction", async () => {
+    await resolveAction.run({ documentId: "doc-1", direction: "pull" });
+
+    expect(mocks.flushNotionDocumentEditor).toHaveBeenCalledWith(
+      "doc-1",
+      "owner@example.com",
+    );
+    expect(
+      mocks.flushNotionDocumentEditor.mock.invocationCallOrder[0],
+    ).toBeLessThan(
+      mocks.resolveDocumentSyncConflict.mock.invocationCallOrder[0],
+    );
+  });
+
+  it("flushes manual pushes but skips the redundant post-save auto-push flush", async () => {
+    await pushAction.run({
+      documentId: "doc-1",
+      flushOpenEditor: true,
+    });
+    expect(mocks.flushNotionDocumentEditor).toHaveBeenCalledTimes(1);
+
+    vi.clearAllMocks();
+    mocks.getNotionDocumentOwner.mockResolvedValue("owner@example.com");
+    await pushAction.run({
+      documentId: "doc-1",
+      flushOpenEditor: false,
+    });
+
+    expect(mocks.flushNotionDocumentEditor).not.toHaveBeenCalled();
+    expect(mocks.pushDocumentToNotion).toHaveBeenCalledWith(
+      "owner@example.com",
+      "doc-1",
+    );
+  });
+
+  it("flushes before linking to an existing Notion page", async () => {
+    await linkAction.run({
+      documentId: "doc-1",
+      pageId: "example-page-id",
+    });
+
+    expect(mocks.flushNotionDocumentEditor).toHaveBeenCalledWith(
+      "doc-1",
+      "owner@example.com",
+    );
+    expect(
+      mocks.flushNotionDocumentEditor.mock.invocationCallOrder[0],
+    ).toBeLessThan(mocks.linkDocumentToNotionPage.mock.invocationCallOrder[0]);
+  });
+
+  it("flushes before creating a linked Notion page", async () => {
+    await createAndLinkAction.run({ documentId: "doc-1" });
+
+    expect(mocks.flushNotionDocumentEditor).toHaveBeenCalledWith(
+      "doc-1",
+      "owner@example.com",
+    );
+    expect(
+      mocks.flushNotionDocumentEditor.mock.invocationCallOrder[0],
+    ).toBeLessThan(mocks.createAndLinkNotionPage.mock.invocationCallOrder[0]);
+  });
+});
diff --git a/templates/content/actions/pull-document.ts b/templates/content/actions/pull-document.ts
index 0208deb53a..4512526af8 100644
--- a/templates/content/actions/pull-document.ts
+++ b/templates/content/actions/pull-document.ts
@@ -29,12 +29,10 @@ import {
  *      never saw the key, so every external `pull-document` waited the full
  *      timeout and returned stale DB content.
  *   2. The editor polls that key, serializes its current Y.Doc to markdown
- *      through its existing serializer, calls `update-document`, then deletes
- *      the key.
- *   3. We poll (across both candidate sessions) for the key to disappear
- *      (flush acknowledged) and then read the now-fresh row. If the key never
- *      clears (no editor actually open), we fall back to the DB column, which
- *      is the best available snapshot.
+ *      through its existing serializer, calls `update-document`, then writes an
+ *      explicit success/error acknowledgement for that request id.
+ *   3. We poll every active collaborator session for the acknowledgement, fail
+ *      closed on editor errors/timeouts, and then read the now-fresh row.
  *
  * When there is no live collab session the DB column is authoritative and we
  * skip the handshake entirely. The helper bounds the wait so stale collab
@@ -90,7 +88,7 @@ export default defineAction({
 
     // If a live Yjs collab session is open, the in-memory editor doc is fresher
     // than the SQL column. Ask the open editor to serialize + save, then wait
-    // for it to acknowledge by clearing the flush-request key.
+    // for its explicit request-id-matched acknowledgement.
     await flushOpenDocumentEditorToSql({
       documentId: id,
       ownerEmail: (access.resource.ownerEmail as string | undefined) || null,
diff --git a/templates/content/actions/pull-notion-page.ts b/templates/content/actions/pull-notion-page.ts
index 4387f17a14..13e2626729 100644
--- a/templates/content/actions/pull-notion-page.ts
+++ b/templates/content/actions/pull-notion-page.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { pullDocumentFromNotion } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -17,6 +18,7 @@ export default defineAction({
   run: async (args) => {
     const documentId = resolveDocumentId(args);
     const owner = await getNotionDocumentOwner(documentId);
+    await flushNotionDocumentEditor(documentId, owner);
     return pullDocumentFromNotion(owner, documentId, true);
   },
 });
diff --git a/templates/content/actions/push-notion-page.ts b/templates/content/actions/push-notion-page.ts
index da200f3319..803ac63350 100644
--- a/templates/content/actions/push-notion-page.ts
+++ b/templates/content/actions/push-notion-page.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { pushDocumentToNotion } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -12,11 +13,20 @@ export default defineAction({
   schema: z.object({
     documentId: z.string().optional().describe("Document ID (required)"),
     id: z.string().optional().describe("Alias for --documentId"),
+    flushOpenEditor: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Flush an open collaborative editor before pushing (disable only when the caller just persisted the exact editor content)",
+      ),
   }),
   http: { method: "POST" },
   run: async (args) => {
     const documentId = resolveDocumentId(args);
     const owner = await getNotionDocumentOwner(documentId);
+    if (args.flushOpenEditor) {
+      await flushNotionDocumentEditor(documentId, owner);
+    }
     return pushDocumentToNotion(owner, documentId);
   },
 });
diff --git a/templates/content/actions/resolve-notion-sync-conflict.ts b/templates/content/actions/resolve-notion-sync-conflict.ts
index e19008323f..57bbd03be9 100644
--- a/templates/content/actions/resolve-notion-sync-conflict.ts
+++ b/templates/content/actions/resolve-notion-sync-conflict.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
 
 import { resolveDocumentSyncConflict } from "../server/lib/notion-sync.js";
 import {
+  flushNotionDocumentEditor,
   getNotionDocumentOwner,
   resolveDocumentId,
 } from "./_notion-action-utils.js";
@@ -18,6 +19,7 @@ export default defineAction({
   run: async (args) => {
     const documentId = resolveDocumentId(args);
     const owner = await getNotionDocumentOwner(documentId);
+    await flushNotionDocumentEditor(documentId, owner);
     return resolveDocumentSyncConflict(owner, documentId, args.direction);
   },
 });
diff --git a/templates/content/app/components/editor/DocumentEditor.layout.test.ts b/templates/content/app/components/editor/DocumentEditor.layout.test.ts
index 75f236d536..8e839eebe7 100644
--- a/templates/content/app/components/editor/DocumentEditor.layout.test.ts
+++ b/templates/content/app/components/editor/DocumentEditor.layout.test.ts
@@ -146,6 +146,12 @@ describe("document editor layout", () => {
     expect(documentEditorSource).toContain(
       "awareness={collabEnabled ? awareness : null}",
     );
+    expect(documentEditorSource).toContain(
+      'awareness.setLocalStateField("canFlushDocument", editorCanEdit)',
+    );
+    expect(documentEditorSource).toContain(
+      'awareness.setLocalStateField("canFlushDocument", false)',
+    );
 
     // Comments stay editor-only — viewers must not open the comment endpoints.
     expect(documentEditorSource).toContain(
@@ -179,6 +185,20 @@ describe("document editor layout", () => {
     );
   });
 
+  it("localizes the live-editor flush failure fallback", () => {
+    const source = readFileSync(
+      new URL("./DocumentEditor.tsx", import.meta.url),
+      {
+        encoding: "utf8",
+      },
+    );
+
+    expect(source).toContain('t("editor.liveDocumentSaveBeforeSyncFailed")');
+    expect(source).not.toContain(
+      'error instanceof Error\n                      ? error.message\n                      : "The live document could not be saved before syncing."',
+    );
+  });
+
   it("lets slash-created page references use the editor save pipeline", () => {
     const documentEditorSource = readFileSync(
       new URL("./DocumentEditor.tsx", import.meta.url),
diff --git a/templates/content/app/components/editor/DocumentEditor.tsx b/templates/content/app/components/editor/DocumentEditor.tsx
index c2384b8d48..b4f9d080c2 100644
--- a/templates/content/app/components/editor/DocumentEditor.tsx
+++ b/templates/content/app/components/editor/DocumentEditor.tsx
@@ -477,6 +477,18 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     canEdit && !bodyHydrationPending && (isLocalFileDocument || !collabLoading);
   canEditRef.current = editorCanEdit;
 
+  // Viewers intentionally join awareness so they receive live cursors, but
+  // only an editor runs the app-state flush poller below. Publish that exact
+  // capability so server-side pull/push/conflict actions do not wait on a
+  // read-only tab that can never acknowledge their request.
+  useEffect(() => {
+    if (!awareness || !collabEnabled) return;
+    awareness.setLocalStateField("canFlushDocument", editorCanEdit);
+    return () => {
+      awareness.setLocalStateField("canFlushDocument", false);
+    };
+  }, [awareness, collabEnabled, editorCanEdit]);
+
   // Initialize from fetched document, reset on document switch
   useEffect(() => {
     if (!document) return;
@@ -813,6 +825,10 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
           try {
             const next = await pushDocumentToNotion.mutateAsync({
               documentId,
+              // The exact editor value was persisted immediately above. Avoid
+              // a redundant live-editor flush handshake on every auto-sync
+              // save; manual pushes/conflict choices keep the safe default.
+              flushOpenEditor: false,
             });
             queryClient.setQueryData(
               documentSyncStatusQueryKey(documentId, { autoSync }),
@@ -1030,8 +1046,21 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       try {
         const res = await fetch(flushPath);
         if (res.ok) {
-          const pending = (await res.json()) as { id?: string } | null;
+          const pending = (await res.json()) as {
+            id?: string;
+            ts?: number;
+            requestId?: string;
+            status?: "pending" | "success" | "error";
+            error?: string;
+          } | null;
           if (pending && active) {
+            // A terminal acknowledgement waits for the requesting action to
+            // read and clear it. Retrying here could hide a failed flush or
+            // replace the explicit success signal before the server sees it.
+            if (pending.status === "error" || pending.status === "success") {
+              if (active) setTimeout(poll, 600);
+              return;
+            }
             const title = localTitleRef.current;
             const content = localContentRef.current;
             const updates: Record<string, string> = {};
@@ -1043,30 +1072,60 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             try {
               if (Object.keys(updates).length > 0) {
                 const saved = await persistDocumentUpdates(updates);
-                // A CAS conflict here means a newer write landed between this
-                // editor's last reconcile and the flush; leave watermarks
-                // alone so the external-change effects reconcile this editor
-                // to the winning server content instead of us claiming the
-                // now-discarded flush content as saved.
-                if (!isDocumentUpdateConflict(saved)) {
-                  const savedAt = saved?.updatedAt ?? new Date().toISOString();
-                  adoptConfirmedSaveWatermarks({
-                    saved,
-                    savedAt,
-                    title,
-                    content,
-                    updates,
-                    lastSavedTitleRef,
-                    lastSavedContentRef,
-                  });
+                if (isDocumentUpdateConflict(saved)) {
+                  // Do not acknowledge a CAS loss as a successful flush. The
+                  // requester must stop instead of pushing/replacing stale SQL.
+                  throw new Error(
+                    "The document changed while preparing it for sync.",
+                  );
                 }
+                const savedAt = saved?.updatedAt ?? new Date().toISOString();
+                adoptConfirmedSaveWatermarks({
+                  saved,
+                  savedAt,
+                  title,
+                  content,
+                  updates,
+                  lastSavedTitleRef,
+                  lastSavedContentRef,
+                });
               }
-            } finally {
-              // Acknowledge the flush even if nothing changed — the SQL row is
-              // already current, and pull-document is waiting on this delete.
+              // Explicitly acknowledge this exact request only after the live
+              // editor state is confirmed in SQL (or nothing needed saving).
+              // A delete is ambiguous with a transient app-state read failure.
               await fetch(flushPath, {
-                method: "DELETE",
-                headers: { "X-Agent-Native-CSRF": "1" },
+                method: "PUT",
+                headers: {
+                  "Content-Type": "application/json",
+                  "X-Agent-Native-CSRF": "1",
+                },
+                body: JSON.stringify({
+                  id: pending.id ?? documentId,
+                  ts: pending.ts ?? Date.now(),
+                  requestId: pending.requestId,
+                  status: "success",
+                }),
+              }).catch(() => {});
+            } catch (error) {
+              // Keep a durable negative acknowledgement so the requesting
+              // Notion action can fail closed instead of timing out and using a
+              // stale documents row. The server clears this after reading it.
+              await fetch(flushPath, {
+                method: "PUT",
+                headers: {
+                  "Content-Type": "application/json",
+                  "X-Agent-Native-CSRF": "1",
+                },
+                body: JSON.stringify({
+                  id: pending.id ?? documentId,
+                  ts: pending.ts ?? Date.now(),
+                  requestId: pending.requestId,
+                  status: "error",
+                  error:
+                    error instanceof Error
+                      ? error.message
+                      : t("editor.liveDocumentSaveBeforeSyncFailed"),
+                }),
               }).catch(() => {});
             }
           }
@@ -1082,7 +1141,13 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       active = false;
       clearTimeout(timer);
     };
-  }, [documentId, editorCanEdit, isLocalFileDocument, persistDocumentUpdates]);
+  }, [
+    documentId,
+    editorCanEdit,
+    isLocalFileDocument,
+    persistDocumentUpdates,
+    t,
+  ]);
 
   const handleTitleChange = useCallback(
     (newTitle: string) => {
diff --git a/templates/content/app/components/editor/VisualEditor.markdown.test.ts b/templates/content/app/components/editor/VisualEditor.markdown.test.ts
index c3e03a4c85..0a357e3015 100644
--- a/templates/content/app/components/editor/VisualEditor.markdown.test.ts
+++ b/templates/content/app/components/editor/VisualEditor.markdown.test.ts
@@ -6,25 +6,33 @@ import {
   parseNfmForEditor,
   serializeEditorToNfm,
 } from "@shared/notion-markdown";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { Editor, getSchema } from "@tiptap/core";
 import StarterKit from "@tiptap/starter-kit";
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { MemoryRouter } from "react-router";
 import { Markdown } from "tiptap-markdown";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { Awareness } from "y-protocols/awareness";
 import * as Y from "yjs";
 
+import { TooltipProvider } from "@/components/ui/tooltip";
+
 import { CodeBlock } from "./extensions/CodeBlockNode";
 import { NotionToggle } from "./extensions/NotionExtensions";
 import {
   createVisualEditorExtensions,
   EmptyLineParagraph,
   getRecentEditPresenceMarkerRect,
+  parseNfmForCollabReconcile,
   uploadAndInsertAudioFiles,
   uploadAndInsertImageFiles,
   uploadAndInsertVideoFiles,
   shouldApplyExternalContentSync,
   shouldPersistLocalFileEditorUpdate,
   shouldSeedCollaborativeContent,
+  VisualEditor,
 } from "./VisualEditor";
 
 function createMarkdownEditor(content: string) {
@@ -653,6 +661,189 @@ describe("VisualEditor markdown round-tripping", () => {
     ).toBe(false);
   });
 
+  it("keeps adjacent NFM blocks separate in collaborative external reconciles", () => {
+    const editor = createFullEditor();
+    const incoming = [
+      "→ → slack questions",
+      '\tmuch simpler "what"',
+      "\twhat is it and how different from other app builders",
+      "\twhen to engage prospects",
+    ].join("\n");
+
+    try {
+      const parsed = parseNfmForCollabReconcile(editor, incoming);
+
+      expect(parsed).not.toBeNull();
+      expect(parsed?.childCount).toBe(4);
+      expect(
+        Array.from(
+          { length: parsed?.childCount ?? 0 },
+          (_, index) => parsed?.child(index).textContent,
+        ),
+      ).toEqual([
+        "→ → slack questions",
+        'much simpler "what"',
+        "what is it and how different from other app builders",
+        "when to engage prospects",
+      ]);
+    } finally {
+      editor.destroy();
+    }
+  });
+
+  it("uses the NFM parser when a newer SQL snapshot reconciles into a live Y.Doc", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    let root = createRoot(container);
+    const ydoc = new Y.Doc();
+    const incoming = [
+      "→ → slack questions",
+      '\tmuch simpler "what"',
+      "\twhat is it and how different from other app builders",
+      "\twhen to engage prospects",
+    ].join("\n");
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    const emitted: string[] = [];
+    const actEnvironment = globalThis as typeof globalThis & {
+      IS_REACT_ACT_ENVIRONMENT?: boolean;
+    };
+    const previousActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = true;
+    const renderEditor = (content: string, contentUpdatedAt: string) =>
+      createElement(
+        MemoryRouter,
+        null,
+        createElement(TooltipProvider, {
+          delayDuration: 0,
+          children: createElement(
+            QueryClientProvider,
+            { client: queryClient },
+            createElement(VisualEditor, {
+              content,
+              contentUpdatedAt,
+              onChange: (markdown) => emitted.push(markdown),
+              ydoc,
+              collabSynced: true,
+              editable: true,
+            }),
+          ),
+        }),
+      );
+
+    try {
+      // Match a real reload after an external version was previously live: seed
+      // the persisted Y.Doc through the actual VisualEditor, unmount the page,
+      // then mount a fresh editor whose SQL snapshot points somewhere else.
+      act(() => {
+        root.render(renderEditor(incoming, "2026-07-09T19:59:59.000Z"));
+      });
+      await act(() => new Promise((resolve) => setTimeout(resolve, 50)));
+      act(() => root.unmount());
+      root = createRoot(container);
+
+      act(() => {
+        root.render(
+          renderEditor("Initial local block", "2026-07-09T20:00:00.000Z"),
+        );
+      });
+      await act(() => new Promise((resolve) => setTimeout(resolve, 50)));
+      expect(
+        Array.from(
+          container.querySelectorAll<HTMLElement>(".notion-editor > p"),
+          (node) => node.textContent,
+        ),
+      ).toEqual(["Initial local block"]);
+
+      act(() => {
+        root.render(renderEditor(incoming, "2026-07-09T20:00:01.000Z"));
+      });
+      await act(() => new Promise((resolve) => setTimeout(resolve, 50)));
+
+      expect(
+        Array.from(
+          container.querySelectorAll<HTMLElement>(".notion-editor > p"),
+          (node) => node.textContent,
+        ),
+      ).toEqual([
+        "→ → slack questions",
+        'much simpler "what"',
+        "what is it and how different from other app builders",
+        "when to engage prospects",
+      ]);
+      expect(emitted).not.toContain("<empty-block/>");
+    } finally {
+      await act(async () => root.unmount());
+      queryClient.clear();
+      ydoc.destroy();
+      container.remove();
+      actEnvironment.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+    }
+  });
+
+  it("does not clear awareness owned by the shared collab connection on unmount", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    const ydoc = new Y.Doc();
+    const awareness = new Awareness(ydoc);
+    const queryClient = new QueryClient();
+    const actEnvironment = globalThis as typeof globalThis & {
+      IS_REACT_ACT_ENVIRONMENT?: boolean;
+    };
+    const previousActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = true;
+    const user = {
+      name: "Awareness Owner",
+      email: "awareness-owner@example.com",
+      color: "#60a5fa",
+    };
+
+    try {
+      act(() => {
+        root.render(
+          createElement(
+            MemoryRouter,
+            null,
+            createElement(TooltipProvider, {
+              children: createElement(
+                QueryClientProvider,
+                { client: queryClient },
+                createElement(VisualEditor, {
+                  content: "Shared awareness body",
+                  contentUpdatedAt: "2026-07-09T20:00:00.000Z",
+                  onChange: () => {},
+                  ydoc,
+                  collabSynced: true,
+                  awareness,
+                  user,
+                  editable: true,
+                }),
+              ),
+            }),
+          ),
+        );
+      });
+      await act(() => new Promise((resolve) => setTimeout(resolve, 50)));
+      expect(awareness.getLocalState()?.user).toMatchObject({
+        email: user.email,
+      });
+
+      act(() => root.unmount());
+
+      expect(awareness.getLocalState()?.user).toMatchObject({
+        email: user.email,
+      });
+    } finally {
+      queryClient.clear();
+      awareness.destroy();
+      ydoc.destroy();
+      container.remove();
+      actEnvironment.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+    }
+  });
+
   it("does not apply stale SQL snapshots over live collaborative edits", () => {
     expect(
       shouldApplyExternalContentSync({
diff --git a/templates/content/app/components/editor/VisualEditor.tsx b/templates/content/app/components/editor/VisualEditor.tsx
index 21e0f39ee1..7d949a0f47 100644
--- a/templates/content/app/components/editor/VisualEditor.tsx
+++ b/templates/content/app/components/editor/VisualEditor.tsx
@@ -822,6 +822,28 @@ export function shouldSeedCollaborativeContent({
   return !!content.trim() && (fragmentLength === 0 || !semanticMarkdown);
 }
 
+/**
+ * Parse authoritative Content NFM with Content's exact NFM parser before the
+ * shared reconcile computes its top-level surgical diff.
+ *
+ * Falling back to the shared CommonMark parser is lossy here: canonical NFM
+ * stores one Notion block per line without blank paragraph separators, while
+ * CommonMark merges those consecutive lines into one paragraph. That made
+ * external replacements such as Notion conflict resolution and version
+ * restores look correct in the non-collaborative history preview, then collapse
+ * into one wrapped paragraph when reconciled into the live Y.Doc.
+ */
+export function parseNfmForCollabReconcile(
+  editor: CoreEditor,
+  value: string,
+): ProseMirrorNode | null {
+  try {
+    return editor.schema.nodeFromJSON(nfmToDoc(value) as any);
+  } catch {
+    return null;
+  }
+}
+
 export function shouldApplyExternalContentSync({
   docChanged,
   content,
@@ -1669,10 +1691,14 @@ export function VisualEditor({
   // Clean up awareness on unmount
   useEffect(() => {
     return () => {
-      localAwareness?.setLocalState(null);
+      // Only the fallback instance is owned by this editor. A provided
+      // awareness belongs to the shared useCollaborativeDoc connection; clearing
+      // it here races StrictMode/remounts and can erase the tab's durable
+      // presence while the shared connection is still active.
+      fallbackAwareness?.setLocalState(null);
       fallbackAwareness?.destroy();
     };
-  }, [fallbackAwareness, localAwareness]);
+  }, [fallbackAwareness]);
 
   const extensions = useMemo(
     () =>
@@ -1941,6 +1967,10 @@ export function VisualEditor({
       e.commands.setContent(doc);
     },
     normalizeValue: canonicalizeNfm,
+    // The shared fallback parser is CommonMark. Content stores canonical NFM,
+    // whose adjacent lines are separate Notion blocks, so always provide the
+    // exact NFM parser for the surgical reconcile path.
+    parseValue: parseNfmForCollabReconcile,
     shouldSeed: ({ value, currentMarkdown, fragmentLength }) =>
       editable &&
       shouldSeedCollaborativeContent({
diff --git a/templates/content/app/hooks/use-notion.ts b/templates/content/app/hooks/use-notion.ts
index 285f81b39e..cf7e1013f4 100644
--- a/templates/content/app/hooks/use-notion.ts
+++ b/templates/content/app/hooks/use-notion.ts
@@ -253,12 +253,12 @@ export function usePullDocumentFromNotion(documentId: string) {
 
 export function usePushDocumentToNotion(documentId: string) {
   const queryClient = useQueryClient();
-  return useActionMutation<DocumentSyncStatus, { documentId: string }>(
-    "push-notion-page",
-    {
-      onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
-    },
-  );
+  return useActionMutation<
+    DocumentSyncStatus,
+    { documentId: string; flushOpenEditor?: boolean }
+  >("push-notion-page", {
+    onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
+  });
 }
 
 export function useResolveDocumentSyncConflict(documentId: string) {
diff --git a/templates/content/app/i18n-data.ts b/templates/content/app/i18n-data.ts
index aa46d0a075..a056d6ae2b 100644
--- a/templates/content/app/i18n-data.ts
+++ b/templates/content/app/i18n-data.ts
@@ -2463,6 +2463,8 @@ const enUS = {
     couldNotSaveLocalFile: "Could not save local file",
     collabConnectingReadOnly:
       "Connecting live editor. Showing a read-only snapshot.",
+    liveDocumentSaveBeforeSyncFailed:
+      "The live document could not be saved before syncing.",
     documentTitle: "Document title",
     builderBodySyncing: "Content is still syncing from Builder",
     builderBodySyncingDescription:
@@ -4843,6 +4845,7 @@ const editorMessagesByLocale = {
   "zh-CN": {
     noDocumentSelected: "未选择文档",
     collabConnectingReadOnly: "正在连接实时编辑器。显示只读快照。",
+    liveDocumentSaveBeforeSyncFailed: "实时文档无法在同步前保存。",
     builderBodySyncing: "内容仍在从 Builder 同步",
     builderBodySyncingDescription:
       "同步 Builder 正文完成前会暂停编辑，避免覆盖现有文章内容。",
@@ -5169,6 +5172,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Ningún documento seleccionado",
     collabConnectingReadOnly:
       "Conectando el editor en vivo. Mostrando una instantánea de solo lectura.",
+    liveDocumentSaveBeforeSyncFailed:
+      "No se pudo guardar el documento activo antes de sincronizarlo.",
     builderBodySyncing: "El contenido aún se está sincronizando desde Builder",
     builderBodySyncingDescription:
       "La edición está en pausa hasta que el cuerpo de Builder termine de sincronizarse, para no sobrescribir el contenido existente del artículo.",
@@ -5506,6 +5511,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Aucun document sélectionné",
     collabConnectingReadOnly:
       "Connexion de l'éditeur en direct. Affichage d'un instantané en lecture seule.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Le document actif n’a pas pu être enregistré avant la synchronisation.",
     builderBodySyncing:
       "Le contenu est encore en cours de synchronisation depuis Builder",
     builderBodySyncingDescription:
@@ -5846,6 +5853,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Kein Dokument ausgewählt",
     collabConnectingReadOnly:
       "Live-Editor wird verbunden. Schreibgeschützte Momentaufnahme wird angezeigt.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Das aktive Dokument konnte vor der Synchronisierung nicht gespeichert werden.",
     builderBodySyncing: "Inhalte werden noch von Builder synchronisiert",
     builderBodySyncingDescription:
       "Die Bearbeitung ist pausiert, bis der Builder-Textkörper fertig synchronisiert ist, damit der bestehende Artikelinhalt nicht überschrieben wird.",
@@ -6190,6 +6199,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "ドキュメントが選択されていません",
     collabConnectingReadOnly:
       "ライブエディターに接続中。読み取り専用のスナップショットを表示しています。",
+    liveDocumentSaveBeforeSyncFailed:
+      "同期前にライブドキュメントを保存できませんでした。",
     builderBodySyncing: "コンテンツはまだ Builder から同期中です",
     builderBodySyncingDescription:
       "既存の記事内容を上書きしないよう、Builder 本文の同期が完了するまで編集は一時停止されます。",
@@ -6524,6 +6535,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "선택한 문서가 없습니다.",
     collabConnectingReadOnly:
       "라이브 편집기에 연결하는 중입니다. 읽기 전용 스냅샷을 표시합니다.",
+    liveDocumentSaveBeforeSyncFailed:
+      "동기화하기 전에 실시간 문서를 저장하지 못했습니다.",
     builderBodySyncing: "콘텐츠가 아직 Builder에서 동기화되는 중입니다",
     builderBodySyncingDescription:
       "기존 문서 내용을 덮어쓰지 않도록 Builder 본문 동기화가 완료될 때까지 편집이 일시 중지됩니다.",
@@ -6857,6 +6870,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "Nenhum documento selecionado",
     collabConnectingReadOnly:
       "Conectando o editor ao vivo. Exibindo um instantâneo somente leitura.",
+    liveDocumentSaveBeforeSyncFailed:
+      "Não foi possível salvar o documento ativo antes da sincronização.",
     builderBodySyncing: "O conteúdo ainda está sincronizando do Builder",
     builderBodySyncingDescription:
       "A edição fica pausada até o corpo do Builder terminar de sincronizar, para não sobrescrever o conteúdo existente do artigo.",
@@ -7196,6 +7211,8 @@ const editorMessagesByLocale = {
     noDocumentSelected: "कोई दस्तावेज़ चयनित नहीं",
     collabConnectingReadOnly:
       "लाइव संपादक कनेक्ट हो रहा है। केवल-पठन स्नैपशॉट दिखाया जा रहा है।",
+    liveDocumentSaveBeforeSyncFailed:
+      "सिंक करने से पहले लाइव दस्तावेज़ सहेजा नहीं जा सका।",
     builderBodySyncing: "सामग्री अभी भी Builder से सिंक हो रही है",
     builderBodySyncingDescription:
       "Builder का मुख्य भाग सिंक पूरा होने तक संपादन रोका गया है, ताकि मौजूदा लेख सामग्री अधिलेखित न हो।",
@@ -7525,6 +7542,7 @@ const editorMessagesByLocale = {
     noDocumentSelected: "لم يتم تحديد أي مستند",
     collabConnectingReadOnly:
       "جارٍ الاتصال بالمحرر المباشر. يتم عرض لقطة للقراءة فقط.",
+    liveDocumentSaveBeforeSyncFailed: "تعذّر حفظ المستند المباشر قبل المزامنة.",
     builderBodySyncing: "لا يزال المحتوى قيد المزامنة من Builder",
     builderBodySyncingDescription:
       "يتم إيقاف التحرير مؤقتًا حتى تكتمل مزامنة نص Builder، حتى لا يتم استبدال محتوى المقالة الحالي.",
diff --git a/templates/content/app/i18n/zh-TW.ts b/templates/content/app/i18n/zh-TW.ts
index ffe7109512..bb1f732ccb 100644
--- a/templates/content/app/i18n/zh-TW.ts
+++ b/templates/content/app/i18n/zh-TW.ts
@@ -94,6 +94,7 @@ const messages = {
     couldNotReadLocalSourceFile: "無法讀取本機來源檔案",
     couldNotSaveLocalFile: "無法儲存本機檔案",
     collabConnectingReadOnly: "正在連接即時編輯器。顯示唯讀快照。",
+    liveDocumentSaveBeforeSyncFailed: "即時文件無法在同步前儲存。",
     documentTitle: "檔案標題",
     builderBodySyncing: "內容仍在從 Builder 同步",
     builderBodySyncingDescription:
diff --git a/templates/content/changelog/2026-07-09-notion-conflict-choices-and-version-restores-preserve-docume.md b/templates/content/changelog/2026-07-09-notion-conflict-choices-and-version-restores-preserve-docume.md
new file mode 100644
index 0000000000..fd687dd733
--- /dev/null
+++ b/templates/content/changelog/2026-07-09-notion-conflict-choices-and-version-restores-preserve-docume.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Notion conflict choices and version restores preserve document paragraphs and protect live edits.
diff --git a/templates/content/server/lib/notion-sync.spec.ts b/templates/content/server/lib/notion-sync.spec.ts
index 8e14f9539b..c5ce24cb4e 100644
--- a/templates/content/server/lib/notion-sync.spec.ts
+++ b/templates/content/server/lib/notion-sync.spec.ts
@@ -22,6 +22,7 @@ const testState = vi.hoisted(() => ({
   },
   link: null as any,
   comments: [] as Array<Record<string, unknown>>,
+  versions: [] as Array<Record<string, unknown>>,
 }));
 
 const notionMocks = vi.hoisted(() => {
@@ -106,6 +107,14 @@ vi.mock("../db/index.js", () => {
       ownerEmail: "documentSyncLinks.ownerEmail",
       syncClaimedAt: "documentSyncLinks.syncClaimedAt",
     },
+    documentVersions: {
+      id: "documentVersions.id",
+      documentId: "documentVersions.documentId",
+      ownerEmail: "documentVersions.ownerEmail",
+      title: "documentVersions.title",
+      content: "documentVersions.content",
+      createdAt: "documentVersions.createdAt",
+    },
     documentComments: {
       documentId: "documentComments.documentId",
       ownerEmail: "documentComments.ownerEmail",
@@ -143,7 +152,7 @@ vi.mock("../db/index.js", () => {
     return true;
   }
 
-  const db = {
+  const db: any = {
     select: () => ({
       from: (table: unknown) => ({
         where: async () => {
@@ -157,17 +166,23 @@ vi.mock("../db/index.js", () => {
       }),
     }),
     insert: (table: unknown) => ({
-      values: (row: Record<string, unknown>) => ({
-        onConflictDoUpdate: async ({
-          set,
-        }: {
-          set: Record<string, unknown>;
-        }) => {
-          if (table === schema.documentSyncLinks) {
-            testState.link = { ...row, ...set };
-          }
-        },
-      }),
+      values: (row: Record<string, unknown>) => {
+        if (table === schema.documentVersions) {
+          testState.versions.push(row);
+          return Promise.resolve();
+        }
+        return {
+          onConflictDoUpdate: async ({
+            set,
+          }: {
+            set: Record<string, unknown>;
+          }) => {
+            if (table === schema.documentSyncLinks) {
+              testState.link = { ...row, ...set };
+            }
+          },
+        };
+      },
     }),
     update: (table: unknown) => ({
       set: (updates: Record<string, unknown>) => ({
@@ -213,6 +228,7 @@ vi.mock("../db/index.js", () => {
         }
       },
     }),
+    transaction: async (run: (tx: unknown) => Promise<unknown>) => run(db),
   };
 
   return { getDb: () => db, schema };
@@ -403,6 +419,7 @@ describe("getDocumentSyncStatus", () => {
       hasConflict: false,
       warningsJson: "[]",
     };
+    testState.versions = [];
     notionMocks.getNotionConnectionForOwner.mockResolvedValue({
       accessToken: "notion-token",
     });
@@ -458,6 +475,7 @@ describe("pullDocumentFromNotion", () => {
       hasConflict: false,
       warningsJson: "[]",
     };
+    testState.versions = [];
 
     notionMocks.getNotionConnectionForOwner.mockResolvedValue({
       accessToken: "notion-token",
@@ -528,6 +546,13 @@ describe("pullDocumentFromNotion", () => {
     expect(testState.link?.lastSyncedContentHash).toBe(
       hashContentForTest("Remote edit from Notion"),
     );
+    expect(testState.versions).toContainEqual(
+      expect.objectContaining({
+        documentId: "doc-1",
+        title: "Local title",
+        content: "Local body",
+      }),
+    );
     expect(status.hasConflict).toBe(false);
   });
 });
@@ -560,6 +585,7 @@ describe("refreshDocumentSyncStatus", () => {
       hasConflict: false,
       warningsJson: "[]",
     };
+    testState.versions = [];
 
     notionMocks.getNotionConnectionForOwner.mockResolvedValue({
       accessToken: "notion-token",
@@ -921,6 +947,7 @@ describe("pushDocumentToNotion", () => {
       hasConflict: false,
       warningsJson: "[]",
     };
+    testState.versions = [];
 
     notionMocks.getNotionConnectionForOwner.mockResolvedValue({
       accessToken: "notion-token",
@@ -1023,6 +1050,9 @@ describe("pushDocumentToNotion", () => {
 
     // The concurrent save must survive; normalized old content must not land.
     expect(testState.document.content).toBe("Newer local save mid-push");
+    // A lost replacement CAS must not create a history entry for a
+    // replacement that never happened.
+    expect(testState.versions).toHaveLength(0);
   });
 
   it("leaves localChanged false when Notion's post-push readback normalizes the content (n-C)", async () => {
@@ -1064,6 +1094,13 @@ describe("pushDocumentToNotion", () => {
     expect(testState.document.content).toBe(
       "Local edit typed just now (normalized)",
     );
+    expect(testState.versions).toContainEqual(
+      expect.objectContaining({
+        documentId: "doc-1",
+        title: "Local title",
+        content: "Local edit typed just now",
+      }),
+    );
     expect(testState.link?.lastSyncedContentHash).toBe(
       hashContentForTest("Local edit typed just now (normalized)"),
     );
diff --git a/templates/content/server/lib/notion-sync.ts b/templates/content/server/lib/notion-sync.ts
index ccb189cb4a..13c5d88292 100644
--- a/templates/content/server/lib/notion-sync.ts
+++ b/templates/content/server/lib/notion-sync.ts
@@ -2,7 +2,6 @@
 // in pnpm's node_modules. Logic is correct; types just don't unify across instances.
 import crypto from "node:crypto";
 
-import { deleteCollabState, releaseDoc } from "@agent-native/core/collab";
 import { and, eq, inArray, isNull, lt, or } from "drizzle-orm";
 import type { InferSelectModel } from "drizzle-orm";
 
@@ -37,6 +36,56 @@ function nanoid(size = 12): string {
   return Array.from(bytes, (byte) => chars[byte % chars.length]).join("");
 }
 
+async function replaceDocumentFromExternal(args: {
+  document: DocumentRow;
+  expectedUpdatedAt: string;
+  title: string;
+  content: string;
+  icon: string | null;
+  updatedAt: string;
+}): Promise<boolean> {
+  const db = getDb();
+  return db.transaction(async (tx) => {
+    const applied = await tx
+      .update(schema.documents)
+      .set({
+        title: args.title,
+        content: args.content,
+        icon: args.icon,
+        updatedAt: args.updatedAt,
+      })
+      .where(
+        and(
+          eq(schema.documents.id, args.document.id),
+          eq(schema.documents.ownerEmail, args.document.ownerEmail),
+          eq(schema.documents.updatedAt, args.expectedUpdatedAt),
+        ),
+      )
+      .returning({ id: schema.documents.id });
+
+    if (!applied || applied.length === 0) return false;
+
+    if (
+      args.title !== args.document.title ||
+      args.content !== args.document.content
+    ) {
+      // Keep the recovery snapshot in the same transaction as the replacement:
+      // a lost CAS creates no phantom version, and a snapshot failure rolls the
+      // destructive replacement back instead of leaving it unrecoverable.
+      await tx.insert(schema.documentVersions).values({
+        id: nanoid(),
+        ownerEmail: args.document.ownerEmail,
+        documentId: args.document.id,
+        title: args.document.title,
+        content: args.document.content,
+        createdAt: nowIso(),
+      });
+    }
+
+    return true;
+  });
+}
+
 /**
  * Hash of the canonical content. Two documents with the same hash are
  * byte-identical once canonicalized, so this is the authoritative "did the
@@ -827,8 +876,6 @@ async function pullDocumentFromNotionInner(
     remotePageDocumentIdByPageId?: RemotePageDocumentLookup;
   },
 ): Promise<DocumentSyncStatus> {
-  const db = getDb();
-  const document = await getDocument(documentId, owner);
   const link = await getSyncLink(documentId, owner);
   if (!link) throw new Error("Document is not linked to a Notion page.");
   const connection = await getNotionConnectionForOwner(owner);
@@ -935,28 +982,18 @@ async function pullDocumentFromNotionInner(
   // check will mistake the unchanged document for a fresh local edit.
   const updatedAt = contentChanged ? nowIso() : freshDocument.updatedAt;
   if (contentChanged) {
-    // Compare-and-swap: only apply the pulled content if the row is still at
-    // the snapshot we just re-read. If a concurrent save landed in between,
-    // 0 rows match and we fall through to the conflict path instead of
-    // clobbering the newer local write.
-    const applied = await db
-      .update(schema.documents)
-      .set({
-        title: newTitle,
-        content: newContent,
-        icon: newIcon,
-        updatedAt,
-      })
-      .where(
-        and(
-          eq(schema.documents.id, documentId),
-          eq(schema.documents.ownerEmail, owner),
-          eq(schema.documents.updatedAt, freshDocument.updatedAt),
-        ),
-      )
-      .returning({ id: schema.documents.id });
+    // Snapshot + compare-and-swap are one transaction: only the winning
+    // replacement gets a recovery version, and snapshot failure rolls it back.
+    const applied = await replaceDocumentFromExternal({
+      document: freshDocument,
+      expectedUpdatedAt: freshDocument.updatedAt,
+      title: newTitle,
+      content: newContent,
+      icon: newIcon,
+      updatedAt,
+    });
 
-    if (!applied || applied.length === 0) {
+    if (!applied) {
       // A newer local save raced in after our re-read. Do not adopt the
       // pulled content or advance the hash baseline — surface a conflict so
       // the user resolves it explicitly instead of silently losing the edit.
@@ -986,16 +1023,10 @@ async function pullDocumentFromNotionInner(
       });
     }
 
-    // Reset the Yjs collaborative state so it no longer holds the pre-sync
-    // content. Connected clients re-seed their Y.XmlFragment from the new
-    // `documents.content` value via VisualEditor's content-sync effect, and
-    // a fresh page load starts from an empty server state and seeds from SQL.
-    try {
-      await deleteCollabState(documentId);
-      releaseDoc(documentId);
-    } catch {
-      // Non-fatal — the client-side sync will still reconcile via setContent.
-    }
+    // Keep the Y.Doc intact. The live editor's updatedAt-gated reconcile applies
+    // this authoritative SQL snapshot as a minimal Yjs transaction. Deleting
+    // collab state here races connected clients (which can re-persist the stale
+    // pre-pull state) and briefly makes later flush handshakes miss the editor.
   }
 
   await upsertSyncLink({
@@ -1193,7 +1224,6 @@ async function pushDocumentToNotionInner(
   // the rare case Notion normalizes a construct differently, immediately
   // converging instead of ping-ponging. Re-read the row first so a local save
   // that landed during the multi-round-trip push isn't clobbered below.
-  const db = getDb();
   const freshDocument = await getDocument(documentId, owner);
   const newContent = remote.content ?? document.content;
   const newTitle = remote.title || document.title;
@@ -1211,39 +1241,25 @@ async function pushDocumentToNotionInner(
   // exactly what we pushed, since contentChanged is false).
   let baselineContent = document.content;
   if (contentChanged) {
-    // Compare-and-swap against the pre-push snapshot: if a concurrent save
-    // changed the row since `document` was read, skip adopting Notion's
-    // normalized content so the newer local edit is never overwritten. The
-    // hash baseline is still advanced to the *pushed* content below so the
-    // concurrent edit continues to show as localChanged and gets re-pushed on
-    // the next sync cycle.
-    const applied = await db
-      .update(schema.documents)
-      .set({
-        title: newTitle,
-        content: newContent,
-        icon: newIcon,
-        updatedAt: pushedAt,
-      })
-      .where(
-        and(
-          eq(schema.documents.id, documentId),
-          eq(schema.documents.ownerEmail, owner),
-          eq(schema.documents.updatedAt, document.updatedAt),
-        ),
-      )
-      .returning({ id: schema.documents.id });
+    // Snapshot + compare-and-swap are atomic. If a concurrent save changed the
+    // row since `document` was read, skip both the provider readback adoption
+    // and its recovery version; the newer local edit remains localChanged.
+    const applied = await replaceDocumentFromExternal({
+      document: freshDocument,
+      expectedUpdatedAt: document.updatedAt,
+      title: newTitle,
+      content: newContent,
+      icon: newIcon,
+      updatedAt: pushedAt,
+    });
 
-    if (applied && applied.length > 0) {
+    if (applied) {
       // The CAS landed — the row now holds Notion's normalized readback, so
       // the baseline must match that, not the pre-push content we sent.
       baselineContent = newContent;
-      try {
-        await deleteCollabState(documentId);
-        releaseDoc(documentId);
-      } catch {
-        // Non-fatal — the client reconciles via setContent.
-      }
+      // Preserve the live Y.Doc and let the updatedAt-gated editor reconcile
+      // apply this provider-normalized snapshot. Clearing collab persistence
+      // here can race a connected client's stale update and resurrect it.
     }
     // else: CAS raced and lost — the row holds the concurrent edit's content,
     // not `newContent` and not `document.content`. Keep baselineContent as
diff --git a/templates/design/.agents/skills/design-generation/SKILL.md b/templates/design/.agents/skills/design-generation/SKILL.md
index 83040ddae8..2e708c0fd7 100644
--- a/templates/design/.agents/skills/design-generation/SKILL.md
+++ b/templates/design/.agents/skills/design-generation/SKILL.md
@@ -173,7 +173,7 @@ defaults. The banned-defaults list above still applies, plus:
 
 ## Generation Workflow — the canonical 5-phase flow
 
-This flow mirrors Claude Design's UX: ask → show variants → user picks → refine. Don't skip phases for new designs.
+This flow mirrors Claude Design's UX: clarify only what's unclear → show variants → user picks → refine. Don't collapse phases into one shot for new, open-ended designs.
 
 ### Phase 1 — Create the project + ask before generating
 
@@ -187,7 +187,28 @@ application state. External MCP hosts should surface the `create-design`
 returned "Open design" link, then use `present-design-variants` to open the
 visual picker.
 
-Then, for any non-trivial first prompt, call `show-design-questions` BEFORE generating. The editor renders a full-canvas overlay; answers come back as a chat message. Skip the questions only when the prompt is unambiguous ("re-skin this with my brand colors") or the user said "decide for me".
+Then, for a brief or ambiguous first prompt to a **new** design, call
+`show-design-questions` BEFORE generating. The editor renders a full-canvas
+overlay; answers come back as a chat message. Size the question count to how
+much is actually unresolved — most prompts warrant 2-4 questions, not the full
+1-8 range — and never ask about something the prompt already specified (a
+stated color, audience, or layout is settled; don't re-ask it as a choice).
+
+Skip the questions entirely when:
+- the prompt is already specific enough to generate from (names the audience,
+  purpose, and a visual direction, e.g. "a dark, data-dense analytics
+  dashboard for ops engineers" or "re-skin this with my brand colors");
+- it's a tweak/edit/refinement to an existing design rather than a new one —
+  go straight to `edit-design` (see Phase 3 and "Making edits" below);
+- the user already answered a question set for this design and is now
+  iterating — don't re-ask settled ground on follow-up prompts for the same
+  design; or
+- the user says "decide for me," "surprise me," "just build it," or similar.
+
+Asking on every prompt is as much a failure mode as never asking: a detailed
+prompt that already answers the obvious questions should generate
+immediately, and a design already in flight should not be interrupted with a
+second questionnaire.
 
 ```bash
 pnpm action show-design-questions \
@@ -196,6 +217,12 @@ pnpm action show-design-questions \
   --questions '[{"id":"form_factor","type":"text-options","question":"What form factor?","options":[{"label":"Desktop web app","value":"desktop"},{"label":"Mobile app","value":"mobile"},{"label":"Both / responsive","value":"responsive"},{"label":"Decide for me","value":"decide"}],"allowOther":true}]'
 ```
 
+Favor choice-first questions (2-5 concrete options, `allowOther: true`, and a
+"Decide for me" option when any answer is acceptable) over open-ended
+`freeform` text, and avoid `multiSelect` unless the question genuinely allows
+combining multiple answers — stacking multi-select questions multiplies
+follow-up ambiguity instead of resolving it.
+
 **Carry the form-factor answer through to generation — do not just ask and discard it.** A "Desktop web app" answer means the generated screen's canvas frame must be desktop-sized (~1440×1024), not left at whatever a screen with no placement falls back to. Map the answer to real frame geometry: pass `deviceType` (`"mobile"` / `"tablet"` / `"desktop"`) per screen to `generate-screens`, explicit `width`/`height` per variant to `present-design-variants`, or an explicit `canvasFrames` entry to `generate-design` — see Phase 2 and Phase 3 below. For "Both / responsive," generate at desktop width and rely on the responsive breakpoint system (see `responsive-breakpoints` skill) rather than guessing a size.
 
 ### Phase 2 — Generate side-by-side variations (2-5, three by default)
diff --git a/templates/design/.agents/skills/design-systems/SKILL.md b/templates/design/.agents/skills/design-systems/SKILL.md
index 0ff6832667..fb2a9e3636 100644
--- a/templates/design/.agents/skills/design-systems/SKILL.md
+++ b/templates/design/.agents/skills/design-systems/SKILL.md
@@ -248,6 +248,92 @@ design-system indexing just to insert a component. Use
 component/component set with provenance. Styles and variables still belong in
 the Builder-backed design-system path above.
 
+### Import from Figma (pixel-accurate frame import)
+
+**When the user pastes a Figma frame/screen link and wants a real, editable
+Design screen** (not a rendered image, not a component insert), use
+`import-figma-frame` instead of `list-figma-library-assets` +
+`insert-figma-library-asset`:
+
+```bash
+pnpm action import-figma-frame --figmaUrl "https://www.figma.com/design/<fileKey>/<name>?node-id=<id>"
+# or
+pnpm action import-figma-frame --fileKey "<fileKey>" --nodeId "12:34" --designId "<designId>"
+```
+
+- Accepts a full Figma URL (design/file/proto share links, including
+  `/branch/<key>/` branch URLs — the branch's own key is used automatically) or
+  an explicit `fileKey` + `nodeId`. If `nodeId` is omitted, the file's first
+  top-level frame is imported.
+- Maps the node tree to real HTML/CSS: exact position/size, auto-layout as
+  flexbox, text (font, line-height, letter-spacing, case, decoration, align),
+  fills (solid/gradient/image, correctly layered and gradient-angle-derived,
+  not a default angle), strokes (including the CENTER/INSIDE/OUTSIDE
+  distinction), per-corner radii, shadows/blur, opacity, and blend modes.
+  Vector networks, boolean operations, and other structurally unsupported node
+  types are rendered as an exact PNG at 2x scale instead of an approximated
+  shape guess.
+- Saves the result as a new screen via the same import path as other Design
+  imports (`saveImportedDesignFiles`), placed on the overview canvas.
+- Returns a `fidelityReport` — `exactCount`, `approximated` (properties CSS
+  can only approximate: rotation, per-side stroke weights, radial/angular/
+  diamond gradients, blur radius scale), and `imageFallbacks` (subtrees
+  rendered as PNG instead of structural HTML). Read this back to the user when
+  a design has non-trivial fallbacks so they know what to expect if they later
+  edit that subtree.
+- After import, treat the screen like any other: `view-screen`,
+  `get-design-snapshot`, `apply-visual-edit` / `edit-design` all work normally
+  on it.
+- For a file's published FILL/TEXT/EFFECT/GRID styles (name, description, node
+  id — not full token values), use `get-figma-styles` with `fileUrl`/`fileKey`.
+  This is the file's Styles panel, not the Enterprise Variables API; full
+  design-token extraction still routes through the Builder-backed
+  `index-design-system-with-builder` path above.
+
+#### Paste from Figma (Cmd+C/Cmd+V) vs. a copied frame link
+
+A plain clipboard paste (Cmd+C in Figma, Cmd+V on the Design canvas) is
+handled separately from `import-figma-frame`, because a clipboard paste and a
+copied frame **link** carry fundamentally different information:
+
+- **A copied frame link** (`?node-id=...`) names an exact node. Always exact —
+  use `import-figma-frame`.
+- **A plain clipboard paste** only carries Figma's `figmeta` marker, which is
+  `{fileKey, pasteID, dataType}` — **no node id at all**, and `pasteID` is an
+  ephemeral, server-side identifier that the public REST API can't resolve
+  back to a node. So a clipboard paste can only ever get an exact node import
+  on a **best-effort match**, never a guarantee.
+
+The canvas paste listener (`app/lib/figma-clipboard.ts` +
+`import-figma-clipboard`) handles this automatically:
+
+1. Decodes `figmeta` from the pasted HTML client-side
+   (`extractFigmeta`/`resolveFigmaPasteImportCall`) to decide whether to call
+   `import-figma-clipboard` (figmeta present) or the legacy
+   `import-design-source` HTML path (no figmeta — not a Figma paste, or an
+   older Figma client that doesn't emit the marker).
+2. `import-figma-clipboard` fetches the file's shallow structure (top-level
+   frames + their direct children, `server/lib/figma-node-import.ts`'s
+   `fetchFileStructure(fileKey, 3)`) and heuristically matches it against the
+   pasted content's visible text (`server/lib/figma-clipboard-match.ts`):
+   a frame is only imported when its **name** or at least **two distinct
+   text-layer contents** appear verbatim in the paste. Anything ambiguous or
+   unmatched imports **nothing structural** — it never guesses and never
+   imports the whole file uninvited.
+3. On a confident match, the matched node(s) are fetched and mapped through
+   the same `buildScreenFilesFromFigmaNodes` core `import-figma-frame` uses
+   (`strategy: "restNodes"` in the result, with a `fidelityReport`).
+4. Otherwise it falls back to the legacy visible-HTML paste
+   (`strategy: "htmlFallback"`), and reports why via `matchStatus`
+   (`"ambiguous"`, `"none"`, or `"error"`) and `figmaApiKeyMissing` (no
+   `FIGMA_ACCESS_TOKEN` configured). The canvas paste toast surfaces a hint in
+   both cases: connect the Figma access token, or paste a frame **link**
+   instead for a guaranteed-exact import.
+
+Tell users who want guaranteed pixel-exact imports to copy a frame **link**
+("Copy link to selection" in Figma), not just Cmd+C — a plain paste is
+convenient but only best-effort.
+
 ### Source: Brand Analysis (combines website + notes)
 
 ```bash
diff --git a/templates/design/.agents/skills/export-handoff/SKILL.md b/templates/design/.agents/skills/export-handoff/SKILL.md
index bb6ef9a7b8..3cd277f8b7 100644
--- a/templates/design/.agents/skills/export-handoff/SKILL.md
+++ b/templates/design/.agents/skills/export-handoff/SKILL.md
@@ -17,6 +17,9 @@ How to export designs and generate handoff documentation for developers converti
   with the editor's Download SVG command. The editor's own Download SVG
   command captures the live browser DOM for the most faithful snapshot; use
   the action when you need agent-side SVG export without a live browser.
+  **This is not importable into Figma as editable vectors** — Figma cannot
+  parse `foreignObject` content, so it stays an opaque embedded HTML blob.
+  Use `export-design-as-figma-svg` (below) when the destination is Figma.
 - **PNG**: there is no PNG export action. Point the user to the editor's
   download menu (Download PNG) — PNG export is a client-side rasterization of
   the live canvas and is not exposed as an agent action.
@@ -88,6 +91,60 @@ pnpm action export-pdf --id <designId>
 
 Returns all design data and files needed for the client to render a PDF.
 
+## Export to Figma (SVG)
+
+`export-design-as-figma-svg` exports a design screen (or a selected
+element's subtree) as a genuinely VECTOR SVG document — real
+`<rect>`/`<path>`/`<text>`/`<image>` markup with
+`<linearGradient>`/`<radialGradient>`/`<filter>` defs. Figma's SVG importer
+parses this into normal, editable layers (rect/path/gradients/filters stay
+editable). This is a different artifact from `export-svg` above, whose
+`foreignObject` wrapper Figma cannot import as vectors at all.
+
+```bash
+pnpm action export-design-as-figma-svg --designId <designId>
+```
+
+Optional args:
+
+- `fileId` / `filename` — pick a specific screen (defaults to `index.html`).
+- `nodeId` — scope the export to one selected element's subtree via its
+  `data-agent-native-node-id`, instead of the whole screen.
+- `embedImages` (default `true`) — fetch and inline `http(s)` image sources
+  and background-images as `data:` URIs, so the SVG is self-contained for
+  clipboard paste. Set `false` to keep absolute URLs instead.
+
+Returns `{ svg, filename, report, filePath? }`. `report` classifies every
+element as `vectorized`, `approximated` (mapped with a documented caveat —
+e.g. a non-square gradient angle, a non-uniform border, a radial gradient's
+shape/position), `rasterized` (video/canvas/iframe content, and any element
+with `backdrop-filter`, which SVG cannot express — embedded as a cropped
+screenshot instead), or `omitted`. If no headless Chromium binary is
+available in the current environment (expected in hosted/serverless
+deploys), the action returns `{ ok: false, reason }` instead of throwing —
+fall back to `export-svg` or `export-html`.
+
+**Vectorized-text caveat**: Figma converts every imported SVG `<text>`
+element to outlined vector paths on paste/drag-import. The exported
+geometry is pixel-exact, but text pasted from this export is no longer
+live, editable type in Figma — it's outlines, the same way any other
+SVG-authoring tool's text becomes outlines on import. This is a Figma
+import limitation, not a defect in the export; the report's
+`vectorizedTextCaveat` field carries this note for the agent/user.
+
+**Getting it into Figma**: two supported paths —
+
+1. **Copy, then paste into Figma.** In the editor, right-click a selected
+   element or the canvas and choose **Copy as SVG** (Copy/Paste as ▸ Copy as
+   SVG). This writes the SVG markup to the system clipboard as `text/plain`
+   (the MIME Figma's own paste handler reads for "paste as vector shapes")
+   plus `image/svg+xml` as a secondary representation. Paste directly into a
+   Figma canvas.
+2. **Download, then drag-import.** Figma's file browser also accepts a
+   plain `.svg` file dropped/imported directly — save the `svg` string
+   returned by the action to a `.svg` file and drag it into a Figma page the
+   same way you'd import any other SVG asset.
+
 ## Coding Handoff
 
 When a user wants to convert an Alpine.js + Tailwind prototype into production
diff --git a/templates/design/.agents/skills/visual-edit/SKILL.md b/templates/design/.agents/skills/visual-edit/SKILL.md
index b597602194..3900657017 100644
--- a/templates/design/.agents/skills/visual-edit/SKILL.md
+++ b/templates/design/.agents/skills/visual-edit/SKILL.md
@@ -208,6 +208,17 @@ the connected app's text/code files through the bridge
 - Saves are conflict-checked against the file's on-disk version — a file that
   changed since it was read fails with a version conflict instead of being
   overwritten.
+- React/TSX canvas edits use build/debug provenance to locate the responsible
+  source, but structural meaning belongs to the coding agent. Do not apply a
+  generic AST reparent/group/ungroup transform. Hand off the exact subject and
+  target source anchors plus their runtime relationship; repeated `.map()`
+  instances, shared components, dynamic expressions, and cross-file edits
+  always require semantic inspection.
+- For every semantic React write, read the file first, pass that exact
+  `versionHash` to `write-local-file` with `requireExpectedVersionHash: true`,
+  re-read and re-plan if it conflicts, and
+  verify the resulting HMR/runtime state before treating the preview as saved.
+  Human write consent remains mandatory and cannot be granted by an agent.
 
 ## Verification
 
diff --git a/templates/design/.generated/bridge/editor-chrome.generated.ts b/templates/design/.generated/bridge/editor-chrome.generated.ts
index 7c9e116e29..34ca05f329 100644
--- a/templates/design/.generated/bridge/editor-chrome.generated.ts
+++ b/templates/design/.generated/bridge/editor-chrome.generated.ts
@@ -13,6 +13,9 @@ export const editorChromeBridgeScript: string = `"use strict";
     var textEditingEnabled = !readOnly && textEditingEnabledFlag;
     var designCanvasScreenId = __DESIGN_CANVAS_SCREEN_ID__ || "";
     var designCanvasBoardSurface = !!__DESIGN_CANVAS_BOARD_SURFACE__;
+    var designCanvasContentOffsetX = Number(__DESIGN_CANVAS_CONTENT_OFFSET_X__) || 0;
+    var designCanvasContentOffsetY = Number(__DESIGN_CANVAS_CONTENT_OFFSET_Y__) || 0;
+    var runtimeLayerSnapshotEnabled = !!__RUNTIME_LAYER_SNAPSHOT_ENABLED__;
     var scaleToolEnabled = false;
     var statePreviewNodeId = null;
     var editorChromeScaleX = Math.max(
@@ -121,6 +124,240 @@ export const editorChromeBridgeScript: string = `"use strict";
       if (!el || !el.getAttribute) return "";
       return el.getAttribute("data-agent-native-node-id") || el.getAttribute("data-code-layer-id") || el.getAttribute("data-layer-id") || el.getAttribute("data-builder-id") || el.getAttribute("data-loc") || el.id || "";
     }
+    var reactDebugProvenanceCache = typeof WeakMap !== "undefined" ? /* @__PURE__ */ new WeakMap() : null;
+    function reactDebugProvenance(el) {
+      var cached = reactDebugProvenanceCache?.get(el);
+      if (cached !== void 0) return cached;
+      var fiberKey = Object.keys(el).find(function(key) {
+        return key.indexOf("__reactFiber$") === 0;
+      });
+      if (!fiberKey) return void 0;
+      var fiber = el[fiberKey];
+      for (var depth = 0; fiber && depth < 12; depth += 1) {
+        var stack = String(fiber._debugStack?.stack || "");
+        var lines = stack.split("\\n");
+        for (var index = 0; index < lines.length; index += 1) {
+          var lineText = lines[index];
+          var match = lineText.match(
+            /(?:\\(|\\s)(https?:\\/\\/[^\\s)]+?):(\\d+):(\\d+)\\)?\\s*$/
+          );
+          if (!match) continue;
+          try {
+            var sourceUrl = new URL(match[1]);
+            var pathname = decodeURIComponent(sourceUrl.pathname);
+            if (pathname.indexOf("/node_modules/") >= 0) continue;
+            var sourceFile = pathname.indexOf("/@fs/") === 0 ? pathname.slice("/@fs".length) : pathname.replace(/^\\/+/, "");
+            if (!sourceFile) continue;
+            var componentMatch = lineText.match(/\\bat\\s+([^\\s(]+)\\s*\\(/);
+            var provenance = {
+              sourceFile,
+              line: parseInt(match[2], 10),
+              column: parseInt(match[3], 10),
+              component: componentMatch ? componentMatch[1] : void 0
+            };
+            reactDebugProvenanceCache?.set(el, provenance);
+            return provenance;
+          } catch (_error) {
+          }
+        }
+        fiber = fiber.return;
+      }
+      return void 0;
+    }
+    var runtimeLayerSnapshotTimer = null;
+    var runtimeLayerSnapshotMaxTimer = null;
+    var lastRuntimeLayerSnapshotHtml = "";
+    function runtimeLayerHash(value) {
+      var hash = 2166136261;
+      for (var index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+      }
+      return (hash >>> 0).toString(36);
+    }
+    function runtimeLayerStructuralPath(el) {
+      var parts = [];
+      var node = el;
+      while (node && node !== document.body) {
+        var tag = node.tagName.toLowerCase();
+        var parent = node.parentElement;
+        if (parent) {
+          var sameTag = Array.prototype.filter.call(
+            parent.children,
+            function(sibling) {
+              return sibling.tagName === node.tagName;
+            }
+          );
+          tag += ":nth-of-type(" + (sameTag.indexOf(node) + 1) + ")";
+        }
+        parts.unshift(tag);
+        node = parent;
+      }
+      return parts.join(" > ") || "body";
+    }
+    function ensureRuntimeLayerNodeId(el) {
+      var existing = el.getAttribute("data-agent-native-node-id")?.trim();
+      if (existing) return existing;
+      var provenance = reactDebugProvenance(el);
+      var provenanceKey = provenance ? [
+        provenance.sourceFile,
+        provenance.line,
+        provenance.column || 0,
+        provenance.component || ""
+      ].join(":") : "dom";
+      var nodeId = "runtime-" + runtimeLayerHash(
+        designCanvasScreenId + ":" + provenanceKey + ":" + runtimeLayerStructuralPath(el)
+      );
+      el.setAttribute("data-agent-native-node-id", nodeId);
+      return nodeId;
+    }
+    function isRuntimeLayerVisualNode(el) {
+      if (/^(script|style|template|noscript|link|meta|title)$/i.test(el.tagName)) {
+        return false;
+      }
+      return !(isOverlayElement(el) || el.closest("[data-agent-native-edit-overlay]"));
+    }
+    function serializeRuntimeLayerSnapshot() {
+      if (!document.body) return null;
+      var sourceNodes = Array.prototype.slice.call(
+        document.body.querySelectorAll("*")
+      );
+      var cloneBody = document.body.cloneNode(true);
+      var cloneNodes = Array.prototype.slice.call(
+        cloneBody.querySelectorAll("*")
+      );
+      var nodeCount = 0;
+      for (var index = 0; index < sourceNodes.length && index < cloneNodes.length; index += 1) {
+        var sourceNode = sourceNodes[index];
+        var cloneNode = cloneNodes[index];
+        if (!isRuntimeLayerVisualNode(sourceNode)) {
+          cloneNode.setAttribute("data-an-runtime-layer-remove", "true");
+          continue;
+        }
+        cloneNode.setAttribute(
+          "data-agent-native-node-id",
+          ensureRuntimeLayerNodeId(sourceNode)
+        );
+        var provenance = reactDebugProvenance(sourceNode);
+        if (provenance) {
+          cloneNode.setAttribute("data-source-file", provenance.sourceFile);
+          cloneNode.setAttribute("data-source-line", String(provenance.line));
+          if (provenance.column) {
+            cloneNode.setAttribute(
+              "data-source-column",
+              String(provenance.column)
+            );
+          }
+          if (provenance.component) {
+            cloneNode.setAttribute("data-component-name", provenance.component);
+          }
+        }
+        nodeCount += 1;
+      }
+      cloneBody.querySelectorAll("[data-an-runtime-layer-remove]").forEach(function(node) {
+        node.remove();
+      });
+      cloneBody.querySelectorAll("script,style,template,noscript,link,meta,title").forEach(function(node) {
+        node.remove();
+      });
+      cloneBody.setAttribute(
+        "data-agent-native-node-id",
+        ensureRuntimeLayerNodeId(document.body)
+      );
+      cloneBody.setAttribute("data-an-runtime-layer-snapshot", "true");
+      var html = "<!doctype html><html>" + cloneBody.outerHTML + "</html>";
+      if (html.length > 2e6) return null;
+      return { html, nodeCount };
+    }
+    function postRuntimeLayerSnapshot() {
+      if (runtimeLayerSnapshotTimer !== null) {
+        window.clearTimeout(runtimeLayerSnapshotTimer);
+      }
+      if (runtimeLayerSnapshotMaxTimer !== null) {
+        window.clearTimeout(runtimeLayerSnapshotMaxTimer);
+      }
+      runtimeLayerSnapshotTimer = null;
+      runtimeLayerSnapshotMaxTimer = null;
+      var snapshot = serializeRuntimeLayerSnapshot();
+      if (!snapshot || snapshot.html === lastRuntimeLayerSnapshotHtml) return;
+      lastRuntimeLayerSnapshotHtml = snapshot.html;
+      window.parent.postMessage(
+        {
+          type: "agent-native:runtime-layer-snapshot",
+          payload: snapshot
+        },
+        "*"
+      );
+    }
+    function scheduleRuntimeLayerSnapshot() {
+      if (runtimeLayerSnapshotTimer !== null) {
+        window.clearTimeout(runtimeLayerSnapshotTimer);
+      }
+      runtimeLayerSnapshotTimer = window.setTimeout(
+        postRuntimeLayerSnapshot,
+        300
+      );
+      if (runtimeLayerSnapshotMaxTimer === null) {
+        runtimeLayerSnapshotMaxTimer = window.setTimeout(
+          postRuntimeLayerSnapshot,
+          1500
+        );
+      }
+    }
+    function runtimeLayerClassSignature(value) {
+      return String(value || "").split(/\\s+/).map(function(token) {
+        var parts = token.split(":");
+        var utility = String(parts[parts.length - 1] || "").replace(/^!/, "");
+        if (/^(?:flex|inline-flex|grid|inline-grid|hidden|block|inline-block|flex-row|flex-col)$/.test(
+          utility
+        ) || /^(?:items|justify)-/.test(utility)) {
+          return utility;
+        }
+        return /(?:component|card|button|control)/.test(utility) ? "component-like" : "";
+      }).filter(Boolean).sort().join(" ");
+    }
+    function runtimeLayerStyleSignature(value) {
+      var relevant = {};
+      String(value || "").split(";").forEach(function(declaration) {
+        var separator = declaration.indexOf(":");
+        if (separator < 0) return;
+        var property = declaration.slice(0, separator).trim().toLowerCase();
+        if (!/^(?:display|flex-direction|align-items|justify-content)$/.test(
+          property
+        )) {
+          return;
+        }
+        relevant[property] = declaration.slice(separator + 1).trim();
+      });
+      return Object.keys(relevant).sort().map(function(property) {
+        return property + ":" + relevant[property];
+      }).join(";");
+    }
+    function runtimeLayerMutationIsMeaningful(mutation) {
+      var target = mutation.target;
+      if (target.nodeType === 1 && (isOverlayElement(target) || target.closest?.("[data-agent-native-edit-overlay]"))) {
+        return false;
+      }
+      if (mutation.type === "childList") {
+        var changedNodes = Array.prototype.slice.call(mutation.addedNodes).concat(Array.prototype.slice.call(mutation.removedNodes));
+        return changedNodes.some(function(node) {
+          var element = node.nodeType === 1 ? node : node.parentElement || mutation.target;
+          return !(element.nodeType === 1 && (isOverlayElement(element) || element.closest?.("[data-agent-native-edit-overlay]")));
+        });
+      }
+      if (mutation.type === "characterData") {
+        return true;
+      }
+      if (mutation.type !== "attributes") return false;
+      var name = mutation.attributeName || "";
+      if (name === "class") {
+        return runtimeLayerClassSignature(mutation.oldValue) !== runtimeLayerClassSignature(target.getAttribute("class"));
+      }
+      if (name === "style") {
+        return runtimeLayerStyleSignature(mutation.oldValue) !== runtimeLayerStyleSignature(target.getAttribute("style"));
+      }
+      return true;
+    }
     function isDocumentRootElement(el) {
       return el === document.body || el === document.documentElement;
     }
@@ -592,6 +829,15 @@ export const editorChromeBridgeScript: string = `"use strict";
           if (hasColumn) dataSourceColumn = lastPart;
         }
       }
+      if (!dataSourceFile) {
+        var reactProvenance = reactDebugProvenance(el);
+        if (reactProvenance) {
+          dataSourceFile = reactProvenance.sourceFile;
+          dataSourceLine = String(reactProvenance.line);
+          dataSourceColumn = reactProvenance.column ? String(reactProvenance.column) : null;
+          dataComponentName = dataComponentName || reactProvenance.component || null;
+        }
+      }
       if (dataSourceFile || dataSourceLine || dataSourceColumn || dataComponentName) {
         provenance = {};
         if (dataSourceFile) provenance.sourceFile = dataSourceFile;
@@ -627,11 +873,18 @@ export const editorChromeBridgeScript: string = `"use strict";
           lineHeight: cs.lineHeight,
           letterSpacing: cs.letterSpacing,
           textAlign: cs.textAlign,
+          // Clean longhand for decoration-toggle state (Cmd+U underline /
+          // Cmd+Shift+X strikethrough). Deliberately the longhand, not the
+          // \`textDecoration\` shorthand — see typography-helpers.ts's
+          // PERSISTENCE GOTCHA comment: reads use this clean value, writes
+          // still commit through the shorthand property name.
+          textDecorationLine: cs.textDecorationLine,
           display: cs.display,
           overflow: cs.overflow,
           flexDirection: cs.flexDirection,
           justifyContent: cs.justifyContent,
           alignItems: cs.alignItems,
+          justifyItems: cs.justifyItems,
           alignSelf: cs.alignSelf,
           flexGrow: cs.flexGrow,
           flexShrink: cs.flexShrink,
@@ -639,12 +892,17 @@ export const editorChromeBridgeScript: string = `"use strict";
           order: cs.order,
           gridColumn: cs.gridColumn,
           gridRow: cs.gridRow,
+          gridTemplateColumns: cs.gridTemplateColumns,
+          gridTemplateRows: cs.gridTemplateRows,
+          gridAutoFlow: cs.gridAutoFlow,
           position: cs.position,
           top: cs.top,
           right: cs.right,
           bottom: cs.bottom,
           left: cs.left,
           gap: cs.gap,
+          rowGap: cs.rowGap,
+          columnGap: cs.columnGap,
           width: cs.width,
           height: cs.height,
           opacity: cs.opacity,
@@ -698,6 +956,7 @@ export const editorChromeBridgeScript: string = `"use strict";
           width: rect.width,
           height: rect.height
         },
+        parentBoundingRect: el.parentElement ? rectInfoForElement(el.parentElement) : void 0,
         textContent: el.textContent ? el.textContent.slice(0, 200) : void 0,
         htmlContent: el.innerHTML && el.innerHTML !== el.textContent ? el.innerHTML.slice(0, 4e3) : void 0,
         childElementCount: el.children ? el.children.length : 0,
@@ -1068,6 +1327,11 @@ export const editorChromeBridgeScript: string = `"use strict";
     }
     var selectedEl = null;
     var hoveredEl = null;
+    var lastHoverInfoPostedEl = null;
+    function clearHoverGate() {
+      hoveredEl = null;
+      lastHoverInfoPostedEl = null;
+    }
     var passiveSelectionEls = [];
     var passiveSelectionOverlays = [];
     var activeMarqueeSelection = null;
@@ -1125,6 +1389,8 @@ export const editorChromeBridgeScript: string = `"use strict";
     var spacingHatchNodesByKey = {};
     var spacingOverlayRenderKey = "";
     var activeDragCancel = null;
+    var bridgeSpaceKeyPressed = false;
+    var bridgeSpaceKeyConsumedByDrag = false;
     var activeCrossScreenStyleSnapshot = void 0;
     var spacingDrag = null;
     var lockedSelectors = [];
@@ -1132,7 +1398,7 @@ export const editorChromeBridgeScript: string = `"use strict";
     var lastEditorPointWasBlocked = false;
     function clearRuntimeSelection() {
       selectedEl = null;
-      hoveredEl = null;
+      clearHoverGate();
       setPassiveSelectionElements([]);
       clearSpacingHoverTimer();
       selectedSpacingHovered = false;
@@ -1382,7 +1648,7 @@ export const editorChromeBridgeScript: string = `"use strict";
             } catch (_err) {
             }
           }
-          hoveredEl = null;
+          clearHoverGate();
           if (selectedEl && !isLayerInteractionBlocked(selectedEl)) {
             positionOverlay(selectionOverlay, selectedEl);
             postElementSelect(selectedEl);
@@ -1411,7 +1677,7 @@ export const editorChromeBridgeScript: string = `"use strict";
       });
       applyHiddenSelectors();
       selectedEl = null;
-      hoveredEl = null;
+      clearHoverGate();
       for (var i = 0; i < activeCandidates.length && !selectedEl; i += 1) {
         try {
           var match = document.querySelector(activeCandidates[i]);
@@ -2304,6 +2570,48 @@ export const editorChromeBridgeScript: string = `"use strict";
         }
       }
     }
+    var overlayAnimationTrackingActive = false;
+    var overlayAnimationTrackingUntil = 0;
+    var overlayAnimationTrackingStartedAt = 0;
+    var OVERLAY_ANIMATION_TRACKING_WINDOW_MS = 1e3;
+    var OVERLAY_ANIMATION_TRACKING_MAX_MS = 4e3;
+    function isOverlayAnimationTrackingTarget(target) {
+      if (!target) return false;
+      return target === selectedEl || target === hoveredEl;
+    }
+    function tickOverlayAnimationTracking() {
+      if (!overlayAnimationTrackingActive) return;
+      refreshOverlays();
+      var now = Date.now();
+      if (now >= overlayAnimationTrackingUntil || now - overlayAnimationTrackingStartedAt >= OVERLAY_ANIMATION_TRACKING_MAX_MS) {
+        overlayAnimationTrackingActive = false;
+        return;
+      }
+      window.requestAnimationFrame(tickOverlayAnimationTracking);
+    }
+    function startOverlayAnimationTracking() {
+      var now = Date.now();
+      overlayAnimationTrackingUntil = now + OVERLAY_ANIMATION_TRACKING_WINDOW_MS;
+      if (overlayAnimationTrackingActive) return;
+      overlayAnimationTrackingActive = true;
+      overlayAnimationTrackingStartedAt = now;
+      window.requestAnimationFrame(tickOverlayAnimationTracking);
+    }
+    function onOverlayAnimationTrackingEvent(e) {
+      if (isOverlayAnimationTrackingTarget(e.target)) {
+        startOverlayAnimationTracking();
+      }
+    }
+    document.addEventListener(
+      "transitionrun",
+      onOverlayAnimationTrackingEvent,
+      true
+    );
+    document.addEventListener(
+      "animationstart",
+      onOverlayAnimationTrackingEvent,
+      true
+    );
     function hideMeasurements() {
       measurementOverlay.style.display = "none";
       measurementOverlay.innerHTML = "";
@@ -2540,7 +2848,10 @@ export const editorChromeBridgeScript: string = `"use strict";
         return !primary && !e.altKey && !e.shiftKey;
       }
       if (key === "Tab") return !!selectedEl;
-      if (key === "Delete" || key === "Backspace") return !primary;
+      if (key === "Delete" || key === "Backspace") {
+        if (primary) return key === "Backspace" && !e.altKey && !e.shiftKey;
+        return true;
+      }
       if (/^Arrow/.test(key || "")) return !e.altKey;
       if (primary) {
         return [
@@ -2557,8 +2868,34 @@ export const editorChromeBridgeScript: string = `"use strict";
           "-",
           "0",
           "]",
-          "["
-        ].indexOf(normalized) !== -1 || e.code === "Digit1" || e.code === "Digit2" || key === "1" || key === "2";
+          "[",
+          // Cmd/Ctrl+U — toggle underline (useDesignHotkeys.ts onToggleUnderline).
+          "u",
+          // Cmd/Ctrl+F — find (onFind). Bridge's "primary" doesn't distinguish
+          // Cmd from Ctrl the way isPlatformPrimaryModifier does host-side, but
+          // forwarding is harmless when the host has no match for the combo.
+          "f",
+          // Cmd/Ctrl+R rename / Cmd/Ctrl+Shift+R paste-to-replace (onRename /
+          // onPasteToReplace) — both live under bare primary+r.
+          "r",
+          // Cmd/Ctrl+\\ — toggle UI (onToggleUi).
+          "\\\\"
+        ].indexOf(normalized) !== -1 || e.code === "Digit1" || e.code === "Digit2" || key === "1" || key === "2" || // Cmd/Ctrl+Shift+H / +L — toggle hidden / toggle locked
+        // (onToggleHidden / onToggleLocked). Gated on shiftKey so bare
+        // Cmd+H / Cmd+L — common OS "Hide app" / browser "focus address bar"
+        // shortcuts the host has no bare-primary binding for — are left
+        // alone (see useDesignHotkeys.ts: both require event.shiftKey).
+        e.shiftKey && (normalized === "h" || normalized === "l") || // Cmd/Ctrl+Alt+B detach instance / Cmd/Ctrl+Alt+K create component
+        // (onDetachInstance / onCreateComponent). Gated on altKey so bare
+        // Cmd+B / Cmd+K are left alone — the host has no bare-primary
+        // binding for either.
+        e.altKey && (normalized === "b" || normalized === "k") || // Ctrl+Alt+H / Ctrl+Alt+T — distribute horizontal / tidy up
+        // (onDistributeSelection / onTidyUp). useDesignHotkeys.ts keeps these
+        // on LITERAL Control on every platform (never remapped to Cmd), so
+        // this mirrors that exact gate instead of the generic "primary" flag
+        // — a blanket "t" entry above would otherwise swallow the common
+        // Cmd+T "new tab" browser shortcut for a combo the host never binds.
+        e.ctrlKey && e.altKey && !e.metaKey && !e.shiftKey && (normalized === "h" || normalized === "t");
       }
       if (e.shiftKey && (e.code === "Digit1" || e.code === "Digit2" || key === "1" || key === "2"))
         return true;
@@ -2886,8 +3223,38 @@ export const editorChromeBridgeScript: string = `"use strict";
     function openContextMenuAtEvent(e) {
       stopNativeInteraction(e);
       blurActiveTextEditor();
-      var target = elementFromEditorPoint(e.clientX, e.clientY);
-      if (!target && lastEditorPointWasBlocked) return;
+      var shieldPointerEvents = shieldOverlay.style.pointerEvents;
+      var selectionPointerEvents = selectionOverlay.style.pointerEvents;
+      var highlightPointerEvents = highlightOverlay.style.pointerEvents;
+      shieldOverlay.style.pointerEvents = "none";
+      selectionOverlay.style.pointerEvents = "none";
+      highlightOverlay.style.pointerEvents = "none";
+      var pointTargets = document.elementsFromPoint ? document.elementsFromPoint(e.clientX, e.clientY) : [document.elementFromPoint(e.clientX, e.clientY)];
+      shieldOverlay.style.pointerEvents = shieldPointerEvents;
+      selectionOverlay.style.pointerEvents = selectionPointerEvents;
+      highlightOverlay.style.pointerEvents = highlightPointerEvents;
+      var candidateElements = [];
+      var layerCandidates = [];
+      pointTargets.forEach(function(pointTarget) {
+        if (!pointTarget || pointTarget.nodeType !== 1) return;
+        if (isOverlayElement(pointTarget)) return;
+        var candidate = selectionTargetForHit(pointTarget);
+        if (!candidate || isDocumentRootElement(candidate) || isOverlayElement(candidate) || isLayerInteractionBlocked(candidate) || isTemplateCloneElement(candidate) || candidateElements.indexOf(candidate) !== -1) {
+          return;
+        }
+        candidateElements.push(candidate);
+        var candidateInfo = getElementInfo(candidate);
+        var explicitLabel = candidate.getAttribute && candidate.getAttribute("data-agent-native-layer-name") || "";
+        var textLabel = (candidate.textContent || "").trim().replace(/\\s+/g, " ");
+        var label = explicitLabel || candidateInfo.componentName || candidate.id || (textLabel && textLabel.length <= 48 ? textLabel : "") || candidate.tagName.toLowerCase();
+        var identity = candidateInfo.sourceId || candidateInfo.selector || String(layerCandidates.length);
+        layerCandidates.push({
+          key: String(identity) + ":" + String(layerCandidates.length),
+          label: String(label).slice(0, 80),
+          info: candidateInfo
+        });
+      });
+      var target = candidateElements[0] || null;
       var info = null;
       if (target) {
         selectedSpacingHovered = false;
@@ -2896,7 +3263,6 @@ export const editorChromeBridgeScript: string = `"use strict";
         if (selectedEl && !isLayerInteractionBlocked(selectedEl)) {
           info = getElementInfo(selectedEl);
           positionOverlay(selectionOverlay, selectedEl);
-          postElementSelect(selectedEl, e);
         } else {
           selectedEl = null;
           hideSelectionOverlay();
@@ -2905,9 +3271,11 @@ export const editorChromeBridgeScript: string = `"use strict";
       window.parent.postMessage(
         {
           type: "element-contextmenu",
+          screenId: designCanvasScreenId,
           clientX: e.clientX,
           clientY: e.clientY,
-          payload: info
+          payload: info,
+          layerCandidates
         },
         "*"
       );
@@ -2935,6 +3303,44 @@ export const editorChromeBridgeScript: string = `"use strict";
       }
       return null;
     }
+    function findUniqueRuntimeStructureTarget(selector, sourceId) {
+      var matches = /* @__PURE__ */ new Set();
+      if (typeof sourceId === "string" && sourceId) {
+        var attributes = [
+          "data-agent-native-node-id",
+          "data-code-layer-id",
+          "data-layer-id",
+          "data-builder-id",
+          "data-loc",
+          "id"
+        ];
+        for (var i = 0; i < attributes.length; i += 1) {
+          try {
+            var sourceMatches = document.querySelectorAll(
+              "[" + attributes[i] + '="' + escapeAttribute(sourceId) + '"]'
+            );
+            for (var j = 0; j < sourceMatches.length; j += 1) {
+              matches.add(sourceMatches[j]);
+            }
+          } catch (_err) {
+          }
+        }
+        if (matches.size > 1) return null;
+        if (matches.size === 1) {
+          var sourceMatch = Array.from(matches)[0];
+          return sourceMatch && sourceMatch !== document.body && sourceMatch !== document.documentElement && !isOverlayElement(sourceMatch) && !isLayerInteractionBlocked(sourceMatch) ? sourceMatch : null;
+        }
+      }
+      if (typeof selector !== "string" || !selector) return null;
+      try {
+        var selectorMatches = document.querySelectorAll(selector);
+        if (selectorMatches.length !== 1) return null;
+        var selectorMatch = selectorMatches[0];
+        return selectorMatch !== document.body && selectorMatch !== document.documentElement && !isOverlayElement(selectorMatch) && !isLayerInteractionBlocked(selectorMatch) ? selectorMatch : null;
+      } catch (_err) {
+        return null;
+      }
+    }
     function removeRuntimeTarget(selector, selectorCandidates) {
       var target = findRuntimeTarget(selector, selectorCandidates);
       if (!target || target === document.body || target === document.documentElement)
@@ -2945,7 +3351,7 @@ export const editorChromeBridgeScript: string = `"use strict";
         selectedEl = null;
         hideSelectionOverlay();
       }
-      hoveredEl = null;
+      clearHoverGate();
       highlightOverlay.style.display = "none";
       hideMeasurements();
       refreshOverlays();
@@ -3697,7 +4103,8 @@ export const editorChromeBridgeScript: string = `"use strict";
     function isAbsolutePrimitiveContainer(el) {
       if (!el || (el.tagName || "").toLowerCase() !== "div") return false;
       var primitive = (el.getAttribute("data-an-primitive") || el.getAttribute("data-agent-native-primitive") || "").toLowerCase();
-      if (primitive !== "rectangle" && primitive !== "rect") return false;
+      if (primitive !== "rectangle" && primitive !== "rect" && primitive !== "frame")
+        return false;
       var cs = window.getComputedStyle(el);
       return cs.position === "absolute" || cs.position === "fixed";
     }
@@ -4121,6 +4528,62 @@ export const editorChromeBridgeScript: string = `"use strict";
         dropMode: "flow-insert"
       };
     }
+    function flowMoveTargetForPoint(el, clientX, clientY, excludeEls, keepCurrentParent, ignoreTargetAutoLayout) {
+      if (!el || !el.parentElement) return null;
+      var currentParent = el.parentElement;
+      var dragged = [el].concat(excludeEls || []);
+      var parentRect = currentParent.getBoundingClientRect();
+      var pointerOutsideCurrentParent = clientX < parentRect.left || clientX > parentRect.right || clientY < parentRect.top || clientY > parentRect.bottom;
+      if (keepCurrentParent && pointerOutsideCurrentParent) {
+        var retainedSlot = nearestChildInsertionTarget(
+          currentParent,
+          clientX,
+          clientY,
+          dragged
+        );
+        return retainedSlot || {
+          anchor: currentParent,
+          placement: "inside",
+          axis: parentFlowAxis(currentParent),
+          dropMode: "flow-insert"
+        };
+      }
+      var target = reorderTargetForPoint(el, clientX, clientY, excludeEls);
+      var container = dropContainerForTarget(target);
+      if (ignoreTargetAutoLayout && container && container !== document.body && isAutoLayoutElement(container)) {
+        return {
+          anchor: container,
+          placement: "inside",
+          axis: parentFlowAxis(container),
+          dropMode: "absolute-container"
+        };
+      }
+      if (currentParent !== document.body && (container === document.body || container === document.documentElement || target?.anchor === document.body)) {
+        return {
+          anchor: document.body,
+          placement: "inside",
+          axis: "y",
+          dropMode: "absolute-container"
+        };
+      }
+      if (target && target.dropMode === "flow-insert" && container && container !== document.body && isContainerDropTarget(container) && !isAutoLayoutElement(container)) {
+        target.needsAutoLayoutConversion = true;
+        target.conversionTarget = container;
+      }
+      return target;
+    }
+    function ignoreAutoLayoutForDropTarget(target) {
+      var container = dropContainerForTarget(target);
+      if (!target || !container || container === document.body || !isAutoLayoutElement(container)) {
+        return target;
+      }
+      return {
+        anchor: container,
+        placement: "inside",
+        axis: parentFlowAxis(container),
+        dropMode: "absolute-container"
+      };
+    }
     function elementFromEditorPointIgnoring(clientX, clientY, ignore) {
       var ignoreList = [];
       var previousPointerEvents = [];
@@ -4323,9 +4786,15 @@ export const editorChromeBridgeScript: string = `"use strict";
       for (var i = 0; i < ABS_POSITION_INLINE_PROPS.length; i += 1) {
         htmlEl.style.removeProperty(ABS_POSITION_INLINE_PROPS[i]);
       }
+      var afterRemoval = window.getComputedStyle(htmlEl).position;
+      if (afterRemoval === "absolute" || afterRemoval === "fixed") {
+        htmlEl.style.setProperty("position", "static", "important");
+        target.forceFlowPositionOverride = true;
+      }
     }
     function rebaseAbsoluteMemberForContainerDrop(el, target) {
       if (!el || !target || target.dropMode !== "absolute-container") return;
+      if (target.absoluteCoordinatesPrepared) return;
       var container = dropContainerForTarget(target);
       if (!container || container === document.body || container === el) return;
       if (el.contains && el.contains(container)) return;
@@ -4334,8 +4803,10 @@ export const editorChromeBridgeScript: string = `"use strict";
       if (cs.position !== "absolute" && cs.position !== "fixed") return;
       var containerRect = container.getBoundingClientRect();
       var containerCS = window.getComputedStyle(container);
-      var newOriginX = containerRect.left + readPx(containerCS.borderLeftWidth) - container.scrollLeft;
-      var newOriginY = containerRect.top + readPx(containerCS.borderTopWidth) - container.scrollTop;
+      var boardOffsetX = designCanvasBoardSurface ? designCanvasContentOffsetX : 0;
+      var boardOffsetY = designCanvasBoardSurface ? designCanvasContentOffsetY : 0;
+      var newOriginX = containerRect.left - boardOffsetX + readPx(containerCS.borderLeftWidth) - container.scrollLeft;
+      var newOriginY = containerRect.top - boardOffsetY + readPx(containerCS.borderTopWidth) - container.scrollTop;
       var oldOriginX = -(window.scrollX || 0);
       var oldOriginY = -(window.scrollY || 0);
       var offsetParent = htmlEl.offsetParent;
@@ -4348,8 +4819,10 @@ export const editorChromeBridgeScript: string = `"use strict";
         if (offsetParentIsRealContainingBlock) {
           var opRect = offsetParent.getBoundingClientRect();
           var opCS = window.getComputedStyle(offsetParent);
-          oldOriginX = opRect.left + readPx(opCS.borderLeftWidth) - offsetParent.scrollLeft;
-          oldOriginY = opRect.top + readPx(opCS.borderTopWidth) - offsetParent.scrollTop;
+          var oldContainingBlockOffsetX = designCanvasBoardSurface && offsetParent !== document.body ? boardOffsetX : 0;
+          var oldContainingBlockOffsetY = designCanvasBoardSurface && offsetParent !== document.body ? boardOffsetY : 0;
+          oldOriginX = opRect.left - oldContainingBlockOffsetX + readPx(opCS.borderLeftWidth) - offsetParent.scrollLeft;
+          oldOriginY = opRect.top - oldContainingBlockOffsetY + readPx(opCS.borderTopWidth) - offsetParent.scrollTop;
         }
       }
       var currentLeft = readPx(htmlEl.style.left || cs.left);
@@ -4357,6 +4830,33 @@ export const editorChromeBridgeScript: string = `"use strict";
       htmlEl.style.left = currentLeft + (oldOriginX - newOriginX) + "px";
       htmlEl.style.top = currentTop + (oldOriginY - newOriginY) + "px";
     }
+    function prepareFlowMembersForAbsoluteDrop(members, target, startRects, gestureStartRect, pointerOffset, clientX, clientY) {
+      if (!target || target.dropMode !== "absolute-container") return;
+      var container = dropContainerForTarget(target);
+      if (!container) return;
+      var containerRect = container.getBoundingClientRect();
+      var containerCS = window.getComputedStyle(container);
+      var containerIsBodyContainingBlock = true;
+      if (container === document.body) {
+        containerIsBodyContainingBlock = containerCS.position !== "static" || containerCS.transform !== "none" || (containerCS.getPropertyValue("translate") || "none") !== "none";
+      }
+      var originX = containerIsBodyContainingBlock ? containerRect.left + readPx(containerCS.borderLeftWidth) - container.scrollLeft : -(window.scrollX || 0);
+      var originY = containerIsBodyContainingBlock ? containerRect.top + readPx(containerCS.borderTopWidth) - container.scrollTop : -(window.scrollY || 0);
+      var desiredGestureLeft = clientX - pointerOffset.x;
+      var desiredGestureTop = clientY - pointerOffset.y;
+      var deltaX = desiredGestureLeft - gestureStartRect.left;
+      var deltaY = desiredGestureTop - gestureStartRect.top;
+      members.forEach(function(member, index) {
+        var startRect = startRects[index] || member.getBoundingClientRect();
+        var htmlEl = member;
+        htmlEl.style.position = "absolute";
+        htmlEl.style.left = Math.round(startRect.left + deltaX - originX) + "px";
+        htmlEl.style.top = Math.round(startRect.top + deltaY - originY) + "px";
+        htmlEl.style.removeProperty("right");
+        htmlEl.style.removeProperty("bottom");
+      });
+      target.absoluteCoordinatesPrepared = true;
+    }
     function applyRuntimeReorder(el, target) {
       if (!el || !target || !target.anchor || !target.anchor.parentElement)
         return;
@@ -4392,9 +4892,11 @@ export const editorChromeBridgeScript: string = `"use strict";
           anchorSourceId: getSourceId(target.anchor),
           placement: target.placement,
           dropMode: target.dropMode || "flow-insert",
+          forceFlowPositionOverride: Boolean(target.forceFlowPositionOverride),
           sourceRect: rectInfoForElement(el),
           anchorRect: rectInfoForElement(target.anchor),
-          payload: getElementInfo(el)
+          payload: getElementInfo(el),
+          anchorPayload: getElementInfo(target.anchor)
         },
         "*"
       );
@@ -4561,7 +5063,7 @@ export const editorChromeBridgeScript: string = `"use strict";
       snapGuideV.style.display = "none";
       snapGuideH.style.display = "none";
     }
-    function startMove(e, gestureElParam) {
+    function startMove(e, gestureElParam, pointerStartParam) {
       var gestureEl = gestureElParam || selectedEl;
       if (!gestureEl) return;
       if (isLayerInteractionBlocked(gestureEl)) return;
@@ -4665,7 +5167,14 @@ export const editorChromeBridgeScript: string = `"use strict";
             hideInsertionGuide();
             showTransformBadge("Move layer", cx, cy);
           } else {
-            currentTarget = reorderTargetForPoint(reorderEl, cx, cy, groupOthers);
+            currentTarget = flowMoveTargetForPoint(
+              reorderEl,
+              cx,
+              cy,
+              groupOthers,
+              keepCurrentFlowParent,
+              Boolean(ev.ctrlKey)
+            );
             showInsertionGuideFor(currentTarget);
             showTransformBadge(currentTarget ? "Move layer" : "Move", cx, cy);
           }
@@ -4673,6 +5182,7 @@ export const editorChromeBridgeScript: string = `"use strict";
           document.removeEventListener(events.move, onReorderMove2, true);
           document.removeEventListener(events.up, onReorderUp2, true);
           document.removeEventListener("keydown", onReorderKeyDown2, true);
+          document.removeEventListener("keyup", onReorderKeyUp2, true);
           clearActiveDragCancel(onReorderEscape2);
         }, onReorderEscape2 = function() {
           cleanupReorderDrag2();
@@ -4692,10 +5202,19 @@ export const editorChromeBridgeScript: string = `"use strict";
           suppressNextShieldClickBriefly();
           return true;
         }, onReorderKeyDown2 = function(ev) {
+          if (ev.code === "Space" || ev.key === " ") {
+            keepCurrentFlowParent = true;
+            ev.preventDefault();
+            return;
+          }
           if (ev.key === "Escape") {
             stopNativeInteraction(ev);
             onReorderEscape2();
           }
+        }, onReorderKeyUp2 = function(ev) {
+          if (ev.code !== "Space" && ev.key !== " ") return;
+          keepCurrentFlowParent = false;
+          ev.preventDefault();
         }, onReorderUp2 = function(ev) {
           cleanupReorderDrag2();
           hideTransformBadge();
@@ -4723,6 +5242,14 @@ export const editorChromeBridgeScript: string = `"use strict";
             );
           }
           if (outsideOnDrop) return;
+          currentTarget = flowMoveTargetForPoint(
+            reorderEl,
+            cx,
+            cy,
+            groupOthers,
+            keepCurrentFlowParent,
+            Boolean(ev?.ctrlKey)
+          );
           if (!currentTarget) {
             if (duplicatedForDrag && reorderEl && reorderEl !== originalSelectedEl) {
               if (reorderEl.parentElement)
@@ -4733,6 +5260,21 @@ export const editorChromeBridgeScript: string = `"use strict";
             }
             return;
           }
+          if (currentTarget.needsAutoLayoutConversion && currentTarget.conversionTarget) {
+            applyAutoLayoutConversionForDrop(
+              currentTarget.conversionTarget,
+              groupEls
+            );
+          }
+          prepareFlowMembersForAbsoluteDrop(
+            groupEls,
+            currentTarget,
+            reorderGroupStartRects,
+            reorderGestureStartRect,
+            reorderPointerOffset,
+            cx,
+            cy
+          );
           if (duplicatedForDrag) {
             applyRuntimeReorder(reorderEl, currentTarget);
             postVisualDuplicateChange(
@@ -4758,13 +5300,20 @@ export const editorChromeBridgeScript: string = `"use strict";
             });
           }
         };
-        var onReorderMove = onReorderMove2, cleanupReorderDrag = cleanupReorderDrag2, onReorderEscape = onReorderEscape2, onReorderKeyDown = onReorderKeyDown2, onReorderUp = onReorderUp2;
+        var onReorderMove = onReorderMove2, cleanupReorderDrag = cleanupReorderDrag2, onReorderEscape = onReorderEscape2, onReorderKeyDown = onReorderKeyDown2, onReorderKeyUp = onReorderKeyUp2, onReorderUp = onReorderUp2;
         var reorderEl = gestureEl;
-        var currentTarget = reorderTargetForPoint(
+        var reorderGroupStartRects = groupEls.map(function(member) {
+          return member.getBoundingClientRect();
+        });
+        var reorderGestureStartRect = reorderEl.getBoundingClientRect();
+        var keepCurrentFlowParent = bridgeSpaceKeyPressed;
+        var currentTarget = flowMoveTargetForPoint(
           reorderEl,
           e.clientX,
           e.clientY,
-          groupOthers
+          groupOthers,
+          keepCurrentFlowParent,
+          Boolean(e.ctrlKey)
         );
         showInsertionGuideFor(currentTarget);
         var pointerOutsideIframe = false;
@@ -4772,13 +5321,15 @@ export const editorChromeBridgeScript: string = `"use strict";
         var reorderSourceId = getSourceId(reorderEl);
         var reorderStyleSnapshot = collectPortableStyleSnapshot(reorderEl);
         var reorderRect = reorderEl.getBoundingClientRect();
+        var reorderPointerStart = pointerStartParam || e;
         var reorderPointerOffset = {
-          x: e.clientX - reorderRect.left,
-          y: e.clientY - reorderRect.top
+          x: reorderPointerStart.clientX - reorderRect.left,
+          y: reorderPointerStart.clientY - reorderRect.top
         };
         document.addEventListener(events.move, onReorderMove2, true);
         document.addEventListener(events.up, onReorderUp2, true);
         document.addEventListener("keydown", onReorderKeyDown2, true);
+        document.addEventListener("keyup", onReorderKeyUp2, true);
         setActiveDragCancel(onReorderEscape2);
         return;
       }
@@ -4821,6 +5372,23 @@ export const editorChromeBridgeScript: string = `"use strict";
       if (!duplicatedForDrag && !isGroupDrag) {
         postCrossScreenDrag("start", dragEl, e);
       }
+      var crossScreenDragMoveScheduled = false;
+      var crossScreenDragMovePendingEv = null;
+      function flushCrossScreenDragMove() {
+        crossScreenDragMoveScheduled = false;
+        var pendingEv = crossScreenDragMovePendingEv;
+        crossScreenDragMovePendingEv = null;
+        if (pendingEv) postCrossScreenDrag("move", dragEl, pendingEv);
+      }
+      function scheduleCrossScreenDragMove(ev) {
+        crossScreenDragMovePendingEv = {
+          clientX: ev.clientX,
+          clientY: ev.clientY
+        };
+        if (crossScreenDragMoveScheduled) return;
+        crossScreenDragMoveScheduled = true;
+        window.requestAnimationFrame(flushCrossScreenDragMove);
+      }
       function onMove(ev) {
         if (!moved && Math.hypot(ev.clientX - startX, ev.clientY - startY) > DRAG_THRESHOLD) {
           moved = true;
@@ -4856,19 +5424,24 @@ export const editorChromeBridgeScript: string = `"use strict";
           state.el.style.top = Math.round(state.originTop + appliedDy) + "px";
         });
         if (!duplicatedForDrag && !isGroupDrag) {
-          postCrossScreenDrag("move", dragEl, ev);
+          scheduleCrossScreenDragMove(ev);
         }
         if (!duplicatedForDrag && isOutsideIframeViewport(ev.clientX, ev.clientY)) {
           currentAutoLayoutTarget = null;
           hideInsertionGuide();
           setMembersOpacity(null);
         } else {
-          currentAutoLayoutTarget = !duplicatedForDrag ? autoLayoutInsertionTargetForPoint(
+          currentAutoLayoutTarget = !duplicatedForDrag && !bridgeSpaceKeyPressed ? autoLayoutInsertionTargetForPoint(
             dragEl,
             ev.clientX,
             ev.clientY,
             groupOthers
           ) : null;
+          if (currentAutoLayoutTarget && ev.ctrlKey) {
+            currentAutoLayoutTarget = ignoreAutoLayoutForDropTarget(
+              currentAutoLayoutTarget
+            );
+          }
           if (currentAutoLayoutTarget) {
             showInsertionGuideFor(currentAutoLayoutTarget);
             setMembersOpacity("0.4");
@@ -4904,6 +5477,8 @@ export const editorChromeBridgeScript: string = `"use strict";
         document.removeEventListener(events.up, onUp, true);
         document.removeEventListener("keydown", onMoveKeyDown, true);
         clearActiveDragCancel(cancelMoveDrag);
+        crossScreenDragMoveScheduled = false;
+        crossScreenDragMovePendingEv = null;
       }
       function cancelMoveDrag() {
         cleanupMoveDrag();
@@ -4945,16 +5520,23 @@ export const editorChromeBridgeScript: string = `"use strict";
           restoreSourceDragPosition();
           return;
         }
-        if (ev && !duplicatedForDrag && !outsideOnDrop) {
+        if (ev && !duplicatedForDrag && !outsideOnDrop && !bridgeSpaceKeyPressed) {
           var finalAutoLayoutTarget = autoLayoutInsertionTargetForPoint(
             dragEl,
             ev.clientX,
             ev.clientY,
             groupOthers
           );
+          if (finalAutoLayoutTarget && ev.ctrlKey) {
+            finalAutoLayoutTarget = ignoreAutoLayoutForDropTarget(
+              finalAutoLayoutTarget
+            );
+          }
           if (finalAutoLayoutTarget) {
             currentAutoLayoutTarget = finalAutoLayoutTarget;
           }
+        } else if (bridgeSpaceKeyPressed) {
+          currentAutoLayoutTarget = null;
         }
         if (duplicatedForDrag && !moved) {
           if (dragEl.parentElement) dragEl.parentElement.removeChild(dragEl);
@@ -5043,8 +5625,8 @@ export const editorChromeBridgeScript: string = `"use strict";
       var originalInlineFontSize = resizeEl.style.fontSize;
       ensurePositionable(resizeEl);
       var cs = window.getComputedStyle(resizeEl);
-      var originW = readPx(resizeEl.style.width || cs.width);
-      var originH = readPx(resizeEl.style.height || cs.height);
+      var originW = readPx(cs.width);
+      var originH = readPx(cs.height);
       var originBorderWidth = readPx(
         resizeEl.style.borderWidth || cs.borderWidth
       );
@@ -5059,6 +5641,8 @@ export const editorChromeBridgeScript: string = `"use strict";
       var startX = e.clientX;
       var startY = e.clientY;
       var resizeTheta = currentRotation(resizeEl) * Math.PI / 180;
+      var widthTouched = false;
+      var heightTouched = false;
       function nextRect(ev) {
         var screenDx = ev.clientX - startX;
         var screenDy = ev.clientY - startY;
@@ -5121,15 +5705,29 @@ export const editorChromeBridgeScript: string = `"use strict";
           if (handle.indexOf("n") !== -1 || handle.indexOf("s") !== -1)
             top = origin.top - (height - origin.height) / 2;
         }
-        return { left, top, width, height };
+        var handlesWidth = handle.indexOf("w") !== -1 || handle.indexOf("e") !== -1;
+        var handlesHeight = handle.indexOf("n") !== -1 || handle.indexOf("s") !== -1;
+        var aspectLocked = !!(ev.shiftKey || scaleToolEnabled);
+        var touchesWidth = handlesWidth || aspectLocked && handlesHeight;
+        var touchesHeight = handlesHeight || aspectLocked && handlesWidth;
+        return {
+          left,
+          top,
+          width,
+          height,
+          touchesWidth,
+          touchesHeight
+        };
       }
       function onMove(ev) {
         if (!resizeEl) return;
         var rect = nextRect(ev);
+        if (rect.touchesWidth) widthTouched = true;
+        if (rect.touchesHeight) heightTouched = true;
         resizeEl.style.left = Math.round(rect.left) + "px";
         resizeEl.style.top = Math.round(rect.top) + "px";
-        resizeEl.style.width = Math.round(rect.width) + "px";
-        resizeEl.style.height = Math.round(rect.height) + "px";
+        if (widthTouched) resizeEl.style.width = Math.round(rect.width) + "px";
+        if (heightTouched) resizeEl.style.height = Math.round(rect.height) + "px";
         if (scaleToolEnabled) {
           var kScaleFactor = rect.width / Math.max(1, origin.width);
           if (originBorderWidth > 0) {
@@ -5185,10 +5783,10 @@ export const editorChromeBridgeScript: string = `"use strict";
         var styles = {
           position: resizeEl.style.position,
           left: resizeEl.style.left,
-          top: resizeEl.style.top,
-          width: resizeEl.style.width,
-          height: resizeEl.style.height
+          top: resizeEl.style.top
         };
+        if (widthTouched) styles.width = resizeEl.style.width;
+        if (heightTouched) styles.height = resizeEl.style.height;
         if (scaleToolEnabled && originBorderWidth > 0) {
           styles.borderWidth = resizeEl.style.borderWidth;
         }
@@ -5346,12 +5944,15 @@ export const editorChromeBridgeScript: string = `"use strict";
         var groupGestureMember = !e.altKey ? groupMemberForGestureTarget(dragTarget) : null;
         if (groupGestureMember && collectMoveGroupMembers(groupGestureMember).length > 1) {
           suppressNextShieldClickBriefly();
-          startMove(ev, groupGestureMember);
+          startMove(ev, groupGestureMember, {
+            clientX: startX,
+            clientY: startY
+          });
           return;
         }
         selectTarget(dragTarget, ev);
         suppressNextShieldClickBriefly();
-        startMove(ev);
+        startMove(ev, void 0, { clientX: startX, clientY: startY });
       }
       function onUp(ev) {
         clearPendingShieldDrag();
@@ -5464,6 +6065,14 @@ export const editorChromeBridgeScript: string = `"use strict";
     document.addEventListener(
       "keydown",
       function(e) {
+        if (e.key === " " && e.code === "Space" && !activeTextEditEl && !isEditorTypingTarget(e.target)) {
+          bridgeSpaceKeyPressed = true;
+          if (activeDragCancel) {
+            bridgeSpaceKeyConsumedByDrag = true;
+            stopNativeInteraction(e);
+            return;
+          }
+        }
         if (!activeTextEditEl && pendingBeginTextEdit) {
           if (!(e.isComposing || e.keyCode === 229) && !e.metaKey && !e.ctrlKey) {
             var pendingKey = e.key || "";
@@ -5564,6 +6173,12 @@ export const editorChromeBridgeScript: string = `"use strict";
       "keyup",
       function(e) {
         if (e.key !== " " || e.code !== "Space") return;
+        bridgeSpaceKeyPressed = false;
+        if (bridgeSpaceKeyConsumedByDrag) {
+          bridgeSpaceKeyConsumedByDrag = false;
+          stopNativeInteraction(e);
+          return;
+        }
         if (activeTextEditEl || isEditorTypingTarget(e.target)) return;
         stopNativeInteraction(e);
         window.parent.postMessage(
@@ -5707,6 +6322,21 @@ export const editorChromeBridgeScript: string = `"use strict";
         }
         return;
       }
+      if (!programmaticFlag && isTemplateCloneElement(target)) {
+        showRejectedDragBadge(
+          "Can't edit repeated items directly",
+          e.clientX,
+          e.clientY
+        );
+        window.setTimeout(hideTransformBadge, 1400);
+        var rejectedTextEditFallback = selectionTargetForHit(target);
+        if (rejectedTextEditFallback && !isLayerInteractionBlocked(rejectedTextEditFallback)) {
+          selectedEl = rejectedTextEditFallback;
+          positionOverlay(selectionOverlay, selectedEl);
+          postElementSelect(selectedEl, e);
+        }
+        return;
+      }
       selectedEl = selectionTargetForHit(target) || target;
       var programmaticTextEdit = programmaticFlag;
       var originalText = target.textContent || "";
@@ -6002,6 +6632,7 @@ export const editorChromeBridgeScript: string = `"use strict";
             scheduleSpacingHoverClear(e);
           }
           hideMeasurements();
+          lastHoverInfoPostedEl = null;
           return;
         }
         if (hoveredEl && hoveredEl.closest("[data-agent-native-text-editing]"))
@@ -6036,11 +6667,14 @@ export const editorChromeBridgeScript: string = `"use strict";
         } else {
           hideMeasurements();
         }
-        var info = getLightElementInfo(hoveredEl);
-        window.parent.postMessage(
-          { type: "element-hover", payload: info },
-          "*"
-        );
+        if (hoveredEl !== lastHoverInfoPostedEl) {
+          lastHoverInfoPostedEl = hoveredEl;
+          var info = getLightElementInfo(hoveredEl);
+          window.parent.postMessage(
+            { type: "element-hover", payload: info },
+            "*"
+          );
+        }
       },
       true
     );
@@ -6071,7 +6705,7 @@ export const editorChromeBridgeScript: string = `"use strict";
           updateSpacingOverlay(selectedEl);
           return;
         }
-        hoveredEl = null;
+        clearHoverGate();
         if (!spacingDrag) {
           scheduleSpacingHoverClear(e);
         }
@@ -6122,6 +6756,13 @@ export const editorChromeBridgeScript: string = `"use strict";
         }
         return;
       }
+      if (e.data.type === "set-content-offset") {
+        var nextContentOffsetX = Number(e.data.x);
+        var nextContentOffsetY = Number(e.data.y);
+        designCanvasContentOffsetX = Number.isFinite(nextContentOffsetX) ? nextContentOffsetX : 0;
+        designCanvasContentOffsetY = Number.isFinite(nextContentOffsetY) ? nextContentOffsetY : 0;
+        return;
+      }
       if (e.data.type === "begin-text-edit") {
         var forceBeginTextEdit = e.data.force === true;
         if ((readOnly || !textEditingEnabled) && !forceBeginTextEdit) return;
@@ -6322,13 +6963,15 @@ export const editorChromeBridgeScript: string = `"use strict";
           }
         }
         if (!target) return;
-        if (target !== selectedEl) {
+        var selectionChangedByHost = target !== selectedEl;
+        if (selectionChangedByHost) {
           selectedSpacingHovered = false;
           hoveredSpacingHandleKey = "";
         }
         selectedEl = target;
         positionOverlay(selectionOverlay, target);
         if (hoveredEl === selectedEl) highlightOverlay.style.display = "none";
+        if (selectionChangedByHost) postElementSelect(target);
         return;
       }
       if (e.data.type === "hover-element") {
@@ -6344,7 +6987,7 @@ export const editorChromeBridgeScript: string = `"use strict";
           hoverCandidates.push(String(e.data.selector));
         }
         if (hoverCandidates.length === 0) {
-          hoveredEl = null;
+          clearHoverGate();
           highlightOverlay.style.display = "none";
           hideMeasurements();
           return;
@@ -6374,12 +7017,51 @@ export const editorChromeBridgeScript: string = `"use strict";
           hideSelectionOverlay();
         }
         if (hoveredEl && isLayerInteractionBlocked(hoveredEl)) {
-          hoveredEl = null;
+          clearHoverGate();
           highlightOverlay.style.display = "none";
         }
         applyHiddenSelectors();
         return;
       }
+      if (e.data.type === "runtime-structure-move") {
+        if (readOnly) return;
+        var runtimePlacement = String(e.data.placement || "");
+        if (runtimePlacement !== "before" && runtimePlacement !== "after" && runtimePlacement !== "inside") {
+          return;
+        }
+        var runtimeSubject = findUniqueRuntimeStructureTarget(
+          String(e.data.subjectSelector || ""),
+          typeof e.data.subjectSourceId === "string" ? e.data.subjectSourceId : ""
+        );
+        var runtimeAnchor = findUniqueRuntimeStructureTarget(
+          String(e.data.anchorSelector || ""),
+          typeof e.data.anchorSourceId === "string" ? e.data.anchorSourceId : ""
+        );
+        if (!runtimeSubject || !runtimeAnchor || runtimeSubject === runtimeAnchor || runtimeSubject.contains(runtimeAnchor)) {
+          return;
+        }
+        if (runtimePlacement === "inside" && !isContainerDropTarget(runtimeAnchor) || runtimePlacement !== "inside" && !runtimeAnchor.parentElement) {
+          return;
+        }
+        var runtimeTarget = {
+          anchor: runtimeAnchor,
+          placement: runtimePlacement,
+          axis: parentFlowAxis(
+            runtimePlacement === "inside" ? runtimeAnchor : runtimeAnchor.parentElement
+          ),
+          dropMode: runtimePlacement === "inside" && isAbsolutePrimitiveContainer(runtimeAnchor) ? "absolute-container" : "flow-insert"
+        };
+        var runtimeOrigin = {
+          prevParent: runtimeSubject.parentElement,
+          prevNextSibling: runtimeSubject.nextSibling,
+          prevInlinePositionStyles: snapshotInlinePositionStyles(runtimeSubject)
+        };
+        applyRuntimeReorder(runtimeSubject, runtimeTarget);
+        selectedEl = runtimeSubject;
+        positionOverlay(selectionOverlay, selectedEl);
+        postVisualStructureChange(runtimeSubject, runtimeTarget, runtimeOrigin);
+        return;
+      }
       if (e.data.type === "visual-structure-ack") {
         var move = pendingStructureMoves[e.data.requestId];
         if (!move) return;
@@ -6514,6 +7196,37 @@ export const editorChromeBridgeScript: string = `"use strict";
     window.addEventListener("scroll", scheduleRefreshOverlays, true);
     window.addEventListener("resize", scheduleRefreshOverlays);
     applyEditorChromeScale();
+    if (runtimeLayerSnapshotEnabled && typeof MutationObserver !== "undefined" && document.body) {
+      var runtimeLayerObserver = new MutationObserver(function(mutations) {
+        var hasMeaningfulMutation = mutations.some(
+          runtimeLayerMutationIsMeaningful
+        );
+        if (hasMeaningfulMutation) scheduleRuntimeLayerSnapshot();
+      });
+      runtimeLayerObserver.observe(document.body, {
+        attributes: true,
+        attributeOldValue: true,
+        childList: true,
+        characterData: true,
+        subtree: true,
+        attributeFilter: [
+          "aria-label",
+          "class",
+          "data-agent-native-component",
+          "data-agent-native-layer-name",
+          "data-an-primitive",
+          "data-component-name",
+          "data-source-column",
+          "data-source-file",
+          "data-source-line",
+          "hidden",
+          "id",
+          "style",
+          "title"
+        ]
+      });
+    }
+    if (runtimeLayerSnapshotEnabled) scheduleRuntimeLayerSnapshot();
     window.parent.postMessage(
       { type: "agent-native:editor-chrome-ready" },
       "*"
diff --git a/templates/design/.generated/bridge/embedded-wheel.generated.ts b/templates/design/.generated/bridge/embedded-wheel.generated.ts
index b6af1eaa46..d7ad5891dc 100644
--- a/templates/design/.generated/bridge/embedded-wheel.generated.ts
+++ b/templates/design/.generated/bridge/embedded-wheel.generated.ts
@@ -184,6 +184,11 @@ export const embeddedWheelBridgeScript: string = `"use strict";
       }
       if (e.data.type === "embedded-canvas-pan-mode") {
         leftButtonEnabled = !!e.data.leftButtonEnabled;
+        return;
+      }
+      if (e.data.type === "embedded-canvas-gesture-mode") {
+        wheelEnabled = !!e.data.wheelEnabled;
+        spaceKeyForwardingEnabled = !!e.data.spaceKeyForwardingEnabled;
       }
     }
     function cancelActivePan() {
diff --git a/templates/design/.generated/bridge/hit-test.generated.ts b/templates/design/.generated/bridge/hit-test.generated.ts
index 14810f1ff2..85ac542708 100644
--- a/templates/design/.generated/bridge/hit-test.generated.ts
+++ b/templates/design/.generated/bridge/hit-test.generated.ts
@@ -148,7 +148,8 @@ export const hitTestBridgeScript: string = `"use strict";
     function isAbsolutePrimitiveContainer(el) {
       if (!el || (el.tagName || "").toLowerCase() !== "div") return false;
       var primitive = (el.getAttribute("data-an-primitive") || el.getAttribute("data-agent-native-primitive") || "").toLowerCase();
-      if (primitive !== "rectangle" && primitive !== "rect") return false;
+      if (primitive !== "rectangle" && primitive !== "rect" && primitive !== "frame")
+        return false;
       var cs = window.getComputedStyle(el);
       return cs.position === "absolute" || cs.position === "fixed";
     }
diff --git a/templates/design/.generated/bridge/motion-preview.generated.ts b/templates/design/.generated/bridge/motion-preview.generated.ts
index 47ba06769d..23cedc6ed2 100644
--- a/templates/design/.generated/bridge/motion-preview.generated.ts
+++ b/templates/design/.generated/bridge/motion-preview.generated.ts
@@ -11,6 +11,16 @@ export const motionPreviewBridgeScript: string = `"use strict";
     var loadedTimelineDurationMs = null;
     var touchedProps = {};
     var originalInlineValues = {};
+    var elementCache = {};
+    function resolveTrackElement(nodeId) {
+      var cached = elementCache[nodeId];
+      if (cached && document.contains(cached)) return cached;
+      var el = document.querySelector(
+        '[data-agent-native-node-id="' + nodeId + '"]'
+      );
+      elementCache[nodeId] = el;
+      return el;
+    }
     function camelizeProp(prop) {
       return String(prop).replace(/-([a-z])/g, function(_m, c) {
         return c.toUpperCase();
@@ -477,9 +487,7 @@ export const motionPreviewBridgeScript: string = `"use strict";
     function applyPreview(t) {
       for (var i = 0; i < loadedTracks.length; i++) {
         var track = loadedTracks[i];
-        var el = document.querySelector(
-          '[data-agent-native-node-id="' + track.targetNodeId + '"]'
-        );
+        var el = resolveTrackElement(track.targetNodeId);
         if (!el) continue;
         var value = interpolate(track.keyframes, trackLocalT(track, t));
         if (value === "") continue;
@@ -500,9 +508,7 @@ export const motionPreviewBridgeScript: string = `"use strict";
     function clearPreview() {
       var nodeIds = Object.keys(touchedProps);
       for (var i = 0; i < nodeIds.length; i++) {
-        var el = document.querySelector(
-          '[data-agent-native-node-id="' + nodeIds[i] + '"]'
-        );
+        var el = resolveTrackElement(nodeIds[i]);
         if (!el) continue;
         var props = touchedProps[nodeIds[i]];
         for (var j = 0; j < props.length; j++) {
@@ -515,6 +521,7 @@ export const motionPreviewBridgeScript: string = `"use strict";
       loadedTracks = [];
       loadedDefaultEase = "ease";
       loadedTimelineDurationMs = null;
+      elementCache = {};
     }
     var lastPreviewT = null;
     window.addEventListener("message", function(e) {
diff --git a/templates/design/.generated/bridge/sample.generated.ts b/templates/design/.generated/bridge/sample.generated.ts
index 7a91e93056..5fb2dc56e7 100644
--- a/templates/design/.generated/bridge/sample.generated.ts
+++ b/templates/design/.generated/bridge/sample.generated.ts
@@ -7,6 +7,7 @@ export const sampleBridgeScript: string = `"use strict";
   // app/components/design/bridge/sample.bridge.ts
   (function() {
     window.addEventListener("message", function(e) {
+      if (e.source !== window.parent) return;
       if (!e.data || e.data.type !== "agent-native:sample-ping") return;
       var correlationId = e.data.correlationId ?? "";
       try {
diff --git a/templates/design/AGENTS.md b/templates/design/AGENTS.md
index 1da6db855d..f1034eb40f 100644
--- a/templates/design/AGENTS.md
+++ b/templates/design/AGENTS.md
@@ -67,6 +67,17 @@ patterns live in `.agents/skills/`.
   or pass it as an action parameter. Figma styles and variables are design-system
   inputs, not draggable media assets; route full file/design-system extraction
   through Builder-backed indexing.
+- To import a Figma frame/screen as a real, editable Design screen (not a
+  rendered image), use `import-figma-frame` with a `figmaUrl` (or
+  `fileKey`/`nodeId`) — it maps position, auto-layout, text, fills/gradients,
+  strokes, corner radii, effects, opacity, and blend modes pixel-accurately,
+  falling back to an exact PNG only for vector networks/boolean ops/unsupported
+  node types, and saves the result as a new screen. Read the returned
+  `fidelityReport` (`approximated`, `imageFallbacks`) back to the user when
+  non-trivial. Use `get-figma-styles` for a file's published style names (not
+  the Enterprise Variables API; full token extraction still routes through
+  Builder-backed indexing). See the `design-systems` skill's "Import from
+  Figma" section.
 - Use Alpine.js and Tailwind CDN for interactive prototypes. Prefer Alpine
   directives over raw inline event handlers.
 - Navigate between prototype screens with Alpine state (`x-show`), a
@@ -112,9 +123,14 @@ patterns live in `.agents/skills/`.
   workflow.
 - Persist useful work early: create/update the design and files as soon as a
   coherent candidate exists, then iterate.
-- For non-trivial new design prompts, ask before generating: create/open the
-  design shell, call `show-design-questions`, stop while the main canvas shows
-  the questions, then continue from the user's answers.
+- For a brief or ambiguous _new_ design prompt, ask before generating:
+  create/open the design shell, call `show-design-questions` with a small
+  tailored set, stop while the main canvas shows the questions, then continue
+  from the user's answers. Skip asking when the prompt is already specific,
+  it's a tweak/edit to an existing design, the user already answered a
+  question set for this design and is now iterating, or they say "decide for
+  me"/"surprise me"/"just build it" — see the `design-generation` skill for
+  how to size and word the questions.
 - For multiple screens/states, call `generate-screens` first. It opens the
   infinite screen overview and returns target filenames plus `canvasFrame`
   placements. Then call `generate-design` with those files and pass the matching
@@ -202,12 +218,27 @@ patterns live in `.agents/skills/`.
   layers: text, classes, styles, attributes, source order, and small structural
   changes. Use it for selected-element edits before falling back to full
   `update-design` / `generate-design` rewrites.
+- For localhost React/TSX screens, treat compiler/debug metadata (project-relative
+  source file, line, column, component, and runtime multiplicity) as evidence
+  for locating source, not as permission to run a generic AST transform.
+  Compiler tooling may verify an anchor, classify a literal edit, and validate
+  syntax. Reparenting, grouping/ungrouping, wrappers, dynamic expressions,
+  repeated `.map()` instances, shared components, and cross-file changes must
+  be handed to the coding agent with both runtime relationships and exact
+  source anchors so it can inspect the surrounding program semantics.
+- A localhost React handoff must read each source file first, write with the
+  exact returned `versionHash` as `expectedVersionHash` with
+  `requireExpectedVersionHash: true`, re-read and re-plan on conflict, and leave the
+  optimistic canvas preview in place until the dev server/HMR confirms the
+  runtime result. Never report a semantic canvas change as persisted merely
+  because it was submitted to the coding agent.
 - Prefer `data-agent-native-layer-name="Readable name"` on meaningful elements.
   The projection uses it before semantic/text fallbacks, and layer renames should
   persist by updating that attribute.
-- Current limitation: visual code-layer edits are HTML-only. Localhost source
-  mode can list and resolve local routes now, but file reads/writes remain a
-  bridge contract until explicit permission controls are hardened.
+- Inline/Alpine screens continue to use deterministic HTML code-layer edits.
+  Localhost React/TSX screens use the semantic coding-agent handoff above;
+  deterministic direct React writes remain intentionally limited to narrowly
+  proven literal edits and never include generic structural transforms.
 
 ## Code Workspace
 
@@ -282,12 +313,16 @@ patterns live in `.agents/skills/`.
   and live app captures. See the same skill section.
 - **Components**: `create-component` promotes a selected element into a
   recognised reusable component; `index-components` scans a design's HTML for
-  existing component annotations; `get-component-details`,
+  existing component annotations; `list-design-components` scans all HTML
+  screens for swap targets; `get-component-details`,
   `preview-component-prop-edit`, `apply-component-prop-edit`, and
   `open-component-source` inspect, preview, persist, and navigate to a
-  component instance. See the `design-generation` skill's "Component reuse"
-  section — promote a 3+ times repeated pattern instead of inventing another
-  near-duplicate.
+  component instance. Use `go-to-main-component` to select the earliest known
+  instance, `swap-component-instance` to replace an inline/Alpine instance
+  while preserving same-named prop overrides, and
+  `detach-component-instance` to turn an instance into plain editable markup.
+  See the `design-generation` skill's "Component reuse" section — promote a
+  3+ times repeated pattern instead of inventing another near-duplicate.
 
 ## Full App Building
 
diff --git a/templates/design/actions/add-localhost-screens.action.spec.ts b/templates/design/actions/add-localhost-screens.action.spec.ts
index 7d6592a6d3..a082510c43 100644
--- a/templates/design/actions/add-localhost-screens.action.spec.ts
+++ b/templates/design/actions/add-localhost-screens.action.spec.ts
@@ -28,11 +28,22 @@ const mocks = vi.hoisted(() => ({
     }>,
     selectCount: 0,
     insertedFile: null as Record<string, unknown> | null,
+    insertedFiles: [] as Array<Record<string, unknown>>,
     updatedFiles: [] as Array<{
       values: Record<string, unknown>;
       where: unknown;
     }>,
     updatedDesignData: null as Record<string, unknown> | null,
+    // Forces the next insert() to throw a unique-constraint-violation error
+    // once, simulating a concurrent request winning the insert race for the
+    // same (design_id, filename) pair.
+    insertConflictOnce: false,
+    // The row a concurrent request is simulated to have already committed —
+    // returned by the conflict-recovery lookup after insertConflictOnce fires.
+    winnerFile: null as Record<string, unknown> | null,
+    // Forces the next insert() to throw a non-constraint error once, to prove
+    // the conflict recovery path doesn't swallow unrelated failures.
+    insertGenericErrorOnce: false,
   },
 }));
 
@@ -93,13 +104,40 @@ vi.mock("../server/db/index.js", () => ({
           }),
         };
       }
+      if (mocks.state.selectCount === 3) {
+        return {
+          from: () => ({ where: () => Promise.resolve(mocks.state.files) }),
+        };
+      }
+      // 4th+ select: the conflict-recovery lookup for whichever row won a
+      // simulated concurrent insert race (see insertConflictOnce/winnerFile).
       return {
-        from: () => ({ where: () => Promise.resolve(mocks.state.files) }),
+        from: () => ({
+          where: () => ({
+            limit: () =>
+              Promise.resolve(
+                mocks.state.winnerFile ? [mocks.state.winnerFile] : [],
+              ),
+          }),
+        }),
       };
     },
     insert: () => ({
       values: (values: Record<string, unknown>) => {
+        if (mocks.state.insertGenericErrorOnce) {
+          mocks.state.insertGenericErrorOnce = false;
+          throw new Error("boom: unrelated insert failure");
+        }
+        if (mocks.state.insertConflictOnce) {
+          mocks.state.insertConflictOnce = false;
+          const err = new Error(
+            'duplicate key value violates unique constraint "design_files_design_filename_unique_idx"',
+          );
+          (err as unknown as { code: string }).code = "23505";
+          throw err;
+        }
         mocks.state.insertedFile = values;
+        mocks.state.insertedFiles.push(values);
         return Promise.resolve();
       },
     }),
@@ -126,8 +164,12 @@ describe("add-localhost-screens refresh behavior", () => {
   beforeEach(() => {
     mocks.state.selectCount = 0;
     mocks.state.insertedFile = null;
+    mocks.state.insertedFiles = [];
     mocks.state.updatedFiles = [];
     mocks.state.updatedDesignData = null;
+    mocks.state.insertConflictOnce = false;
+    mocks.state.winnerFile = null;
+    mocks.state.insertGenericErrorOnce = false;
     mocks.assertAccess.mockReset().mockResolvedValue(undefined);
     mocks.applyText.mockReset().mockResolvedValue(undefined);
     mocks.hasCollabState.mockReset().mockResolvedValue(false);
@@ -297,4 +339,98 @@ describe("add-localhost-screens refresh behavior", () => {
     });
     expect(result.screens[0]?.filename).toBe("localhost-home-2.html");
   });
+
+  it("never inserts two design_files rows for the same route requested twice in one call", async () => {
+    // `existingFiles`/route-candidate matching is snapshotted once above the
+    // per-route loop and never refreshed mid-loop, so two entries resolving
+    // to the same route (repeated `paths`, or a `path` duplicating a
+    // `routeId`-addressed entry) used to each see "no existing match" and
+    // each insert their own design_files row for the identical route.
+    const result = await action.run({
+      designId: "design_1",
+      connectionId: "conn_1",
+      paths: ["/settings", "/settings"],
+      startX: 0,
+      startY: 0,
+      gap: 160,
+    });
+
+    expect(mocks.state.insertedFiles).toHaveLength(1);
+    expect(mocks.state.insertedFiles[0]).toMatchObject({
+      filename: "localhost-settings.html",
+    });
+    expect(result.screens).toHaveLength(1);
+  });
+
+  it("still creates distinct screens when the same route is requested twice with different explicit viewports", async () => {
+    // A duplicate route request is only collapsed when its explicit
+    // width/height also match — an intentional multi-viewport request for
+    // the same route must still create its own variant per viewport.
+    const result = await action.run({
+      designId: "design_1",
+      connectionId: "conn_1",
+      routes: [
+        { path: "/settings", width: 1280, height: 900 },
+        { path: "/settings", width: 390, height: 844 },
+      ],
+      startX: 0,
+      startY: 0,
+      gap: 160,
+    });
+
+    expect(mocks.state.insertedFiles).toHaveLength(2);
+    expect(result.screens).toHaveLength(2);
+  });
+
+  it("recovers when a concurrent request wins the insert race for the same route/filename", async () => {
+    // Cross-request race: this request's `existingFiles` snapshot (taken once,
+    // up front) found no match for /settings, but by the time its insert
+    // executes a concurrent add-localhost-screens call has already committed
+    // the winning design_files row for the identical (design_id, filename)
+    // pair. The design_files_design_filename_unique_idx unique index (see
+    // server/plugins/db.ts) turns that into a real constraint-violation error
+    // — forced here via insertConflictOnce — which the action must catch and
+    // recover from by adopting the winning row instead of throwing.
+    mocks.state.insertConflictOnce = true;
+    mocks.state.winnerFile = {
+      id: "winner_file",
+      designId: "design_1",
+      filename: "localhost-settings.html",
+      fileType: "html",
+      content: "http://localhost:5173/settings?winner=1",
+    };
+
+    const result = await action.run({
+      designId: "design_1",
+      connectionId: "conn_1",
+      paths: ["/settings"],
+      startX: 0,
+      startY: 0,
+      gap: 160,
+    });
+
+    expect(mocks.state.insertedFile).toBeNull();
+    expect(mocks.state.updatedFiles).toHaveLength(1);
+    expect(result.screens).toHaveLength(1);
+    expect(result.screens[0]?.id).toBe("winner_file");
+    expect(result.placedFrames[0]?.fileId).toBe("winner_file");
+  });
+
+  it("rethrows a non-conflict insert error instead of silently swallowing it", async () => {
+    // isUniqueConstraintViolation must only catch the specific
+    // unique/primary-key-violation error class it's meant to recover from —
+    // any other insert failure (e.g. a connection error) must still surface.
+    mocks.state.insertGenericErrorOnce = true;
+
+    await expect(
+      action.run({
+        designId: "design_1",
+        connectionId: "conn_1",
+        paths: ["/settings"],
+        startX: 0,
+        startY: 0,
+        gap: 160,
+      }),
+    ).rejects.toThrow("boom: unrelated insert failure");
+  });
 });
diff --git a/templates/design/actions/add-localhost-screens.ts b/templates/design/actions/add-localhost-screens.ts
index 28c4aa8215..5bfcc2ef9b 100644
--- a/templates/design/actions/add-localhost-screens.ts
+++ b/templates/design/actions/add-localhost-screens.ts
@@ -25,6 +25,7 @@ import {
   type CanvasFrameGeometry,
   type CanvasFramePlacement,
 } from "../shared/canvas-frames.js";
+import { isUniqueConstraintViolation } from "../shared/db-conflict.js";
 import {
   makeLocalhostRouteId,
   titleFromRoutePath,
@@ -488,6 +489,18 @@ export default defineAction({
       height: number;
     }> = [];
     const placementIntents: PlacementIntent[] = [];
+    // Duplicate-route guard: `existingFiles`/`existingByFilename`/the
+    // route-candidate lookups below are all snapshotted ONCE above the loop
+    // and never refreshed as new files are inserted mid-loop, so two entries
+    // in the SAME `requestedRoutes` call that resolve to the same route
+    // (repeated `paths`, or a `routeId` and a `path` naming the same route)
+    // each independently see "no existing match" and each insert a fresh
+    // `design_files` row — two overlapping screens for one route. Track
+    // routeIds already processed THIS call (keyed with width/height so an
+    // intentional multi-viewport request for the same route still creates
+    // its distinct variants) and skip later duplicates outright.
+    const seenRouteRequestKeys = new Set<string>();
+    let placementIndex = 0;
 
     for (let index = 0; index < requestedRoutes.length; index += 1) {
       const input = requestedRoutes[index]!;
@@ -505,6 +518,9 @@ export default defineAction({
       );
       const routeId =
         input.routeId ?? manifestRoute?.id ?? makeLocalhostRouteId(path);
+      const routeRequestKey = `${routeId}::${input.width ?? ""}x${input.height ?? ""}`;
+      if (seenRouteRequestKeys.has(routeRequestKey)) continue;
+      seenRouteRequestKeys.add(routeRequestKey);
       const title =
         input.title ?? manifestRoute?.title ?? titleFromRoutePath(path);
       const sourceFile = input.sourceFile ?? manifestRoute?.sourceFile;
@@ -619,7 +635,9 @@ export default defineAction({
       const filename =
         existing?.filename ??
         uniqueFilename(path, usedFilenames, preferredFilename);
-      const fileId = existing?.id ?? nanoid();
+      // Reassigned below if a concurrent request wins the insert race for
+      // this exact (designId, filename) pair — see the `else` branch.
+      let fileId = existing?.id ?? nanoid();
       const existingScreenMetadata = existing
         ? metadataForFile(
             existing.id,
@@ -656,16 +674,50 @@ export default defineAction({
           await seedFromText(existing.id, url);
         }
       } else {
-        await db.insert(schema.designFiles).values({
-          id: fileId,
-          designId,
-          filename,
-          fileType: "html",
-          content: url,
-          createdAt: now,
-          updatedAt: now,
-        });
-        await seedFromText(fileId, url);
+        try {
+          await db.insert(schema.designFiles).values({
+            id: fileId,
+            designId,
+            filename,
+            fileType: "html",
+            content: url,
+            createdAt: now,
+            updatedAt: now,
+          });
+          await seedFromText(fileId, url);
+        } catch (err) {
+          if (!isUniqueConstraintViolation(err)) throw err;
+          // Cross-request race: this snapshot's `existingFiles` query ran
+          // before a concurrent add-localhost-screens call (for the same
+          // route) committed its own insert, so both requests independently
+          // computed the same deterministic filename and both tried to
+          // create it. The `design_files_design_filename_unique_idx` unique
+          // index (see server/plugins/db.ts) turns the loser's insert into
+          // this error instead of a silent duplicate screen. Recover by
+          // adopting whichever row actually won the race and updating its
+          // content, the same way the `existing` branch above does.
+          const [winner] = await db
+            .select()
+            .from(schema.designFiles)
+            .where(
+              and(
+                eq(schema.designFiles.designId, designId),
+                eq(schema.designFiles.filename, filename),
+              ),
+            )
+            .limit(1);
+          if (!winner) throw err;
+          fileId = winner.id;
+          await db
+            .update(schema.designFiles)
+            .set({ content: url, fileType: "html", updatedAt: now })
+            .where(eq(schema.designFiles.id, winner.id));
+          if (await hasCollabState(winner.id)) {
+            await applyText(winner.id, url, "content", "agent");
+          } else {
+            await seedFromText(winner.id, url);
+          }
+        }
       }
 
       savedScreens.push({
@@ -688,12 +740,13 @@ export default defineAction({
         x:
           input.x ??
           existingFrame?.x ??
-          layoutStartX + index * (width + layoutGap),
+          layoutStartX + placementIndex * (width + layoutGap),
         y: input.y ?? existingFrame?.y ?? layoutStartY,
         width,
         height,
-        z: input.z ?? existingFrame?.z ?? index,
+        z: input.z ?? existingFrame?.z ?? placementIndex,
       };
+      placementIndex += 1;
       placementIntents.push({
         fileId,
         filename,
diff --git a/templates/design/actions/apply-component-prop-edit.interleave.spec.ts b/templates/design/actions/apply-component-prop-edit.interleave.spec.ts
index c7019db481..8bd321428b 100644
--- a/templates/design/actions/apply-component-prop-edit.interleave.spec.ts
+++ b/templates/design/actions/apply-component-prop-edit.interleave.spec.ts
@@ -28,6 +28,7 @@ import * as Y from "yjs";
 // Fake @agent-native/core/collab backed by a real per-docId Y.Doc registry.
 // ---------------------------------------------------------------------------
 const collabDocs = vi.hoisted(() => ({ docs: new Map<string, unknown>() }));
+const accessState = vi.hoisted(() => ({ sourceType: "inline" }));
 
 function getOrCreateDoc(docId: string): InstanceType<typeof Y.Doc> {
   let doc = collabDocs.docs.get(docId) as
@@ -83,10 +84,10 @@ vi.mock("@agent-native/core/collab", () => ({
 
 vi.mock("@agent-native/core/sharing", () => ({
   assertAccess: vi.fn().mockResolvedValue({ role: "editor", resource: {} }),
-  resolveAccess: vi.fn().mockResolvedValue({
+  resolveAccess: vi.fn(async () => ({
     role: "editor",
-    resource: { data: JSON.stringify({ sourceType: "inline" }) },
-  }),
+    resource: { data: JSON.stringify({ sourceType: accessState.sourceType }) },
+  })),
   accessFilter: vi.fn().mockReturnValue(undefined),
 }));
 
@@ -207,10 +208,31 @@ function baseDoc(): string {
 beforeEach(() => {
   collabDocs.docs.clear();
   designFilesStore.rows.clear();
+  accessState.sourceType = "inline";
   seedFile(baseDoc());
 });
 
 describe("apply-component-prop-edit CAS safety (false-CAS fix)", () => {
+  it("fails closed for localhost sources without touching the SQL HTML mirror", async () => {
+    accessState.sourceType = "localhost";
+    const original = currentFileRef().content;
+
+    const result = await action.run({
+      designId: DESIGN_ID,
+      nodeId: "btn-1",
+      edit: { kind: "classReplace", from: "bg-blue-500", to: "bg-red-500" },
+    } as never);
+
+    expect(result).toMatchObject({
+      sourceType: "localhost",
+      persisted: false,
+      ctaRequired: true,
+    });
+    expect(result.ctaMessage).toMatch(/dedicated consented/i);
+    expect(currentFileRef().content).toBe(original);
+    expect(collabDocs.docs.size).toBe(0);
+  });
+
   it("succeeds and preserves a sibling's concurrent edit when the action's own read observes the latest base (no clobber of a landed sibling write)", async () => {
     await seedFromText(FILE_ID, baseDoc());
 
@@ -236,6 +258,28 @@ describe("apply-component-prop-edit CAS safety (false-CAS fix)", () => {
     expect(finalLive.content).toContain("bg-red-500");
   });
 
+  it("preserves an unsaved caller working copy when its revision still matches the unchanged live base", async () => {
+    const workingCopy = baseDoc().replace(
+      "Sibling text",
+      "Sibling text (unsaved locally)",
+    );
+
+    const result = (await action.run({
+      designId: DESIGN_ID,
+      nodeId: "btn-1",
+      edit: { kind: "classReplace", from: "bg-blue-500", to: "bg-red-500" },
+      source: {
+        currentContent: workingCopy,
+        revision: "2026-07-06T00:00:00.000Z",
+      },
+    } as never)) as { persisted: boolean };
+
+    expect(result.persisted).toBe(true);
+    const finalLive = await readLiveSourceFile(currentFileRef());
+    expect(finalLive.content).toContain("Sibling text (unsaved locally)");
+    expect(finalLive.content).toContain("bg-red-500");
+  });
+
   it("rejects a persist whose expectedVersionHash is stale relative to what's live, instead of silently overwriting the concurrent writer's change", async () => {
     // Prove the CAS is a real check (not a check-against-self no-op): build
     // the exact false-CAS shape the bug had directly against
diff --git a/templates/design/actions/apply-component-prop-edit.ts b/templates/design/actions/apply-component-prop-edit.ts
index 1fbc3397e7..be0d3155aa 100644
--- a/templates/design/actions/apply-component-prop-edit.ts
+++ b/templates/design/actions/apply-component-prop-edit.ts
@@ -12,11 +12,12 @@
  *                    HTML attribute on the component root.
  * - `classReplace` — replaces one Tailwind class with another on the root node.
  *
- * **Tier B (real-app, localhost / fusion):**  prop writes require the
- * `applyEdit` source capability.  Localhost sources have it (design bridge +
- * user write consent); fusion sources gain it after bridge hardening.  For
- * sources without it the action returns a `ctaRequired: true` response and
- * does not modify any source.
+ * **Real-app sources (localhost / fusion):** deliberately fail closed. This
+ * action's patcher operates on SQL-backed HTML design files; it must never be
+ * reused for compiled JSX/TSX source. Real-app prop persistence needs a
+ * dedicated consented, version-guarded bridge transform. Until that exists,
+ * callers may preview but this action returns `ctaRequired: true` without
+ * reading or modifying a design file.
  *
  * See DESIGN-STUDIO-PLAN.md §6.1, §7 (preview/apply contract), §11 phase 2.
  */
@@ -38,10 +39,11 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 import {
+  prepareInlineSourceEdit,
+  SourceWorkspaceEditConflictError,
   writeInlineSourceFile,
   type SourceWorkspaceFile,
 } from "../server/source-workspace.js";
-import { resolveSourceCapabilities } from "../shared/capability-resolver.js";
 import {
   applyVisualEdit,
   buildCodeLayerProjection,
@@ -56,9 +58,7 @@ import {
   componentNameFor,
   componentNodeIdMatches,
 } from "../shared/component-model.js";
-import { hasCapability } from "../shared/design-source-capabilities.js";
 import { designSourceTypeFromData } from "../shared/source-mode.js";
-import { sourceContentHash } from "../shared/source-workspace.js";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -174,8 +174,8 @@ export default defineAction({
     "For inline/Alpine designs, edits the data-agent-native-prop-* attributes, " +
     "x-data expression, or class list of the component root via the deterministic " +
     "HTML-patch path (same seam as apply-visual-edit). " +
-    "For real-app sources, the applyEdit capability must be available; if not, " +
-    "returns ctaRequired=true without modifying any file.",
+    "For real-app sources, returns ctaRequired=true without modifying any file; " +
+    "compiled source requires a dedicated consented bridge transform.",
   schema: z.object({
     designId: z.string().describe("Design project ID"),
     nodeId: z
@@ -234,19 +234,21 @@ export default defineAction({
       .optional(),
   }),
   run: async ({ designId, nodeId, fileId, edit, source }) => {
-    const db = getDb();
-
     // ── Access check ────────────────────────────────────────────────────────
     const access = await resolveAccess("design", designId);
     if (!access) throw new Error("Design not found");
 
-    // ── Source type + capability gate ────────────────────────────────────────
+    // ── Source type gate ────────────────────────────────────────────────────
     const rawData = (access.resource as { data?: unknown }).data;
     const sourceType = designSourceTypeFromData(rawData);
-    const caps = resolveSourceCapabilities(sourceType);
 
-    // Real-app sources gate on `applyEdit` (bridge write hardening).
-    if (sourceType !== "inline" && !hasCapability(caps, "applyEdit")) {
+    // Fail closed for every real-app tier even if its generic capability map
+    // advertises applyEdit. This action only knows how to patch SQL-backed HTML;
+    // allowing localhost through here could report success for the mirror while
+    // leaving the real JSX/TSX file untouched. A future compiled-source action
+    // must perform consent, canonical path resolution, AST anchoring, and an
+    // expected-version bridge write as one dedicated transaction.
+    if (sourceType !== "inline") {
       return {
         designId,
         nodeId,
@@ -254,13 +256,14 @@ export default defineAction({
         persisted: false,
         ctaRequired: true,
         ctaMessage:
-          "Prop write-back to real app sources requires the bridge applyEdit " +
-          "capability, which lands with bridge write hardening. " +
+          "Prop write-back to real app sources requires a dedicated consented, " +
+          "version-guarded compiled-source transform. " +
           "Use preview-component-prop-edit to preview without persisting.",
       };
     }
 
     await assertAccess("design", designId, "editor");
+    const db = getDb();
 
     // ── Fetch file ───────────────────────────────────────────────────────────
     const conditions = [
@@ -289,12 +292,24 @@ export default defineAction({
 
     if (!file) throw new Error("Design HTML file not found.");
 
-    if (
-      source?.currentContent &&
-      source.revision &&
-      file.updatedAt &&
-      source.revision !== file.updatedAt
-    ) {
+    const workspaceFile: SourceWorkspaceFile = {
+      id: file.id,
+      designId: file.designId,
+      filename: file.filename,
+      fileType: "html",
+      content: file.content,
+      createdAt: null,
+      updatedAt: file.updatedAt,
+    };
+    let prepared: Awaited<ReturnType<typeof prepareInlineSourceEdit>>;
+    try {
+      prepared = await prepareInlineSourceEdit({
+        file: workspaceFile,
+        currentContent: source?.currentContent,
+        revision: source?.revision,
+      });
+    } catch (error) {
+      if (!(error instanceof SourceWorkspaceEditConflictError)) throw error;
       return {
         designId,
         nodeId,
@@ -307,18 +322,12 @@ export default defineAction({
       };
     }
 
-    // Prefer explicit editor content after the caller's revision check, and use
-    // the saved SQL content as the fallback. Collab/Yjs reads can be stale
-    // across local dev worker processes and make prop controls lag behind.
-    const html =
-      typeof source?.currentContent === "string"
-        ? source.currentContent
-        : (file.content ?? "");
-    // Capture the hash of this EXACT base — the same string the transform
-    // below reads from — so persistEdit can pass it through as
-    // expectedVersionHash. A re-read at persist time would hash whatever is
-    // live "then" instead of proving this base is still current.
-    const baseVersionHash = sourceContentHash(html);
+    // The transform runs against the caller's working copy (when supplied),
+    // while the persist CAS uses the live hash that working copy is allowed to
+    // replace. Keeping those identities separate preserves rapid unsaved prop
+    // edits without weakening concurrent-writer rejection.
+    const html = prepared.content;
+    const baseVersionHash = prepared.expectedVersionHash;
 
     // ── Resolve node ─────────────────────────────────────────────────────────
     const codeLayerSource: CodeLayerSource = {
diff --git a/templates/design/actions/apply-motion-edit.interleave.spec.ts b/templates/design/actions/apply-motion-edit.interleave.spec.ts
index c1d24ee30b..488622aa47 100644
--- a/templates/design/actions/apply-motion-edit.interleave.spec.ts
+++ b/templates/design/actions/apply-motion-edit.interleave.spec.ts
@@ -391,6 +391,27 @@ describe("apply-motion-edit collab-aware persist (contract-bypass fix)", () => {
     expect(finalLive.content).toContain("data-agent-native-motion");
   });
 
+  it("preserves an unsaved caller working copy when its revision still matches the unchanged live base", async () => {
+    const workingCopy = baseDoc().replace(
+      "Caption text",
+      "Caption text (unsaved locally)",
+    );
+
+    const result = await action.run({
+      designId: DESIGN_ID,
+      fileId: FILE_ID,
+      tracks: oneTrack(),
+      durationMs: 500,
+      currentContent: workingCopy,
+      revision: "2026-07-06T00:00:00.000Z",
+    } as never);
+
+    expect(result.persisted).toBe(true);
+    const finalLive = await readLiveSourceFile(currentFileRef());
+    expect(finalLive.content).toContain("Caption text (unsaved locally)");
+    expect(finalLive.content).toContain("data-agent-native-motion");
+  });
+
   it("rejects (loud, not silent) when a concurrent write lands using a caller-supplied stale currentContent base", async () => {
     // The action supports a caller-supplied `currentContent` param used
     // instead of the live read as the patch base. If that base has gone
diff --git a/templates/design/actions/apply-motion-edit.ts b/templates/design/actions/apply-motion-edit.ts
index f8f3972da2..2819bdf40b 100644
--- a/templates/design/actions/apply-motion-edit.ts
+++ b/templates/design/actions/apply-motion-edit.ts
@@ -32,7 +32,7 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
 import {
-  readLiveSourceFile,
+  prepareInlineSourceEdit,
   writeInlineSourceFile,
   type SourceWorkspaceFile,
 } from "../server/source-workspace.js";
@@ -51,7 +51,6 @@ import {
   readTimelinePlaybackMode,
   withTimelinePlaybackMode,
 } from "../shared/motion-timeline.js";
-import { sourceContentHash } from "../shared/source-workspace.js";
 
 // ─── DoS-guard caps ──────────────────────────────────────────────────────────
 //
@@ -343,7 +342,15 @@ export default defineAction({
       .describe(
         "Current open editor HTML for the target file. When supplied, the " +
           "managed motion CSS is patched into this content instead of the " +
-          "last SQL snapshot so in-flight local edits are preserved.",
+          "last SQL snapshot so in-flight local edits are preserved. " +
+          "revision must also be supplied.",
+      ),
+    revision: z
+      .string()
+      .optional()
+      .describe(
+        "design_files.updatedAt value the currentContent is based on. " +
+          "Required when currentContent is supplied.",
       ),
   }),
   run: async ({
@@ -357,6 +364,7 @@ export default defineAction({
     defaultEase,
     includeContent,
     currentContent: currentContentInput,
+    revision,
   }) => {
     const access = await assertAccess("design", designId, "editor");
 
@@ -378,6 +386,7 @@ export default defineAction({
         filename: schema.designFiles.filename,
         fileType: schema.designFiles.fileType,
         content: schema.designFiles.content,
+        updatedAt: schema.designFiles.updatedAt,
       })
       .from(schema.designFiles)
       .innerJoin(
@@ -398,40 +407,25 @@ export default defineAction({
     const fileId = file.id;
     const resolvedSourceRef = sourceRef ?? fileId;
 
-    // The EDITABLE base for compiling/injecting CSS: prefer the caller's
-    // in-flight editor snapshot when supplied (currentContentInput), else the
-    // LIVE collab-authoritative content for this file (not the raw SQL row —
-    // a live editor's Y.Text may be ahead of the last SQL snapshot). Either
-    // way, `baseVersionHash` is computed from the EXACT string chosen as the
-    // base, at this same point in time, so it faithfully represents "what
-    // this transform's base was" for the persist's optimistic-concurrency
-    // check below — never a fresh re-hash of already-transformed content
-    // (that would trivially match itself and prove nothing raced).
-    let currentContent: string;
-    let baseVersionHash: string;
-    if (currentContentInput !== undefined) {
-      // Caller supplied their own editor snapshot as the patch base. It may
-      // already be stale relative to the live doc — that's fine.
-      // writeInlineSourceFile's own guard (via readLiveSourceFile at write
-      // time) correctly rejects the write if this base no longer matches
-      // live state, exactly as designed for every other caller-supplied-base
-      // action (see apply-component-prop-edit.ts / apply-shader-fill.ts).
-      currentContent = currentContentInput;
-      baseVersionHash = sourceContentHash(currentContent);
-    } else {
-      const workspaceFileForRead: SourceWorkspaceFile = {
+    // Keep the transform working copy separate from the live version it may
+    // replace. A caller snapshot can legitimately contain unsaved local edits
+    // beyond the matching SQL revision; the write CAS must guard the observed
+    // live base, not incorrectly hash those unsaved edits as if already live.
+    const prepared = await prepareInlineSourceEdit({
+      file: {
         id: file.id,
         designId: file.designId,
         filename: file.filename,
         fileType: file.fileType,
         content: file.content,
         createdAt: null,
-        updatedAt: null,
-      };
-      const live = await readLiveSourceFile(workspaceFileForRead);
-      currentContent = live.content;
-      baseVersionHash = live.versionHash;
-    }
+        updatedAt: file.updatedAt,
+      },
+      currentContent: currentContentInput,
+      revision,
+    });
+    const currentContent = prepared.content;
+    const baseVersionHash = prepared.expectedVersionHash;
 
     // ── 2. Compile tracks → CSS ─────────────────────────────────────────────
     const inputTracks = tracks as MotionTrack[];
diff --git a/templates/design/actions/apply-shader-fill.interleave.spec.ts b/templates/design/actions/apply-shader-fill.interleave.spec.ts
index 181a1b9c38..3ea456e559 100644
--- a/templates/design/actions/apply-shader-fill.interleave.spec.ts
+++ b/templates/design/actions/apply-shader-fill.interleave.spec.ts
@@ -271,6 +271,71 @@ describe("apply-shader-fill collab-aware persist (contract-bypass fix)", () => {
     expect(finalLive.content).toContain("background:");
   });
 
+  it("preserves an unsaved caller working copy when its revision still matches the unchanged live base", async () => {
+    const workingCopy = baseDoc().replace(
+      "Caption text",
+      "Caption text (unsaved locally)",
+    );
+
+    const result = await action.run(
+      shaderFillArgs({
+        source: {
+          kind: "design-file",
+          designId: DESIGN_ID,
+          fileId: FILE_ID,
+          currentContent: workingCopy,
+          revision: "2026-07-06T00:00:00.000Z",
+        },
+      }) as never,
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.persisted).toBe(true);
+    const finalLive = await readLiveSourceFile(currentFileRef());
+    expect(finalLive.content).toContain("Caption text (unsaved locally)");
+    expect(finalLive.content).toContain("background:");
+  });
+
+  it("rejects a third live value even when the caller's SQL revision still matches", async () => {
+    const persistedBase = baseDoc();
+    const workingCopy = persistedBase.replace(
+      "Caption text",
+      "Caption text (unsaved locally)",
+    );
+    await (
+      await import("@agent-native/core/collab")
+    ).seedFromText(FILE_ID, persistedBase);
+    const concurrentLive = persistedBase.replace(
+      "Caption text",
+      "Caption text (edited concurrently)",
+    );
+    await applyText(FILE_ID, concurrentLive, "content", "agent");
+    // Deliberately leave SQL at persistedBase with the matching revision. The
+    // live Y.Text is the independent third value that must win the conflict.
+
+    const result = await action.run(
+      shaderFillArgs({
+        source: {
+          kind: "design-file",
+          designId: DESIGN_ID,
+          fileId: FILE_ID,
+          currentContent: workingCopy,
+          revision: "2026-07-06T00:00:00.000Z",
+        },
+      }) as never,
+    );
+
+    expect(result).toMatchObject({
+      ok: false,
+      persisted: false,
+      conflict: true,
+    });
+    const finalLive = await readLiveSourceFile(currentFileRef());
+    expect(finalLive.content).toContain("Caption text (edited concurrently)");
+    expect(finalLive.content).not.toContain("unsaved locally");
+    expect(finalLive.content).not.toContain("background:");
+  });
+
   it("rejects loud (ShaderFillRevisionConflictError shape) instead of silently clobbering when currentContent has gone stale by write time", async () => {
     const staleBase = baseDoc();
 
diff --git a/templates/design/actions/apply-shader-fill.ts b/templates/design/actions/apply-shader-fill.ts
index dc67cc66c3..c68f7eb115 100644
--- a/templates/design/actions/apply-shader-fill.ts
+++ b/templates/design/actions/apply-shader-fill.ts
@@ -38,7 +38,8 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import {
-  readLiveSourceFile,
+  prepareInlineSourceEdit,
+  SourceWorkspaceEditConflictError,
   writeInlineSourceFile,
   type SourceWorkspaceFile,
 } from "../server/source-workspace.js";
@@ -58,7 +59,6 @@ import {
   type ShaderPresetName,
   validateDescriptor,
 } from "../shared/shader-presets.js";
-import { sourceContentHash } from "../shared/source-workspace.js";
 
 // ─── Schema ──────────────────────────────────────────────────────────────────
 
@@ -163,14 +163,10 @@ interface ResolvedDesignFile {
  * editor access. Mirrors `resolveEditableDesignFile` in apply-visual-edit.ts so
  * the shader-fill write goes through the exact same ownership gate.
  *
- * The editable base is collab-aware: `readLiveSourceFile` returns the live
- * Y.Text content when a collab doc exists for this file, else the SQL row —
- * never only the raw SQL snapshot. When the caller supplies
- * `source.currentContent`, that in-flight editor snapshot is preferred as the
- * base instead (same precedence as apply-motion-edit.ts / apply-component-
- * prop-edit.ts), and its versionHash is computed directly from that exact
- * string via `sourceContentHash` — not from a fresh live re-read, which would
- * prove nothing about whether this specific base is still current.
+ * `prepareInlineSourceEdit` keeps the caller's working copy (the transform
+ * base) separate from the live hash it is allowed to replace (the write CAS).
+ * This preserves unsaved local edits based on the matching SQL revision while
+ * still rejecting a third, concurrently-edited live value.
  */
 async function resolveEditableDesignFile(source: {
   designId?: string;
@@ -241,36 +237,27 @@ async function resolveEditableDesignFile(source: {
       "source.revision is required when source.currentContent is provided.",
     );
   }
-  // Legitimate pre-check, distinct from the CAS write-guard below: reject
-  // early when the caller's own revision stamp doesn't match the file's SQL
-  // updatedAt, before any transform work happens.
-  if (
-    source.currentContent !== undefined &&
-    source.revision &&
-    file.updatedAt &&
-    source.revision !== file.updatedAt
-  ) {
-    throw new ShaderFillRevisionConflictError();
-  }
-
-  let content: string;
-  let versionHash: string;
-  if (source.currentContent !== undefined) {
-    content = source.currentContent;
-    versionHash = sourceContentHash(content);
-  } else {
-    const workspaceFile: SourceWorkspaceFile = {
-      id: file.id,
-      designId: file.designId,
-      filename: file.filename,
-      fileType: file.fileType,
-      content: file.content,
-      createdAt: null,
-      updatedAt: file.updatedAt,
-    };
-    const live = await readLiveSourceFile(workspaceFile);
-    content = live.content;
-    versionHash = live.versionHash;
+  const workspaceFile: SourceWorkspaceFile = {
+    id: file.id,
+    designId: file.designId,
+    filename: file.filename,
+    fileType: file.fileType,
+    content: file.content,
+    createdAt: null,
+    updatedAt: file.updatedAt,
+  };
+  let prepared: Awaited<ReturnType<typeof prepareInlineSourceEdit>>;
+  try {
+    prepared = await prepareInlineSourceEdit({
+      file: workspaceFile,
+      currentContent: source.currentContent,
+      revision: source.revision,
+    });
+  } catch (error) {
+    if (error instanceof SourceWorkspaceEditConflictError) {
+      throw new ShaderFillRevisionConflictError();
+    }
+    throw error;
   }
 
   return {
@@ -278,8 +265,8 @@ async function resolveEditableDesignFile(source: {
     designId: file.designId,
     filename: file.filename,
     fileType: file.fileType,
-    content,
-    versionHash,
+    content: prepared.content,
+    versionHash: prepared.expectedVersionHash,
     codeLayerSource: {
       kind: "design-file",
       designId: file.designId,
diff --git a/templates/design/actions/detach-component-instance.spec.ts b/templates/design/actions/detach-component-instance.spec.ts
new file mode 100644
index 0000000000..497fb4d5ad
--- /dev/null
+++ b/templates/design/actions/detach-component-instance.spec.ts
@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+
+import { buildCodeLayerProjection } from "../shared/code-layer.js";
+import { componentNodeIdMatches } from "../shared/component-model.js";
+import action, {
+  stripComponentAnnotations,
+} from "./detach-component-instance.js";
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+describe("detach-component-instance schema", () => {
+  it("accepts the minimal designId + nodeId payload", () => {
+    expect(
+      action.schema.safeParse({ designId: "design_1", nodeId: "node_1" })
+        .success,
+    ).toBe(true);
+  });
+
+  it("accepts an optional fileId and source revision guard", () => {
+    const parsed = action.schema.safeParse({
+      designId: "design_1",
+      nodeId: "node_1",
+      fileId: "file_about",
+      source: { currentContent: "<div></div>", revision: "2024-01-01" },
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("rejects a payload missing nodeId", () => {
+    expect(action.schema.safeParse({ designId: "design_1" }).success).toBe(
+      false,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// stripComponentAnnotations — pure transform
+// ---------------------------------------------------------------------------
+
+function findNode(html: string, nodeId: string) {
+  const projection = buildCodeLayerProjection(html, {
+    source: {
+      kind: "design-file",
+      designId: "d1",
+      fileId: "f1",
+      filename: "index.html",
+    },
+  });
+  const node = projection.nodes.find((n) => componentNodeIdMatches(n, nodeId));
+  if (!node) throw new Error(`test fixture node "${nodeId}" not found`);
+  return node;
+}
+
+describe("stripComponentAnnotations", () => {
+  it("removes the component annotation and prop attributes, preserving everything else", () => {
+    const html =
+      '<main><button data-agent-native-node-id="btn1" data-agent-native-component="PrimaryButton" ' +
+      'data-agent-native-prop-variant="solid" data-agent-native-prop-size="lg" ' +
+      'class="rounded px-4" x-data="{ open: false }">Save</button></main>';
+
+    const node = findNode(html, "btn1");
+    const result = stripComponentAnnotations(html, node.source);
+
+    expect(result.changed).toBe(true);
+    expect(result.removedAttributes).toContain("data-agent-native-component");
+    expect(result.removedAttributes).toContain(
+      "data-agent-native-prop-variant",
+    );
+    expect(result.removedAttributes).toContain("data-agent-native-prop-size");
+
+    expect(result.content).not.toContain("data-agent-native-component");
+    expect(result.content).not.toContain("data-agent-native-prop-");
+    // Preserved: node id, classes, x-data, text content, tag.
+    expect(result.content).toContain('data-agent-native-node-id="btn1"');
+    expect(result.content).toContain('class="rounded px-4"');
+    expect(result.content).toContain('x-data="{ open: false }"');
+    expect(result.content).toContain(">Save</button>");
+  });
+
+  it("is a no-op (changed: false) when the node has no component annotation", () => {
+    const html =
+      '<main><div data-agent-native-node-id="plain1" class="box">Hi</div></main>';
+    const node = findNode(html, "plain1");
+    const result = stripComponentAnnotations(html, node.source);
+    expect(result.changed).toBe(false);
+    expect(result.content).toBe(html);
+    expect(result.removedAttributes).toEqual([]);
+  });
+
+  it("returns unchanged content when the source span is missing", () => {
+    const result = stripComponentAnnotations("<div></div>", null);
+    expect(result).toEqual({
+      content: "<div></div>",
+      changed: false,
+      removedAttributes: [],
+    });
+  });
+
+  it("does not disturb sibling instances of the same component", () => {
+    const html =
+      "<main>" +
+      '<button data-agent-native-node-id="a" data-agent-native-component="Chip" data-agent-native-prop-tone="info">A</button>' +
+      '<button data-agent-native-node-id="b" data-agent-native-component="Chip" data-agent-native-prop-tone="danger">B</button>' +
+      "</main>";
+    const nodeA = findNode(html, "a");
+    const result = stripComponentAnnotations(html, nodeA.source);
+
+    expect(result.changed).toBe(true);
+    // Sibling "b" keeps its annotation and its own prop value untouched.
+    expect(result.content).toContain(
+      'data-agent-native-node-id="b" data-agent-native-component="Chip" data-agent-native-prop-tone="danger"',
+    );
+    // "a" lost its annotation entirely.
+    const aTagMatch = /<button data-agent-native-node-id="a"[^>]*>/.exec(
+      result.content,
+    );
+    expect(aTagMatch?.[0]).not.toContain("data-agent-native-component");
+    expect(aTagMatch?.[0]).not.toContain("data-agent-native-prop-");
+  });
+});
diff --git a/templates/design/actions/detach-component-instance.ts b/templates/design/actions/detach-component-instance.ts
new file mode 100644
index 0000000000..1eb5b70073
--- /dev/null
+++ b/templates/design/actions/detach-component-instance.ts
@@ -0,0 +1,337 @@
+/**
+ * detach-component-instance — Figma's "Detach instance" (⌥⌘B).
+ *
+ * There is no separate component "definition"/template markup anywhere in
+ * this codebase (see `shared/component-model.ts`): a component instance is
+ * just an ordinary element carrying a `data-agent-native-component="Name"`
+ * annotation (plus optional `data-agent-native-prop-*` overrides), and every
+ * instance of the same name is an independently-duplicated copy of HTML —
+ * `component_index` only stores metadata (props/variants/runtime selectors),
+ * never markup. Detaching an instance therefore doesn't need to "inline a
+ * template" the way a real component-instantiation system would: the node's
+ * current rendered markup already IS the fully expanded content. Detach
+ * severs the *component-instance linkage* by stripping the annotation
+ * attributes, so `is-component-instance` checks (`isComponentInstance`,
+ * `index-components`, `get-component-details`) stop recognizing this node —
+ * exactly Figma's "instance becomes a plain layer" semantics — while leaving
+ * position, size, layout, classes, text, and Alpine (`x-data`) behavior
+ * completely untouched.
+ *
+ * Persists through the same deterministic HTML-patch + collab seam as
+ * `apply-component-prop-edit` / `apply-visual-edit` (`writeInlineSourceFile`
+ * with an `expectedVersionHash` CAS guard), so it participates in the
+ * editor's undo/collab machinery exactly like every other HTML-mutating
+ * action — there is no separate undo/history log in this codebase to hook
+ * into (see those actions' docs).
+ *
+ * Inline/Alpine designs only; real-app sources fail closed (same posture as
+ * `apply-component-prop-edit`).
+ */
+
+import { defineAction } from "@agent-native/core/action";
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+import {
+  accessFilter,
+  assertAccess,
+  resolveAccess,
+} from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  writeInlineSourceFile,
+  type SourceWorkspaceFile,
+} from "../server/source-workspace.js";
+import { buildCodeLayerProjection } from "../shared/code-layer.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import { agentSelectionDescriptor } from "../shared/collab-selection.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+  COMPONENT_NAME_ATTR,
+  COMPONENT_PROP_PREFIX,
+} from "../shared/component-model.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+import { sourceContentHash } from "../shared/source-workspace.js";
+
+// ─── Pure transform ────────────────────────────────────────────────────────
+
+/**
+ * Strip the `data-agent-native-component` annotation and every
+ * `data-agent-native-prop-*` override attribute from a node's opening tag,
+ * using its source span. Pure — no DB / IO — so it can be unit tested
+ * directly.
+ *
+ * Leaves everything else (classes, style, text, `x-data`, `id`,
+ * `data-agent-native-node-id`, …) untouched: the node keeps its current
+ * rendered appearance and behavior, it simply stops being recognized as a
+ * component instance.
+ */
+export function stripComponentAnnotations(
+  html: string,
+  source: { openStart: number; openEnd: number } | null | undefined,
+): { content: string; changed: boolean; removedAttributes: string[] } {
+  if (!source) {
+    return { content: html, changed: false, removedAttributes: [] };
+  }
+
+  const openTag = html.slice(source.openStart, source.openEnd);
+  const removed: string[] = [];
+  let newOpenTag = openTag;
+
+  const componentAttrRe = new RegExp(
+    `\\s+${COMPONENT_NAME_ATTR}\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s>"']+)`,
+    "i",
+  );
+  if (componentAttrRe.test(newOpenTag)) {
+    removed.push(COMPONENT_NAME_ATTR);
+    newOpenTag = newOpenTag.replace(componentAttrRe, "");
+  }
+
+  const propAttrRe = new RegExp(
+    `\\s+${COMPONENT_PROP_PREFIX}[a-z0-9-]+\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s>"']+)`,
+    "gi",
+  );
+  newOpenTag = newOpenTag.replace(propAttrRe, (match) => {
+    removed.push(match.trim().split("=")[0] ?? match.trim());
+    return "";
+  });
+
+  if (newOpenTag === openTag) {
+    return { content: html, changed: false, removedAttributes: [] };
+  }
+
+  return {
+    content:
+      html.slice(0, source.openStart) + newOpenTag + html.slice(source.openEnd),
+    changed: true,
+    removedAttributes: removed,
+  };
+}
+
+// ─── Persistence ────────────────────────────────────────────────────────────
+
+async function persistEdit(file: {
+  id: string;
+  designId: string;
+  filename: string;
+  content: string;
+  expectedVersionHash: string;
+}): Promise<string> {
+  await assertAccess("design", file.designId, "editor");
+
+  agentEnterDocument(file.id);
+  try {
+    const workspaceFile: SourceWorkspaceFile = {
+      id: file.id,
+      designId: file.designId,
+      filename: file.filename,
+      fileType: "html",
+      content: file.content,
+      createdAt: null,
+      updatedAt: null,
+    };
+
+    const result = await writeInlineSourceFile({
+      designId: file.designId,
+      file: workspaceFile,
+      content: file.content,
+      expectedVersionHash: file.expectedVersionHash,
+    });
+
+    return result.updatedAt;
+  } finally {
+    agentLeaveDocument(file.id);
+  }
+}
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description:
+    "Detach a component instance (Figma's ⌥⌘B): strip the " +
+    "data-agent-native-component annotation and its data-agent-native-prop-* " +
+    "overrides from the selected instance root so it becomes a plain, " +
+    "unlinked element. Position, size, classes, text, and behavior are " +
+    "unchanged — only the component-instance linkage is removed. " +
+    "Inline/Alpine designs only.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    nodeId: z
+      .string()
+      .describe("data-agent-native-node-id of the component instance root"),
+    fileId: z
+      .string()
+      .optional()
+      .describe("Design file id; defaults to index.html"),
+    source: z
+      .object({
+        currentContent: z
+          .string()
+          .optional()
+          .describe("Latest editor HTML snapshot, when available."),
+        revision: z
+          .string()
+          .optional()
+          .describe(
+            "design_files.updatedAt value the currentContent is based on.",
+          ),
+      })
+      .optional(),
+  }),
+  run: async ({ designId, nodeId, fileId, source }) => {
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    const rawData = (access.resource as { data?: unknown }).data;
+    const sourceType = designSourceTypeFromData(rawData);
+
+    if (sourceType !== "inline") {
+      return {
+        designId,
+        nodeId,
+        sourceType,
+        detached: false,
+        ctaRequired: true,
+        ctaMessage:
+          "Detach instance requires a dedicated consented, version-guarded " +
+          "compiled-source transform for real-app sources. Not yet available.",
+      };
+    }
+
+    await assertAccess("design", designId, "editor");
+    const db = getDb();
+
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+      fileId
+        ? eq(schema.designFiles.id, fileId)
+        : eq(schema.designFiles.filename, "index.html"),
+    ];
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+        updatedAt: schema.designFiles.updatedAt,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(and(...conditions))
+      .limit(1);
+
+    if (!file) throw new Error("Design HTML file not found.");
+
+    if (
+      source?.currentContent &&
+      source.revision &&
+      file.updatedAt &&
+      source.revision !== file.updatedAt
+    ) {
+      return {
+        designId,
+        nodeId,
+        detached: false,
+        conflict: true,
+        fileId: file.id,
+        filename: file.filename,
+        error:
+          "This file changed since this detach was prepared. Refresh the editor and try again.",
+      };
+    }
+
+    const html =
+      typeof source?.currentContent === "string"
+        ? source.currentContent
+        : (file.content ?? "");
+    const baseVersionHash = sourceContentHash(html);
+
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+
+    const projection = buildCodeLayerProjection(html, {
+      source: codeLayerSource,
+    });
+
+    const node = projection.nodes.find((n) =>
+      componentNodeIdMatches(n, nodeId),
+    );
+    if (!node) {
+      throw new Error(
+        `Node "${nodeId}" not found. Run get-code-layer-projection to list current ids.`,
+      );
+    }
+
+    const componentName = componentNameFor(node);
+    if (!componentName) {
+      throw new Error(
+        `Node "${nodeId}" is not a component root (no data-agent-native-component attribute) — nothing to detach.`,
+      );
+    }
+
+    const {
+      content: patchedContent,
+      changed,
+      removedAttributes,
+    } = stripComponentAnnotations(html, node.source);
+
+    if (!changed) {
+      return {
+        designId,
+        nodeId,
+        componentName,
+        detached: false,
+        fileId: file.id,
+        filename: file.filename,
+        note: "No component annotation attributes found on this node's open tag.",
+      };
+    }
+
+    const updatedAt = await persistEdit({
+      id: file.id,
+      designId: file.designId,
+      filename: file.filename,
+      content: patchedContent,
+      expectedVersionHash: baseVersionHash,
+    });
+
+    agentUpdateSelection(file.id, {
+      selection: agentSelectionDescriptor(
+        { nodeId, selector: node.selector },
+        "Detaching instance",
+      ),
+      nodeId,
+      editingFile: file.filename,
+      designId: file.designId,
+    });
+
+    return {
+      designId,
+      nodeId,
+      componentName,
+      detached: true,
+      removedAttributes,
+      fileId: file.id,
+      filename: file.filename,
+      updatedAt,
+      content: patchedContent,
+      note: `Detached from component "${componentName}". This node is now a plain element.`,
+    };
+  },
+});
diff --git a/templates/design/actions/export-design-as-figma-svg.spec.ts b/templates/design/actions/export-design-as-figma-svg.spec.ts
new file mode 100644
index 0000000000..514b7c88c0
--- /dev/null
+++ b/templates/design/actions/export-design-as-figma-svg.spec.ts
@@ -0,0 +1,189 @@
+/**
+ * export-design-as-figma-svg.spec.ts
+ *
+ * Covers the DB-shaped branch logic (missing designId/fileId, file not
+ * found, wrong file type, chromium-unavailable fallback, success shape) with
+ * a mocked drizzle chain and a mocked `renderDesignToFigmaSvg`. The actual
+ * render path (real headless Chromium producing real geometry) requires a
+ * live browser and DB-backed design_files row — not exercised here, same
+ * split as `take-design-screenshot.spec.ts` (see that file's docblock) and
+ * `design-to-figma-svg.spec.ts`.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+const mockRow = {
+  id: "file_1",
+  designId: "design_1",
+  filename: "index.html",
+  fileType: "html",
+  content: "<div>hi</div>",
+};
+
+function chainable(rows: unknown[]) {
+  const chain: Record<string, unknown> = {};
+  chain.select = vi.fn(() => chain);
+  chain.from = vi.fn(() => chain);
+  chain.innerJoin = vi.fn(() => chain);
+  chain.where = vi.fn(() => chain);
+  chain.limit = vi.fn(() => Promise.resolve(rows));
+  return chain;
+}
+
+let fileRows: unknown[] = [mockRow];
+let designRows: unknown[] = [{ title: "My Screen" }];
+
+vi.mock("@agent-native/core/collab", () => ({
+  hasCollabState: vi.fn().mockResolvedValue(false),
+  getText: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/sharing", () => ({
+  accessFilter: () => ({ kind: "access-filter" }),
+  registerShareableResource: vi.fn(),
+}));
+
+vi.mock("../server/db/index.js", () => ({
+  getDb: () => {
+    let call = 0;
+    return {
+      select: vi.fn(() => {
+        call += 1;
+        return call === 1 ? chainable(fileRows) : chainable(designRows);
+      }),
+    };
+  },
+  schema: {
+    designFiles: { id: "id", designId: "designId", filename: "filename" },
+    designs: { id: "id", title: "title" },
+    designShares: {},
+  },
+}));
+
+vi.mock("../server/lib/design-export.js", () => ({
+  trySaveExportFile: vi.fn().mockResolvedValue({ filePath: "/tmp/out.svg" }),
+}));
+
+const renderDesignToFigmaSvg = vi.fn();
+vi.mock("../server/lib/design-to-figma-svg.js", () => ({
+  renderDesignToFigmaSvg: (...args: unknown[]) =>
+    renderDesignToFigmaSvg(...args),
+  safeFigmaSvgFilename: (title?: string | null) =>
+    `${title ?? "design"}-figma-123.svg`,
+}));
+
+vi.mock("../server/lib/playwright-runtime.js", () => ({
+  isMissingBrowserError: (err: unknown) =>
+    /no chromium/i.test(err instanceof Error ? err.message : String(err)),
+}));
+
+import action, {
+  chromiumUnavailableReason,
+} from "./export-design-as-figma-svg.js";
+
+describe("chromiumUnavailableReason", () => {
+  it("names export-svg/export-html as the fallback", () => {
+    const reason = chromiumUnavailableReason(new Error("no chromium binary"));
+    expect(reason).toContain("export-svg");
+    expect(reason).toContain("export-html");
+    expect(reason).toContain("no chromium binary");
+  });
+});
+
+describe("export-design-as-figma-svg schema defaults", () => {
+  it("defaults filename to index.html and embedImages to true", () => {
+    const parsed = action.schema.parse({ designId: "design_1" });
+    expect(parsed.filename).toBe("index.html");
+    expect(parsed.embedImages).toBe(true);
+  });
+});
+
+describe("export-design-as-figma-svg action.run", () => {
+  it("throws when neither designId nor fileId is provided", async () => {
+    await expect(action.run({} as never, {} as never)).rejects.toThrow(
+      /designId or fileId is required/,
+    );
+  });
+
+  it("throws a 404 when no matching design file is found", async () => {
+    fileRows = [];
+    await expect(
+      action.run(
+        { designId: "design_1", filename: "index.html" } as never,
+        {} as never,
+      ),
+    ).rejects.toThrow(/Design file not found/);
+    fileRows = [mockRow];
+  });
+
+  it("rejects a non-HTML file type", async () => {
+    fileRows = [{ ...mockRow, fileType: "css" }];
+    await expect(
+      action.run(
+        { designId: "design_1", filename: "index.html" } as never,
+        {} as never,
+      ),
+    ).rejects.toThrow(/only supports HTML files/);
+    fileRows = [mockRow];
+  });
+
+  it("returns ok:false with a fallback reason when Chromium is unavailable", async () => {
+    renderDesignToFigmaSvg.mockRejectedValueOnce(
+      new Error("no chromium binary"),
+    );
+    const result = (await action.run(
+      { designId: "design_1", filename: "index.html" } as never,
+      {} as never,
+    )) as { ok: boolean; reason?: string };
+    expect(result.ok).toBe(false);
+    expect(result.reason).toContain("export-svg");
+  });
+
+  it("re-throws a non-Chromium render error", async () => {
+    renderDesignToFigmaSvg.mockRejectedValueOnce(new Error("boom"));
+    await expect(
+      action.run(
+        { designId: "design_1", filename: "index.html" } as never,
+        {} as never,
+      ),
+    ).rejects.toThrow(/boom/);
+  });
+
+  it("returns the svg, report, and filename on success", async () => {
+    renderDesignToFigmaSvg.mockResolvedValueOnce({
+      svg: "<svg></svg>",
+      report: {
+        vectorized: ["root"],
+        approximated: [],
+        rasterized: [],
+        omitted: [],
+        warnings: [],
+        vectorizedTextCaveat: "...",
+      },
+    });
+    const result = (await action.run(
+      {
+        designId: "design_1",
+        filename: "index.html",
+        nodeId: "node_1",
+      } as never,
+      {} as never,
+    )) as {
+      ok: boolean;
+      svg: string;
+      filename: string;
+      report: { vectorized: string[] };
+      filePath?: string;
+    };
+    expect(result.ok).toBe(true);
+    expect(result.svg).toBe("<svg></svg>");
+    expect(result.filename).toBe("My Screen-figma-123.svg");
+    expect(result.report.vectorized).toEqual(["root"]);
+    expect(result.filePath).toBe("/tmp/out.svg");
+    expect(renderDesignToFigmaSvg).toHaveBeenCalledWith(
+      expect.objectContaining({
+        rootSelector: '[data-agent-native-node-id="node_1"]',
+      }),
+    );
+  });
+});
diff --git a/templates/design/actions/export-design-as-figma-svg.ts b/templates/design/actions/export-design-as-figma-svg.ts
new file mode 100644
index 0000000000..6c69192060
--- /dev/null
+++ b/templates/design/actions/export-design-as-figma-svg.ts
@@ -0,0 +1,219 @@
+/**
+ * export-design-as-figma-svg — export a design screen (or a selected
+ * subtree) as a genuinely VECTOR SVG document that Figma imports as
+ * editable layers (rect/path/gradients/filters stay editable; `<text>` is
+ * vectorized to outline paths on import — see the returned report's
+ * `vectorizedTextCaveat`). This is a different artifact from `export-svg`,
+ * which wraps the standalone HTML in a `foreignObject` for the editor's own
+ * "Download SVG" parity — Figma cannot import that as vectors at all, it
+ * stays an opaque embedded HTML blob.
+ *
+ * Resolution mirrors `take-design-screenshot.ts`: a single HTML screen
+ * (`fileId`, or `designId` + `filename` defaulting to `index.html`), using
+ * live collab content when the screen is actively being edited. `nodeId`
+ * additionally scopes the export to one selected element's subtree via its
+ * `data-agent-native-node-id` — the same attribute the editor stamps on
+ * selectable layers.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { trySaveExportFile } from "../server/lib/design-export.js";
+import {
+  renderDesignToFigmaSvg,
+  safeFigmaSvgFilename,
+} from "../server/lib/design-to-figma-svg.js";
+import { isMissingBrowserError } from "../server/lib/playwright-runtime.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+
+async function liveContent(
+  fileId: string,
+  storedContent: string,
+): Promise<string> {
+  try {
+    if (await hasCollabState(fileId)) {
+      const live = await getText(fileId, "content");
+      if (typeof live === "string") return live;
+    }
+  } catch {
+    // SQL content is the deterministic fallback.
+  }
+  return storedContent;
+}
+
+/** Model-actionable message when no headless Chromium binary is available. */
+export function chromiumUnavailableReason(err: unknown): string {
+  const detail = err instanceof Error ? err.message : String(err);
+  return (
+    "A headless Chromium browser is not available in this environment, so the " +
+    "vector SVG export cannot run here (this is expected in hosted/serverless " +
+    "deploys, which do not bundle a Chromium binary). Fall back to `export-svg` " +
+    "(a foreignObject-wrapped HTML snapshot — not Figma-importable as vectors, " +
+    "but still a usable static preview) or `export-html`. " +
+    `(${detail})`
+  );
+}
+
+export default defineAction({
+  description:
+    "Export a design screen (or a selected element's subtree via nodeId) as a " +
+    "genuinely vector SVG document — real <rect>/<path>/<text>/<image> markup " +
+    "with <linearGradient>/<radialGradient>/<filter> defs, which Figma imports " +
+    "as normal EDITABLE layers (unlike `export-svg`'s foreignObject wrapper, " +
+    "which Figma cannot import as vectors). Returns the SVG string plus an " +
+    "export report classifying each element as vectorized, approximated, " +
+    "rasterized, or omitted. Note: Figma converts all imported SVG <text> to " +
+    "outlined vector paths on paste/drag-import — geometry stays pixel-exact " +
+    "but the text is no longer live/editable type in Figma; see the report's " +
+    "`vectorizedTextCaveat`.",
+  schema: z.object({
+    designId: z
+      .string()
+      .optional()
+      .describe("Design project id. Required unless fileId is provided."),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Specific design_files.id to export. Takes priority over designId/filename.",
+      ),
+    filename: z
+      .string()
+      .optional()
+      .default("index.html")
+      .describe(
+        "Filename to export when fileId is not provided. Defaults to index.html.",
+      ),
+    nodeId: z
+      .string()
+      .optional()
+      .describe(
+        "Scope the export to one element's subtree via its data-agent-native-node-id, " +
+          "instead of the whole screen.",
+      ),
+    embedImages: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe(
+        "Fetch and inline http(s) image sources/background-images as data: URIs, so the " +
+          "SVG is self-contained for clipboard paste. Set false to keep absolute URLs.",
+      ),
+    width: z.coerce
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Render viewport width in px. Defaults to the screen's natural width or 1440.",
+      ),
+    height: z.coerce
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "Render viewport height in px. Defaults to the screen's natural height or 1200.",
+      ),
+  }),
+  readOnly: true,
+  http: { method: "POST" },
+  run: async ({
+    designId,
+    fileId,
+    filename,
+    nodeId,
+    embedImages,
+    width,
+    height,
+  }) => {
+    if (!designId && !fileId) {
+      throw new Error("designId or fileId is required.");
+    }
+
+    const db = getDb();
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      fileId
+        ? eq(schema.designFiles.id, fileId)
+        : eq(schema.designFiles.designId, designId ?? ""),
+    ];
+    if (!fileId) {
+      conditions.push(
+        eq(schema.designFiles.filename, filename ?? "index.html"),
+      );
+    }
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        fileType: schema.designFiles.fileType,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(and(...conditions))
+      .limit(1);
+
+    if (!file) {
+      const err = new Error("Design file not found") as Error & {
+        statusCode: number;
+      };
+      err.statusCode = 404;
+      throw err;
+    }
+    if (file.fileType !== "html") {
+      throw new Error(
+        `export-design-as-figma-svg only supports HTML files (got "${file.fileType}").`,
+      );
+    }
+
+    const [designRow] = await db
+      .select({ title: schema.designs.title })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, file.designId))
+      .limit(1);
+
+    const html = await liveContent(file.id, file.content ?? "");
+
+    let result: Awaited<ReturnType<typeof renderDesignToFigmaSvg>>;
+    try {
+      result = await renderDesignToFigmaSvg({
+        html,
+        width: width ?? 1440,
+        height: height ?? 1200,
+        title: designRow?.title ?? file.filename,
+        rootSelector: nodeId ? `[data-agent-native-node-id="${nodeId}"]` : null,
+        embedImages: embedImages ?? true,
+      });
+    } catch (err) {
+      if (isMissingBrowserError(err)) {
+        return { ok: false, reason: chromiumUnavailableReason(err) };
+      }
+      throw err;
+    }
+
+    const filenameOut = safeFigmaSvgFilename(designRow?.title ?? file.filename);
+    const saveResult = await trySaveExportFile(filenameOut, result.svg);
+
+    return {
+      ok: true,
+      designId: file.designId,
+      fileId: file.id,
+      filename: filenameOut,
+      svg: result.svg,
+      report: result.report,
+      ...saveResult,
+    };
+  },
+});
diff --git a/templates/design/actions/generate-design.spec.ts b/templates/design/actions/generate-design.spec.ts
index 430693c30f..3954446bbf 100644
--- a/templates/design/actions/generate-design.spec.ts
+++ b/templates/design/actions/generate-design.spec.ts
@@ -303,6 +303,66 @@ describe("generate-design action tool schema", () => {
   });
 });
 
+describe("generate-design: canvasFrames duplicate-target rejection", () => {
+  // mergeCanvasFramePlacements folds two placements for the same target into
+  // one canvasFrames[fileId] value (last one wins), but the mutateDesignData
+  // isApplied check verifies EVERY placedFrames entry against that single
+  // folded value, so the earlier (now-overwritten) entry always mismatches.
+  // Since the mutate callback is deterministic, every retry recomputes the
+  // same mismatch, so the action would always fail with a "concurrent write
+  // conflicts" error after burning through every retry. Reject the malformed
+  // input up front instead.
+  it("rejects two canvasFrames entries targeting the same fileId", () => {
+    const parsed = (action as any).schema.safeParse({
+      designId: "design-1",
+      prompt: "Add a screen",
+      files: [
+        { filename: "index.html", fileType: "html", content: "<html></html>" },
+      ],
+      canvasFrames: JSON.stringify([
+        { fileId: "file-1", x: 0, y: 0, width: 100, height: 100 },
+        { fileId: "file-1", x: 50, y: 50, width: 100, height: 100 },
+      ]),
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it("rejects two canvasFrames entries targeting the same filename", () => {
+    const parsed = (action as any).schema.safeParse({
+      designId: "design-1",
+      prompt: "Add a screen",
+      files: [
+        { filename: "index.html", fileType: "html", content: "<html></html>" },
+      ],
+      canvasFrames: JSON.stringify([
+        { filename: "index.html", x: 0, y: 0, width: 100, height: 100 },
+        { filename: "index.html", x: 50, y: 50, width: 100, height: 100 },
+      ]),
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  it("still accepts distinct canvasFrames targets", () => {
+    const parsed = (action as any).schema.safeParse({
+      designId: "design-1",
+      prompt: "Add screens",
+      files: [
+        { filename: "index.html", fileType: "html", content: "<html></html>" },
+        {
+          filename: "details.html",
+          fileType: "html",
+          content: "<html></html>",
+        },
+      ],
+      canvasFrames: JSON.stringify([
+        { filename: "index.html", x: 0, y: 0, width: 100, height: 100 },
+        { filename: "details.html", x: 200, y: 0, width: 100, height: 100 },
+      ]),
+    });
+    expect(parsed.success).toBe(true);
+  });
+});
+
 describe("generate-design: existing-file update path (hash-guarded write)", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -423,6 +483,112 @@ describe("generate-design: existing-file update path (hash-guarded write)", () =
   });
 });
 
+describe("generate-design: generation-session lock guards concurrent fan-out", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.seededCollabText.clear();
+    mocks.setFileRows([]);
+    mocks.setDesignRows([{ id: "design-1", data: null }]);
+    mocks.assertAccess.mockResolvedValue(undefined);
+    mocks.fileUpdateChain.where.mockResolvedValue(undefined);
+    mocks.designUpdateChain.where.mockResolvedValue(undefined);
+    resetDesignDataMutation();
+  });
+
+  // generate-screens' own tool description recommends fanning out parallel
+  // generate-design calls per returned frame. Both calls read-modify-write
+  // the same design-generation-session:<designId> application-state key with
+  // no CAS/versioning primitive available, so without in-process
+  // serialization, whichever write lands second silently discards the first
+  // call's frame-done update (classic lost-update race). Artificial delays on
+  // the mocked readAppState/writeAppState make the race deterministic: without
+  // the lock, both reads land on the same pre-update session before either
+  // write commits.
+  it("marks both fanned-out frames done instead of losing one to a last-write-wins race", async () => {
+    const sessionStore = new Map<string, Record<string, unknown>>();
+    const key = "design-generation-session:design-1";
+    sessionStore.set(key, {
+      designId: "design-1",
+      status: "generating",
+      prompt: "Build two screens",
+      contextRefs: [],
+      frames: [
+        {
+          frameId: "frame-1",
+          filename: "index.html",
+          agentId: "agent-1",
+          agentName: "Atlas",
+          agentColor: "red",
+          region: { x: 0, y: 0, width: 100, height: 100 },
+          role: "screen",
+          status: "queued",
+          progress: 0,
+        },
+        {
+          frameId: "frame-2",
+          filename: "details.html",
+          agentId: "agent-2",
+          agentName: "Nova",
+          agentColor: "blue",
+          region: { x: 0, y: 0, width: 100, height: 100 },
+          role: "screen",
+          status: "queued",
+          progress: 0,
+        },
+      ],
+      startedAt: "2026-07-09T00:00:00.000Z",
+    });
+
+    mocks.readAppState.mockImplementation(async (k: string) => {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      return sessionStore.get(k) ?? null;
+    });
+    mocks.writeAppState.mockImplementation(
+      async (k: string, value: Record<string, unknown>) => {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        sessionStore.set(k, value);
+      },
+    );
+
+    await Promise.all([
+      action.run({
+        designId: "design-1",
+        prompt: "Build two screens",
+        files: [
+          {
+            filename: "index.html",
+            fileType: "html",
+            content: "<html><body>index</body></html>",
+          },
+        ],
+      }),
+      action.run({
+        designId: "design-1",
+        prompt: "Build two screens",
+        files: [
+          {
+            filename: "details.html",
+            fileType: "html",
+            content: "<html><body>details</body></html>",
+          },
+        ],
+      }),
+    ]);
+
+    const finalSession = sessionStore.get(key) as {
+      status: string;
+      frames: Array<{ filename?: string; status: string }>;
+    };
+    expect(
+      finalSession.frames.find((f) => f.filename === "index.html")?.status,
+    ).toBe("done");
+    expect(
+      finalSession.frames.find((f) => f.filename === "details.html")?.status,
+    ).toBe("done");
+    expect(finalSession.status).toBe("done");
+  });
+});
+
 describe("generate-design: new-file creation path (unchanged)", () => {
   beforeEach(() => {
     vi.clearAllMocks();
diff --git a/templates/design/actions/generate-design.ts b/templates/design/actions/generate-design.ts
index 6e2a581a8b..8015650232 100644
--- a/templates/design/actions/generate-design.ts
+++ b/templates/design/actions/generate-design.ts
@@ -57,23 +57,59 @@ function jsonValuesEqual(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+// Same-process mutex guarding the generation-session read-modify-write below.
+// generate-screens' own tool description explicitly recommends fanning out
+// parallel generate-design calls per returned frame ("fan out calls to
+// generate-design for each returned frame"). Without this lock, two
+// concurrent calls for the same designId both read the same pre-update
+// session, each only marks its own frame done, and whichever writeAppState
+// lands second silently discards the first call's frame-done update —
+// application state has no CAS/versioning primitive (unlike designs.data's
+// mutateDesignData), so a plain read-then-write here is a classic lost-update
+// race. This mirrors the same-process serialization
+// server/lib/design-data-mutation.ts uses (withDesignDataLock) for the
+// designs.data column. Cross-process races remain (no CAS primitive exists
+// for application state), but same-process fan-out from one agent turn is
+// the realistic, explicitly-encouraged case this closes.
+const generationSessionLocks = new Map<string, Promise<unknown>>();
+
+function withGenerationSessionLock<T>(
+  designId: string,
+  callback: () => Promise<T>,
+): Promise<T> {
+  const previous = generationSessionLocks.get(designId) ?? Promise.resolve();
+  const next = previous.then(callback, callback);
+  generationSessionLocks.set(designId, next);
+  const cleanup = () => {
+    if (generationSessionLocks.get(designId) === next) {
+      generationSessionLocks.delete(designId);
+    }
+  };
+  next.then(cleanup, cleanup);
+  return next;
+}
+
 async function updateGenerationSessionForSavedFiles(
   designId: string,
   savedFilenames: string[],
 ) {
-  const key = designGenerationSessionKey(designId);
-  const rawSession = await readAppState(key).catch(() => null);
-  if (!rawSession || typeof rawSession !== "object") return;
-  const session = rawSession as unknown as DesignGenerationSession;
-  if (session.designId !== designId || !Array.isArray(session.frames)) return;
-
-  const nextSession = updateGenerationSessionWithSavedFiles(
-    session,
-    savedFilenames,
-  );
-  if (nextSession === session) return;
+  await withGenerationSessionLock(designId, async () => {
+    const key = designGenerationSessionKey(designId);
+    const rawSession = await readAppState(key).catch(() => null);
+    if (!rawSession || typeof rawSession !== "object") return;
+    const session = rawSession as unknown as DesignGenerationSession;
+    if (session.designId !== designId || !Array.isArray(session.frames)) {
+      return;
+    }
+
+    const nextSession = updateGenerationSessionWithSavedFiles(
+      session,
+      savedFilenames,
+    );
+    if (nextSession === session) return;
 
-  await writeAppState(key, nextSession as unknown as Record<string, unknown>);
+    await writeAppState(key, nextSession as unknown as Record<string, unknown>);
+  });
 }
 
 const generateDesignAgentParameters = {
@@ -228,6 +264,37 @@ const generateDesignAction = defineAction({
                 message: "canvasFrames entries require fileId or filename",
               }),
           )
+          // Reject two placements for the same target in one call. Without
+          // this, mergeCanvasFramePlacements folds both entries into a single
+          // canvasFrames[fileId] value (last one wins), but the mutateDesignData
+          // isApplied check below verifies EVERY placedFrames entry against
+          // that single folded value — so the earlier, now-overwritten entry
+          // always fails the equality check. Since the mutate callback is
+          // deterministic, every retry recomputes the identical mismatch, so
+          // the whole action always fails with a "concurrent write conflicts"
+          // error after burning through all retries, even though nothing else
+          // was actually writing to the design.
+          .superRefine((frames, ctx) => {
+            const seen = new Map<string, number>();
+            frames.forEach((frame, index) => {
+              const key = frame.fileId
+                ? `id:${frame.fileId}`
+                : `name:${frame.filename}`;
+              const firstIndex = seen.get(key);
+              if (firstIndex !== undefined) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index],
+                  message:
+                    `canvasFrames entry ${index} duplicates the target already placed ` +
+                    `at index ${firstIndex} (${frame.fileId ? `fileId ${frame.fileId}` : `filename ${frame.filename}`}). ` +
+                    "Pass exactly one placement per screen.",
+                });
+                return;
+              }
+              seen.set(key, index);
+            });
+          })
           .optional(),
       )
       .optional()
diff --git a/templates/design/actions/generate-screens.spec.ts b/templates/design/actions/generate-screens.spec.ts
index 09cfdbf655..52c73cb37f 100644
--- a/templates/design/actions/generate-screens.spec.ts
+++ b/templates/design/actions/generate-screens.spec.ts
@@ -3,6 +3,7 @@ import { describe, expect, it, vi, beforeEach } from "vitest";
 const mocks = vi.hoisted(() => ({
   writeAppState: vi.fn(),
   assertAccess: vi.fn(),
+  existingDesignFiles: [] as Array<{ filename: string }>,
 }));
 
 vi.mock("@agent-native/core/application-state", () => ({
@@ -14,6 +15,28 @@ vi.mock("@agent-native/core/sharing", () => ({
   registerShareableResource: vi.fn(),
 }));
 
+vi.mock("drizzle-orm", () => ({
+  eq: (left: unknown, right: unknown) => ({ left, right }),
+  sql: (strings: unknown, ...values: unknown[]) => ({ strings, values }),
+}));
+
+vi.mock("../server/db/index.js", () => ({
+  getDb: () => ({
+    select: () => ({
+      from: () => ({
+        where: () => Promise.resolve(mocks.existingDesignFiles),
+      }),
+    }),
+  }),
+  schema: {
+    designFiles: {
+      id: "designFiles.id",
+      designId: "designFiles.designId",
+      filename: "designFiles.filename",
+    },
+  },
+}));
+
 vi.mock("@agent-native/core/server", () => ({
   buildDeepLink: (args: {
     app: string;
@@ -30,6 +53,7 @@ describe("generate-screens", () => {
   beforeEach(() => {
     mocks.writeAppState.mockReset();
     mocks.assertAccess.mockReset();
+    mocks.existingDesignFiles = [];
   });
 
   it("creates an overview generation session and returns placed targets", async () => {
@@ -138,6 +162,48 @@ describe("generate-screens", () => {
     ]);
   });
 
+  // Without checking the design's already-saved files, a requested/slugged
+  // target could silently collide with an existing screen: generate-design's
+  // existing-file lookup is keyed by filename, so the later generate-design
+  // call for a "new" target that happens to match an existing filename would
+  // UPDATE (overwrite) that pre-existing file instead of creating a new one.
+  it("avoids target filenames that already exist in the design", async () => {
+    mocks.existingDesignFiles = [{ filename: "onboarding.html" }];
+
+    const result = await action.run({
+      designId: "design_123",
+      prompt: "Add another onboarding screen",
+      screens: [{ title: "Onboarding" }],
+    });
+
+    expect(result.targets[0]!.filename).toBe("onboarding-2.html");
+  });
+
+  it("avoids an explicit filename that collides with an existing file", async () => {
+    mocks.existingDesignFiles = [{ filename: "index.html" }];
+
+    const result = await action.run({
+      designId: "design_123",
+      prompt: "Add a home screen",
+      screens: [{ title: "Home", filename: "index.html" }],
+    });
+
+    expect(result.targets[0]!.filename).toBe("index-2.html");
+  });
+
+  it("rejects two screens sharing the same explicit frameId", () => {
+    expect(
+      action.schema.safeParse({
+        designId: "design_123",
+        prompt: "Build two screens",
+        screens: [
+          { frameId: "frame-a", title: "Landing" },
+          { frameId: "frame-a", title: "Details" },
+        ],
+      }).success,
+    ).toBe(false);
+  });
+
   it("rejects variants anchored to another variant in the same request", () => {
     expect(
       action.schema.safeParse({
diff --git a/templates/design/actions/generate-screens.ts b/templates/design/actions/generate-screens.ts
index 61dac41d2a..61448e7f0a 100644
--- a/templates/design/actions/generate-screens.ts
+++ b/templates/design/actions/generate-screens.ts
@@ -2,10 +2,11 @@ import { defineAction, embedApp } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
 import { buildDeepLink } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
 
-import "../server/db/index.js";
+import { getDb, schema } from "../server/db/index.js";
 import {
   type AssignedCanvasRegion,
   DEFAULT_ASSIGNED_REGION_GAP,
@@ -186,6 +187,28 @@ export default defineAction({
           .min(1)
           .max(8)
           .superRefine((screens, ctx) => {
+            // Two screens sharing an explicit frameId would produce two
+            // DesignGenerationFrame entries with the same frameId (and thus
+            // the same derived agentId `agent-${frameId}`) once frames get
+            // built below, colliding agent presence/status tracking for both
+            // screens on the overview canvas.
+            const frameIdsSeen = new Map<string, number>();
+            screens.forEach((screen, index) => {
+              if (!screen.frameId) return;
+              const firstIndex = frameIdsSeen.get(screen.frameId);
+              if (firstIndex !== undefined) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index, "frameId"],
+                  message:
+                    `duplicate frameId "${screen.frameId}" (already used at index ${firstIndex}); ` +
+                    "each screen needs a distinct frameId",
+                });
+                return;
+              }
+              frameIdsSeen.set(screen.frameId, index);
+            });
+
             const requestAnchors = new Map<
               string,
               { index: number; role: DesignGenerationFrame["role"] }
@@ -259,21 +282,43 @@ export default defineAction({
           : DEFAULT_ASSIGNED_REGION_MAX_COLUMNS,
     });
 
-    const seenFilenames = new Map<string, number>();
-    // Dedupe any filename (explicit or auto-generated) so two screens can never
-    // resolve to the same target file — otherwise generate-design silently
-    // overwrites the first screen's output with the second's.
+    // Seed the used-filename set with the design's EXISTING files, not just
+    // names requested in this call. Without this, a requested/auto-slugged
+    // target (e.g. a screen titled "Onboarding" slugging to "onboarding.html")
+    // can silently collide with an already-saved screen: generate-design's
+    // existing-file lookup is keyed by filename, so the later generate-design
+    // call for that "new" target would UPDATE (overwrite) the pre-existing
+    // file instead of creating the new screen the agent intended.
+    const db = getDb();
+    const existingFiles = await db
+      .select({ filename: schema.designFiles.filename })
+      .from(schema.designFiles)
+      .where(eq(schema.designFiles.designId, designId));
+    const usedFilenames = new Set(
+      existingFiles
+        .map((file) => file.filename)
+        .filter((filename): filename is string => Boolean(filename)),
+    );
+    // Dedupe any filename (explicit or auto-generated) so two screens can
+    // never resolve to the same target file, and so no target collides with
+    // an existing screen — otherwise generate-design silently overwrites the
+    // other screen's content.
     const dedupeFilename = (base: string): string => {
-      if (!seenFilenames.has(base)) {
-        seenFilenames.set(base, 1);
+      if (!usedFilenames.has(base)) {
+        usedFilenames.add(base);
         return base;
       }
-      const count = seenFilenames.get(base)! + 1;
-      seenFilenames.set(base, count);
       const dot = base.lastIndexOf(".");
-      return dot > 0
-        ? `${base.slice(0, dot)}-${count}${base.slice(dot)}`
-        : `${base}-${count}`;
+      const stem = dot > 0 ? base.slice(0, dot) : base;
+      const ext = dot > 0 ? base.slice(dot) : "";
+      let count = 2;
+      let candidate = `${stem}-${count}${ext}`;
+      while (usedFilenames.has(candidate)) {
+        count += 1;
+        candidate = `${stem}-${count}${ext}`;
+      }
+      usedFilenames.add(candidate);
+      return candidate;
     };
     const requestedTargets = screens.map((screen, index) => {
       if (screen.filename) return dedupeFilename(screen.filename);
diff --git a/templates/design/actions/get-figma-styles.spec.ts b/templates/design/actions/get-figma-styles.spec.ts
new file mode 100644
index 0000000000..492be40daa
--- /dev/null
+++ b/templates/design/actions/get-figma-styles.spec.ts
@@ -0,0 +1,93 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  executeProviderApiRequest: vi.fn(),
+}));
+
+vi.mock("../server/lib/provider-api.js", () => ({
+  executeProviderApiRequest: mocks.executeProviderApiRequest,
+}));
+
+import action from "./get-figma-styles.js";
+
+function jsonEnvelope(json: unknown) {
+  return { response: { ok: true, status: 200, json } };
+}
+
+describe("get-figma-styles", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("summarizes styles by type from a fileUrl", async () => {
+    mocks.executeProviderApiRequest.mockResolvedValue(
+      jsonEnvelope({
+        meta: {
+          styles: [
+            {
+              key: "k1",
+              node_id: "1:1",
+              style_type: "FILL",
+              name: "Brand/Primary",
+              description: "Primary brand color",
+            },
+            {
+              key: "k2",
+              node_id: "1:2",
+              style_type: "TEXT",
+              name: "Heading/H1",
+              description: "",
+            },
+            {
+              key: "k3",
+              node_id: "1:3",
+              style_type: "FILL",
+              name: "Brand/Secondary",
+              description: null,
+            },
+          ],
+        },
+      }),
+    );
+
+    const result = await action.run({
+      fileUrl: "https://www.figma.com/design/abcDEF12345/System",
+    } as any);
+
+    expect(mocks.executeProviderApiRequest).toHaveBeenCalledWith(
+      expect.objectContaining({
+        provider: "figma",
+        method: "GET",
+        path: "/files/abcDEF12345/styles",
+      }),
+    );
+    expect(result.fileKey).toBe("abcDEF12345");
+    expect(result.total).toBe(3);
+    expect(result.byType).toEqual({ FILL: 2, TEXT: 1 });
+    expect(result.styles[0]).toEqual({
+      key: "k1",
+      nodeId: "1:1",
+      styleType: "FILL",
+      name: "Brand/Primary",
+      description: "Primary brand color",
+    });
+    expect(result.guidance).toMatch(/Enterprise Variables API/);
+  });
+
+  it("throws when neither fileUrl nor fileKey resolves to a valid key", async () => {
+    await expect(
+      action.run({ fileUrl: "https://example.com/not-figma" } as any),
+    ).rejects.toThrow(/Could not find a Figma file key/);
+    expect(mocks.executeProviderApiRequest).not.toHaveBeenCalled();
+  });
+
+  it("throws a clear error when the provider request fails", async () => {
+    mocks.executeProviderApiRequest.mockResolvedValue({
+      response: { ok: false, status: 403, statusText: "Forbidden", text: "" },
+    });
+
+    await expect(action.run({ fileKey: "abcDEF12345" } as any)).rejects.toThrow(
+      /Forbidden/,
+    );
+  });
+});
diff --git a/templates/design/actions/get-figma-styles.ts b/templates/design/actions/get-figma-styles.ts
new file mode 100644
index 0000000000..d3769a0c81
--- /dev/null
+++ b/templates/design/actions/get-figma-styles.ts
@@ -0,0 +1,115 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import { executeProviderApiRequest } from "../server/lib/provider-api.js";
+import { parseFigmaFileKey } from "../shared/figma-url.js";
+
+const schemaInput = z
+  .object({
+    fileUrl: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma file URL, for example https://www.figma.com/design/<fileKey>/...",
+      ),
+    fileKey: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Figma file key. Used when fileUrl is omitted."),
+  })
+  .refine((value) => value.fileUrl || value.fileKey, {
+    message: "Pass fileUrl or fileKey.",
+    path: ["fileUrl"],
+  });
+
+type FigmaProviderEnvelope = {
+  response?: {
+    ok?: boolean;
+    status?: number;
+    statusText?: string;
+    json?: unknown;
+    text?: string;
+  };
+};
+
+type FigmaStyleRecord = {
+  key?: unknown;
+  node_id?: unknown;
+  style_type?: unknown;
+  name?: unknown;
+  description?: unknown;
+};
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function providerJson(envelope: unknown, label: string): unknown {
+  const response = (envelope as FigmaProviderEnvelope | null)?.response;
+  if (!response) throw new Error(`Figma ${label} response was empty.`);
+  if (response.ok === false) {
+    const detail =
+      stringValue(response.text) ||
+      response.statusText ||
+      `HTTP ${response.status ?? "error"}`;
+    throw new Error(`Figma ${label} request failed: ${detail}`);
+  }
+  return response.json;
+}
+
+export default defineAction({
+  description:
+    "Summarize a Figma file's published styles (fill/text/effect/grid) by name, description, and node id. This is the file's Styles panel, NOT the Enterprise Variables API — full design-token extraction (including variables/collections) routes through index-design-system-with-builder or import-file --format fig. Requires the saved FIGMA_ACCESS_TOKEN secret.",
+  schema: schemaInput,
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async (args) => {
+    const fileKey =
+      parseFigmaFileKey(args.fileKey) ?? parseFigmaFileKey(args.fileUrl);
+    if (!fileKey) {
+      throw new Error("Could not find a Figma file key in the provided URL.");
+    }
+
+    const envelope = await executeProviderApiRequest({
+      provider: "figma",
+      method: "GET",
+      path: `/files/${fileKey}/styles`,
+      maxBytes: 2 * 1024 * 1024,
+    });
+    const json = providerJson(envelope, "styles") as {
+      meta?: { styles?: unknown };
+    };
+    const records = Array.isArray(json.meta?.styles)
+      ? (json.meta!.styles as FigmaStyleRecord[])
+      : [];
+
+    const styles = records
+      .filter((record) => record && typeof record === "object")
+      .map((record) => ({
+        key: stringValue(record.key),
+        nodeId: stringValue(record.node_id),
+        styleType: stringValue(record.style_type),
+        name: stringValue(record.name) ?? "Untitled style",
+        description: stringValue(record.description),
+      }));
+
+    const byType = styles.reduce<Record<string, number>>((acc, style) => {
+      const type = style.styleType ?? "UNKNOWN";
+      acc[type] = (acc[type] ?? 0) + 1;
+      return acc;
+    }, {});
+
+    return {
+      source: "figma",
+      fileKey,
+      total: styles.length,
+      byType,
+      styles,
+      guidance:
+        "These are the file's published FILL/TEXT/EFFECT/GRID styles (name, description, node id), not the Enterprise Variables API. For full design-system token extraction (variables, collections, modes) use index-design-system-with-builder or import-file --format fig instead of hand-mapping these style records.",
+    };
+  },
+});
diff --git a/templates/design/actions/go-to-main-component.spec.ts b/templates/design/actions/go-to-main-component.spec.ts
new file mode 100644
index 0000000000..809da0794e
--- /dev/null
+++ b/templates/design/actions/go-to-main-component.spec.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+
+import action from "./go-to-main-component.js";
+
+describe("go-to-main-component schema", () => {
+  it("accepts the minimal designId + nodeId payload", () => {
+    expect(
+      action.schema.safeParse({ designId: "design_1", nodeId: "node_1" })
+        .success,
+    ).toBe(true);
+  });
+
+  it("accepts an optional fileId", () => {
+    const parsed = action.schema.safeParse({
+      designId: "design_1",
+      nodeId: "node_1",
+      fileId: "file_about",
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) expect(parsed.data.fileId).toBe("file_about");
+  });
+
+  it("rejects a payload missing nodeId", () => {
+    expect(action.schema.safeParse({ designId: "design_1" }).success).toBe(
+      false,
+    );
+  });
+
+  it("uses the default mutation transport because it writes navigation state", () => {
+    expect(action.readOnly).not.toBe(true);
+    expect(action.http).toBeUndefined();
+  });
+});
diff --git a/templates/design/actions/go-to-main-component.ts b/templates/design/actions/go-to-main-component.ts
new file mode 100644
index 0000000000..74fc18d3be
--- /dev/null
+++ b/templates/design/actions/go-to-main-component.ts
@@ -0,0 +1,254 @@
+/**
+ * go-to-main-component — Figma's "Go to main component".
+ *
+ * DESIGN NOTE — mapping onto this codebase's data model: there is no
+ * persisted "main component" concept anywhere here. A component is just a
+ * name (`data-agent-native-component="Name"`) that happens to be stamped on
+ * more than one element; every instance is an independently-duplicated copy
+ * of HTML (see `shared/component-model.ts`, `component_index` schema — it
+ * stores props/variants/runtime-selectors metadata, never a canonical
+ * definition). A true "main component" would require a data-model addition
+ * (e.g. an `isMain`/definition pointer on `component_index`) — out of scope
+ * here; flagged for a follow-up if promoting a specific instance as
+ * authoritative becomes a real need.
+ *
+ * Closest tractable equivalent: treat the EARLIEST instance of the same
+ * component name — scanning every design file in `createdAt` order, document
+ * order within each file — as the "main" analogue, mirroring the common case
+ * where a component's original occurrence predates its copies. If the given
+ * instance already IS that earliest one, this returns `isMain: true` instead
+ * of navigating (nothing to jump to). Otherwise it writes a `navigate`
+ * app-state command (same mechanism as `navigate` / `open-component-source`)
+ * so the editor selects the target instance, including switching design
+ * files when the main instance lives on a different screen.
+ *
+ * Navigation-only + inline/Alpine designs only (real-app sources return a
+ * CTA). Because this writes the transient `navigate` application-state
+ * command, it is exposed as the default POST mutation rather than a GET.
+ */
+
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { accessFilter, resolveAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import { buildCodeLayerProjection } from "../shared/code-layer.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import {
+  entriesForComponent,
+  scanComponentLibrary,
+} from "../shared/component-library.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+} from "../shared/component-model.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+
+async function liveContent(
+  fileId: string,
+  storedContent: string,
+): Promise<string> {
+  try {
+    if (await hasCollabState(fileId)) {
+      const live = await getText(fileId, "content");
+      if (typeof live === "string") return live;
+    }
+  } catch {
+    // Collab reads are best-effort; SQL content is the fallback.
+  }
+  return storedContent;
+}
+
+export default defineAction({
+  description:
+    "Resolve the 'main' instance of a component (Figma's Go to main " +
+    "component). This codebase has no separate component-definition markup " +
+    "— components are structurally duplicated HTML matched by name — so the " +
+    "earliest instance found across the design's files stands in for the " +
+    "main component. Returns isMain=true when the given instance already IS " +
+    "that earliest one; otherwise navigates the editor to it (which may " +
+    "switch design files).",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    nodeId: z
+      .string()
+      .describe("data-agent-native-node-id of the component instance root"),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Design file id the instance currently lives in; defaults to index.html",
+      ),
+  }),
+  run: async ({ designId, nodeId, fileId }) => {
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    const rawData = (access.resource as { data?: unknown }).data;
+    const sourceType = designSourceTypeFromData(rawData);
+
+    if (sourceType !== "inline") {
+      return {
+        designId,
+        nodeId,
+        sourceType,
+        ctaRequired: true,
+        ctaMessage:
+          "Go to main component requires a connected Builder app for " +
+          "real-app sources. Not yet available.",
+        isMain: false,
+        navigated: false,
+      };
+    }
+
+    const db = getDb();
+
+    // ── Resolve the current node + component name ──────────────────────────
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+      fileId
+        ? eq(schema.designFiles.id, fileId)
+        : eq(schema.designFiles.filename, "index.html"),
+    ];
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(and(...conditions))
+      .limit(1);
+
+    if (!file) throw new Error("Design HTML file not found.");
+
+    const currentHtml = await liveContent(file.id, file.content ?? "");
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+    const currentProjection = buildCodeLayerProjection(currentHtml, {
+      source: codeLayerSource,
+    });
+
+    const node = currentProjection.nodes.find((n) =>
+      componentNodeIdMatches(n, nodeId),
+    );
+    if (!node) {
+      throw new Error(
+        `Node "${nodeId}" not found. Run get-code-layer-projection to list current ids.`,
+      );
+    }
+
+    const componentName = componentNameFor(node);
+    if (!componentName) {
+      throw new Error(
+        `Node "${nodeId}" is not a component root (no data-agent-native-component attribute).`,
+      );
+    }
+
+    // ── Scan every design file for instances of this component ─────────────
+    const allFiles = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designFiles.designId, designId),
+          eq(schema.designFiles.fileType, "html"),
+        ),
+      )
+      .orderBy(schema.designFiles.createdAt);
+
+    // Use the freshest content we already read for the current file so the
+    // instance we just resolved (possibly from a live collab doc) matches up
+    // with `node.id` exactly.
+    const filesForScan = allFiles.map((row) =>
+      row.id === file.id ? { ...row, content: currentHtml } : row,
+    );
+
+    const entries = scanComponentLibrary(filesForScan);
+    const matches = entriesForComponent(entries, componentName);
+
+    if (matches.length === 0) {
+      // Shouldn't happen (the current node itself matches), but guard anyway.
+      throw new Error(
+        `No instances of component "${componentName}" found across the design's files.`,
+      );
+    }
+
+    const main = matches[0];
+    // Compare against the caller's own stable `nodeId` param (a durable
+    // data-agent-native-node-id), not `node.id` (an ephemeral id scoped to
+    // this projection call) — `scanComponentLibrary` resolves the same
+    // durable id for every entry, so this is an apples-to-apples comparison.
+    const isMain = main.fileId === file.id && main.nodeId === nodeId;
+
+    if (isMain) {
+      return {
+        designId,
+        nodeId,
+        componentName,
+        sourceType,
+        ctaRequired: false,
+        isMain: true,
+        instanceCount: matches.length,
+        navigated: false,
+        note:
+          matches.length === 1
+            ? `"${componentName}" has only one instance — this is it.`
+            : `This is the earliest instance of "${componentName}" across the design.`,
+      };
+    }
+
+    await writeAppState("navigate", {
+      view: "editor",
+      designId,
+      editorView: "single",
+      fileId: main.fileId,
+      filename: main.filename,
+      selectedNodeId: main.nodeId,
+      inspectorTab: "design",
+      inspectorSection: "component",
+    });
+
+    return {
+      designId,
+      nodeId,
+      componentName,
+      sourceType,
+      ctaRequired: false,
+      isMain: false,
+      instanceCount: matches.length,
+      main: {
+        fileId: main.fileId,
+        filename: main.filename,
+        nodeId: main.nodeId,
+        selector: main.selector,
+      },
+      navigated: true,
+    };
+  },
+});
diff --git a/templates/design/actions/grant-localhost-write-consent.spec.ts b/templates/design/actions/grant-localhost-write-consent.spec.ts
index 918a847f83..0786511eea 100644
--- a/templates/design/actions/grant-localhost-write-consent.spec.ts
+++ b/templates/design/actions/grant-localhost-write-consent.spec.ts
@@ -8,7 +8,8 @@
  * - It throws when the connection row is missing.
  * - It throws when the connection has no rootPath.
  * - It upserts a grant (insert on first call, update on second).
- * - The returned bridgeToken equals the one stored on the connection.
+ * - The unrestricted bridgeToken is persisted server-side but never returned
+ *   to the browser caller.
  */
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -107,7 +108,7 @@ beforeEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("grant-localhost-write-consent", () => {
-  it("uses bridgeToken from the connection row (not a minted token)", async () => {
+  it("persists the connection bridgeToken without returning it to the browser", async () => {
     mockConnection = {
       id: "conn_1",
       ownerEmail: "user@example.com",
@@ -120,8 +121,8 @@ describe("grant-localhost-write-consent", () => {
       connectionId: "conn_1",
     });
 
-    expect(result.bridgeToken).toBe("bridge_real_token_xyz");
-    // Ensure this is the same value persisted in the grant row.
+    expect(result).not.toHaveProperty("bridgeToken");
+    // The server-side grant still retains the token write-local-file needs.
     expect(insertedValues?.bridgeToken).toBe("bridge_real_token_xyz");
   });
 
@@ -207,7 +208,7 @@ describe("grant-localhost-write-consent", () => {
     expect(result.grantId).toBe("existing_grant_id");
   });
 
-  it("returns rootPath and grantedUntil alongside bridgeToken", async () => {
+  it("returns only non-secret grant metadata", async () => {
     mockConnection = {
       id: "conn_1",
       ownerEmail: "user@example.com",
@@ -223,6 +224,7 @@ describe("grant-localhost-write-consent", () => {
     const after = Date.now();
 
     expect(result.rootPath).toBe("/home/user/my-app");
+    expect(result).not.toHaveProperty("bridgeToken");
     const grantedUntilMs = new Date(result.grantedUntil).getTime();
     const eightHoursMs = 8 * 60 * 60 * 1000;
     expect(grantedUntilMs).toBeGreaterThanOrEqual(before + eightHoursMs);
diff --git a/templates/design/actions/grant-localhost-write-consent.ts b/templates/design/actions/grant-localhost-write-consent.ts
index 461f879ad7..b9b1622f53 100644
--- a/templates/design/actions/grant-localhost-write-consent.ts
+++ b/templates/design/actions/grant-localhost-write-consent.ts
@@ -19,7 +19,7 @@ export default defineAction({
     "for a specific design + localhost connection. The grant scopes writes to the " +
     "connection's rootPath and expires after 8 hours. Requires editor access on the design. " +
     "The LocalhostWriteConsentDialog calls this after the user clicks 'Allow writes'.",
-  // This action mints/returns the real bridgeToken that unlocks the local
+  // This action persists the real bridgeToken that unlocks the local
   // bridge's unrestricted /read-file, /write-file, and /apply-edit. It must
   // only ever be triggered by a human clicking "Allow writes" in
   // LocalhostWriteConsentDialog — never by the agent itself, or an agent
@@ -27,7 +27,9 @@ export default defineAction({
   // human consent model entirely. `agentTool: false` hides it from every
   // agent tool surface (in-app assistant, MCP, A2A) while keeping it
   // callable from the frontend via `callAction` / `useActionMutation` and
-  // the raw `/_agent-native/actions/grant-localhost-write-consent` route.
+  // the raw `/_agent-native/actions/grant-localhost-write-consent` route. The
+  // token intentionally stays server-side: browser callers only need grant
+  // metadata because write-local-file adds bridge authentication itself.
   agentTool: false,
   schema: z.object({
     designId: z.string().describe("Design ID."),
@@ -124,7 +126,6 @@ export default defineAction({
 
     return {
       grantId: existing?.id ?? grantId,
-      bridgeToken,
       rootPath,
       grantedUntil,
     };
diff --git a/templates/design/actions/import-design-source.ts b/templates/design/actions/import-design-source.ts
index a43c8deb8b..70aff8b0e3 100644
--- a/templates/design/actions/import-design-source.ts
+++ b/templates/design/actions/import-design-source.ts
@@ -2,12 +2,12 @@ import { defineAction } from "@agent-native/core";
 import { assertAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
+import { saveFigmaPasteHtmlFallback } from "../server/lib/figma-paste-fallback.js";
 import {
   normalizeImportedHtmlDocument,
   resolveImportDesignId,
   saveImportedDesignFiles,
 } from "../server/lib/import-design-files.js";
-import { parseVisibleClipboardHtml } from "../server/lib/visible-clipboard-html.js";
 
 const MAX_HTML_IMPORT_BYTES = 2 * 1024 * 1024;
 
@@ -62,38 +62,11 @@ export default defineAction({
       };
     }
 
-    const parsed = parseVisibleClipboardHtml(content);
-    if (!parsed.fallbackHtml) {
-      throw new Error(
-        "No visible HTML was found in the clipboard. Copy a frame, then paste into the canvas.",
-      );
-    }
-    const saved = await saveImportedDesignFiles({
+    return saveFigmaPasteHtmlFallback({
       designId: resolvedDesignId,
-      sourceType: "figma-paste-html",
-      files: [
-        {
-          filename: baseFilename(originalName, "figma-paste"),
-          fileType: "html",
-          content: normalizeImportedHtmlDocument(
-            parsed.fallbackHtml,
-            "visible clipboard HTML",
-          ),
-          source: {
-            sourceType: "figma-paste-html",
-          },
-        },
-      ],
+      clipboardHtml: content,
+      originalName,
     });
-    return {
-      ...saved,
-      stats: {
-        sourceKind: "figma-paste",
-        format: "html",
-        frameCount: saved.files.length,
-        imageCount: 0,
-      },
-    };
   },
   link: ({ result }) => {
     if (!result || typeof result !== "object") return null;
diff --git a/templates/design/actions/import-figma-clipboard.spec.ts b/templates/design/actions/import-figma-clipboard.spec.ts
new file mode 100644
index 0000000000..af35d4d7d9
--- /dev/null
+++ b/templates/design/actions/import-figma-clipboard.spec.ts
@@ -0,0 +1,242 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  executeProviderApiRequest: vi.fn(),
+  saveImportedDesignFiles: vi.fn(),
+  resolveImportDesignId: vi.fn(),
+}));
+
+vi.mock("../server/lib/provider-api.js", () => ({
+  executeProviderApiRequest: mocks.executeProviderApiRequest,
+}));
+
+vi.mock("../server/lib/import-design-files.js", () => ({
+  normalizeImportedHtmlDocument: vi.fn(
+    (content: string, label: string) =>
+      `<!doctype html><html><head><!-- ${label} --></head><body>${content}</body></html>`,
+  ),
+  resolveImportDesignId: mocks.resolveImportDesignId,
+  saveImportedDesignFiles: mocks.saveImportedDesignFiles,
+}));
+
+import action from "./import-figma-clipboard.js";
+
+function jsonEnvelope(json: unknown) {
+  return { response: { ok: true, status: 200, json } };
+}
+
+const FILE_KEY = "abcDEF12345";
+
+const CLIPBOARD_HTML_HERO = [
+  '<meta charset="utf-8">',
+  '<span data-metadata="(figmeta)ZmFrZQ==(/figmeta)"></span>',
+  "<div><h1>Hero</h1><p>Welcome aboard</p></div>",
+].join("");
+
+const CLIPBOARD_HTML_UNMATCHED = [
+  '<span data-metadata="(figmeta)ZmFrZQ==(/figmeta)"></span>',
+  "<div><h1>Totally unrelated copy</h1><p>Nothing here matches anything</p></div>",
+].join("");
+
+const HERO_NODE_DOCUMENT = {
+  id: "1:1",
+  name: "Hero",
+  type: "FRAME",
+  absoluteBoundingBox: { x: 0, y: 0, width: 100, height: 50 },
+  fills: [{ type: "SOLID", color: { r: 1, g: 1, b: 1, a: 1 } }],
+  children: [],
+};
+
+function structureWithFrames(
+  frames: Array<{ id: string; name: string; texts?: string[] }>,
+) {
+  return jsonEnvelope({
+    document: {
+      children: [
+        {
+          id: "page-1",
+          children: frames.map((frame) => ({
+            id: frame.id,
+            name: frame.name,
+            children: (frame.texts ?? []).map((characters, index) => ({
+              id: `${frame.id}-text-${index}`,
+              type: "TEXT",
+              characters,
+            })),
+          })),
+        },
+      ],
+    },
+  });
+}
+
+describe("import-figma-clipboard", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.resolveImportDesignId.mockImplementation(
+      async (id?: string) => id ?? "resolved-design-id",
+    );
+    mocks.saveImportedDesignFiles.mockResolvedValue({
+      designId: "design-1",
+      files: [{ id: "file-1", filename: "Hero.html" }],
+      warnings: [],
+      placedFrames: [],
+      overview: true,
+      urlPath: "/design/design-1",
+    });
+  });
+
+  it("imports the exact REST node when its name matches the pasted visible text", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(
+      async ({ path, query }: any) => {
+        if (path === `/files/${FILE_KEY}` && query?.depth === 3) {
+          return structureWithFrames([{ id: "1:1", name: "Hero" }]);
+        }
+        if (path === `/files/${FILE_KEY}/nodes`) {
+          expect(query).toEqual({ ids: "1:1", geometry: "paths" });
+          return jsonEnvelope({
+            nodes: { "1:1": { document: HERO_NODE_DOCUMENT } },
+          });
+        }
+        throw new Error(`Unexpected path ${path}`);
+      },
+    );
+
+    const result = await action.run({
+      figmetaFileKey: FILE_KEY,
+      clipboardHtml: CLIPBOARD_HTML_HERO,
+    } as any);
+
+    expect(result.strategy).toBe("restNodes");
+    expect(result.figma).toEqual({
+      fileKey: FILE_KEY,
+      nodeIds: ["1:1"],
+      matched: [{ id: "1:1", name: "Hero", reason: "name" }],
+    });
+    expect(result.fidelityReport.exactCount).toBeGreaterThan(0);
+    expect(mocks.saveImportedDesignFiles).toHaveBeenCalledTimes(1);
+    const saveArgs = mocks.saveImportedDesignFiles.mock.calls[0]![0];
+    expect(saveArgs.sourceType).toBe("figma-clipboard-rest");
+    expect(saveArgs.files[0].filename).toBe("Hero.html");
+  });
+
+  it("falls back to the HTML preview with a key-missing hint when Figma credentials aren't configured", async () => {
+    mocks.executeProviderApiRequest.mockRejectedValue(
+      new Error("figma credential not configured. Tried: FIGMA_ACCESS_TOKEN"),
+    );
+
+    const result = await action.run({
+      figmetaFileKey: FILE_KEY,
+      clipboardHtml: CLIPBOARD_HTML_HERO,
+    } as any);
+
+    expect(result.strategy).toBe("htmlFallback");
+    expect(result.figmaApiKeyMissing).toBe(true);
+    expect(result.guidance).toMatch(/connect your figma access token/i);
+    expect(mocks.saveImportedDesignFiles).toHaveBeenCalledTimes(1);
+    expect(mocks.saveImportedDesignFiles.mock.calls[0]![0].sourceType).toBe(
+      "figma-paste-html",
+    );
+  });
+
+  it("falls back to the HTML preview and reports ambiguity when two frames match equally", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(
+      async ({ path, query }: any) => {
+        if (path === `/files/${FILE_KEY}` && query?.depth === 3) {
+          return structureWithFrames([
+            { id: "1:1", name: "Frame 1", texts: ["Hero", "Welcome aboard"] },
+            { id: "1:2", name: "Frame 2", texts: ["Hero", "Welcome aboard"] },
+          ]);
+        }
+        throw new Error(`Unexpected path ${path}`);
+      },
+    );
+
+    const result = await action.run({
+      figmetaFileKey: FILE_KEY,
+      clipboardHtml: CLIPBOARD_HTML_HERO,
+    } as any);
+
+    expect(result.strategy).toBe("htmlFallback");
+    expect(result.matchStatus).toBe("ambiguous");
+    expect(result.figmaApiKeyMissing).toBe(false);
+    expect(result.guidance).toMatch(/paste a frame link/i);
+  });
+
+  it("falls back to the HTML preview and reports no match when nothing overlaps", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(
+      async ({ path, query }: any) => {
+        if (path === `/files/${FILE_KEY}` && query?.depth === 3) {
+          return structureWithFrames([{ id: "1:1", name: "Some Other Frame" }]);
+        }
+        throw new Error(`Unexpected path ${path}`);
+      },
+    );
+
+    const result = await action.run({
+      figmetaFileKey: FILE_KEY,
+      clipboardHtml: CLIPBOARD_HTML_UNMATCHED,
+    } as any);
+
+    expect(result.strategy).toBe("htmlFallback");
+    expect(result.matchStatus).toBe("none");
+    expect(result.figmaApiKeyMissing).toBe(false);
+  });
+
+  it("falls back to the HTML preview on a generic (non-credential) REST error", async () => {
+    mocks.executeProviderApiRequest.mockRejectedValue(
+      new Error("Figma file request failed: HTTP 500"),
+    );
+
+    const result = await action.run({
+      figmetaFileKey: FILE_KEY,
+      clipboardHtml: CLIPBOARD_HTML_HERO,
+    } as any);
+
+    expect(result.strategy).toBe("htmlFallback");
+    expect(result.figmaApiKeyMissing).toBe(false);
+    expect(result.matchStatus).toBe("error");
+  });
+
+  it("never imports the exact REST nodes for an ambiguous match, even if the file structure fetch succeeded", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(
+      async ({ path, query }: any) => {
+        if (path === `/files/${FILE_KEY}` && query?.depth === 3) {
+          return structureWithFrames([
+            { id: "1:1", name: "Frame 1", texts: ["Hero", "Welcome aboard"] },
+            { id: "1:2", name: "Frame 2", texts: ["Hero", "Welcome aboard"] },
+          ]);
+        }
+        if (path === `/files/${FILE_KEY}/nodes`) {
+          throw new Error("Should never fetch nodes for an ambiguous match");
+        }
+        throw new Error(`Unexpected path ${path}`);
+      },
+    );
+
+    const result = await action.run({
+      figmetaFileKey: FILE_KEY,
+      clipboardHtml: CLIPBOARD_HTML_HERO,
+    } as any);
+    expect(result.strategy).toBe("htmlFallback");
+  });
+
+  it("throws when the clipboard has no visible HTML at all", async () => {
+    await expect(
+      action.run({
+        figmetaFileKey: FILE_KEY,
+        clipboardHtml:
+          '<span data-metadata="(figmeta)ZmFrZQ==(/figmeta)"></span>',
+      } as any),
+    ).rejects.toThrow(/no visible html/i);
+  });
+
+  it("throws for an invalid figmeta file key", async () => {
+    await expect(
+      action.run({
+        figmetaFileKey: "x",
+        clipboardHtml: CLIPBOARD_HTML_HERO,
+      } as any),
+    ).rejects.toThrow(/could not be parsed/i);
+  });
+});
diff --git a/templates/design/actions/import-figma-clipboard.ts b/templates/design/actions/import-figma-clipboard.ts
new file mode 100644
index 0000000000..155a585188
--- /dev/null
+++ b/templates/design/actions/import-figma-clipboard.ts
@@ -0,0 +1,134 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  buildFigmaNodeCandidates,
+  extractVisibleTexts,
+  matchFigmaClipboardNodes,
+} from "../server/lib/figma-clipboard-match.js";
+import {
+  buildScreenFilesFromFigmaNodes,
+  fetchFileStructure,
+  fetchFigmaNodes,
+  summarizeFidelity,
+} from "../server/lib/figma-node-import.js";
+import { saveFigmaPasteHtmlFallback } from "../server/lib/figma-paste-fallback.js";
+import { saveImportedDesignFiles } from "../server/lib/import-design-files.js";
+import { parseVisibleClipboardHtml } from "../server/lib/visible-clipboard-html.js";
+import { parseFigmaFileKey } from "../shared/figma-url.js";
+
+const NODE_STRUCTURE_DEPTH = 3;
+
+const CREDENTIAL_MISSING_RE = /credential not configured/i;
+
+const AMBIGUOUS_GUIDANCE =
+  'Couldn\'t confidently match this paste to specific Figma nodes, so nothing was imported from the API. Paste a frame LINK instead (copy the frame in Figma, then "Copy link to selection") for an exact node import — or continue with the clipboard preview below.';
+
+const KEY_MISSING_GUIDANCE =
+  "Connect your Figma access token (Settings > Secrets > Figma access token) to import this paste as exact, editable Figma nodes. Imported from the clipboard preview instead.";
+
+export default defineAction({
+  description:
+    "Import a plain clipboard paste copied from Figma (Cmd+C in Figma, Cmd+V here). Figma's clipboard marker only carries a file key, not node ids, so this heuristically matches the pasted content against the file's top-level frames by name/text and imports exact REST nodes only on a confident match; otherwise it falls back to the lossy visible-HTML preview and reports why. For a guaranteed exact import, use import-figma-frame with a copied frame LINK (which does carry a node id) instead.",
+  schema: z.object({
+    designId: z
+      .string()
+      .optional()
+      .describe("Design id. Defaults to the active editor navigation state."),
+    figmetaFileKey: z
+      .string()
+      .trim()
+      .min(1)
+      .describe(
+        "The fileKey decoded from the clipboard's figmeta marker (see app/lib/figma-clipboard.ts's extractFigmeta).",
+      ),
+    clipboardHtml: z
+      .string()
+      .describe(
+        "The raw clipboard HTML (still containing the hidden figmeta/figbuffer markers) — used both for the legacy visible-HTML fallback and for node-matching against visible text.",
+      ),
+    originalName: z.string().optional(),
+  }),
+  run: async ({ designId, figmetaFileKey, clipboardHtml, originalName }) => {
+    const fileKey = parseFigmaFileKey(figmetaFileKey);
+    if (!fileKey) {
+      throw new Error("The clipboard's Figma file key could not be parsed.");
+    }
+
+    // Legacy fallback text is needed either way: as the actual save payload
+    // when we fall back, and as the "visible text" signal the matcher scores
+    // candidate frames against.
+    const parsedClipboard = parseVisibleClipboardHtml(clipboardHtml);
+    if (!parsedClipboard.fallbackHtml) {
+      throw new Error(
+        "No visible HTML was found in the clipboard. Copy a frame, then paste into the canvas.",
+      );
+    }
+    const clipboardTexts = extractVisibleTexts(parsedClipboard.fallbackHtml);
+
+    let figmaApiKeyMissing = false;
+    let matchStatus: "matched" | "ambiguous" | "none" | "error" = "error";
+
+    try {
+      const document = await fetchFileStructure(fileKey, NODE_STRUCTURE_DEPTH);
+      const candidates = buildFigmaNodeCandidates(document);
+      const matchResult = matchFigmaClipboardNodes(candidates, clipboardTexts);
+      matchStatus = matchResult.status;
+
+      if (matchResult.status === "matched") {
+        const nodeIds = matchResult.matches.map((match) => match.id);
+        const nodesById = await fetchFigmaNodes(fileKey, nodeIds);
+        const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
+          fileKey,
+          nodesById,
+        );
+        const saved = await saveImportedDesignFiles({
+          designId,
+          sourceType: "figma-clipboard-rest",
+          files,
+        });
+        return {
+          ...saved,
+          strategy: "restNodes" as const,
+          figma: {
+            fileKey,
+            nodeIds,
+            matched: matchResult.matches,
+          },
+          fidelityReport: summarizeFidelity(fidelityEntries),
+          guidance:
+            "Review fidelityReport.imageFallbacks for subtrees rendered as PNG and fidelityReport.approximated for properties CSS cannot express exactly.",
+        };
+      }
+    } catch (error) {
+      figmaApiKeyMissing = CREDENTIAL_MISSING_RE.test(
+        error instanceof Error ? error.message : String(error),
+      );
+      if (!figmaApiKeyMissing) {
+        // A real (non-credential) REST failure — network error, revoked
+        // token, file access issue, etc. Still fall back to the honest
+        // clipboard preview rather than losing the paste entirely, but this
+        // isn't a "no confident match" case, so don't claim ambiguity.
+        matchStatus = "error";
+      }
+    }
+
+    const saved = await saveFigmaPasteHtmlFallback({
+      designId,
+      clipboardHtml,
+      originalName,
+    });
+    return {
+      ...saved,
+      strategy: "htmlFallback" as const,
+      figmaApiKeyMissing,
+      matchStatus,
+      figma: { fileKey },
+      guidance: figmaApiKeyMissing
+        ? KEY_MISSING_GUIDANCE
+        : matchStatus === "ambiguous" || matchStatus === "none"
+          ? AMBIGUOUS_GUIDANCE
+          : "Imported the clipboard's visible-HTML preview after a Figma API error. Paste a frame link for an exact import.",
+    };
+  },
+});
diff --git a/templates/design/actions/import-figma-frame.spec.ts b/templates/design/actions/import-figma-frame.spec.ts
new file mode 100644
index 0000000000..bdc99aa242
--- /dev/null
+++ b/templates/design/actions/import-figma-frame.spec.ts
@@ -0,0 +1,216 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  executeProviderApiRequest: vi.fn(),
+  saveImportedDesignFiles: vi.fn(),
+}));
+
+vi.mock("../server/lib/provider-api.js", () => ({
+  executeProviderApiRequest: mocks.executeProviderApiRequest,
+}));
+
+vi.mock("../server/lib/import-design-files.js", () => ({
+  normalizeImportedHtmlDocument: vi.fn(
+    (content: string, label: string) =>
+      `<!doctype html><html><head><!-- ${label} --></head><body>${content}</body></html>`,
+  ),
+  saveImportedDesignFiles: mocks.saveImportedDesignFiles,
+}));
+
+import action from "./import-figma-frame.js";
+
+function jsonEnvelope(json: unknown) {
+  return { response: { ok: true, status: 200, json } };
+}
+
+function errorEnvelope(status: number, text: string) {
+  return { response: { ok: false, status, statusText: "Error", text } };
+}
+
+const SIMPLE_FRAME = {
+  document: {
+    id: "1:2",
+    name: "Hero",
+    type: "FRAME",
+    absoluteBoundingBox: { x: 0, y: 0, width: 200, height: 100 },
+    fills: [{ type: "SOLID", color: { r: 1, g: 1, b: 1, a: 1 } }],
+    children: [],
+  },
+};
+
+describe("import-figma-frame", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.saveImportedDesignFiles.mockResolvedValue({
+      designId: "design-1",
+      files: [{ id: "file-1", filename: "Hero.html" }],
+      warnings: [],
+      placedFrames: [],
+      overview: true,
+      urlPath: "/design/design-1",
+    });
+  });
+
+  it("imports a frame from a figmaUrl with an explicit node-id", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(
+      async ({ path, query }: any) => {
+        expect(path).toBe("/files/abcDEF12345/nodes");
+        expect(query).toEqual({ ids: "1:2", geometry: "paths" });
+        return jsonEnvelope({ nodes: { "1:2": SIMPLE_FRAME } });
+      },
+    );
+
+    const result = await action.run({
+      figmaUrl: "https://www.figma.com/design/abcDEF12345/App?node-id=1-2",
+      asNewScreen: true,
+    } as any);
+
+    expect(result.figma).toEqual({
+      fileKey: "abcDEF12345",
+      nodeId: "1:2",
+      nodeName: "Hero",
+    });
+    expect(mocks.saveImportedDesignFiles).toHaveBeenCalledTimes(1);
+    const saveArgs = mocks.saveImportedDesignFiles.mock.calls[0]![0];
+    expect(saveArgs.sourceType).toBe("figma-import");
+    expect(saveArgs.files[0].filename).toBe("Hero.html");
+    expect(saveArgs.files[0].content).toContain(
+      "background-color: rgba(255, 255, 255, 1)",
+    );
+    expect(saveArgs.files[0].preferredFrame).toEqual({
+      title: "Hero",
+      width: 200,
+      height: 100,
+    });
+    expect(result.fidelityReport.exactCount).toBeGreaterThan(0);
+  });
+
+  it("resolves /branch/:branchKey/ to the branch key for the nodes request", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(
+      async ({ path }: any) => {
+        if (path === "/files/branchKey456/nodes") {
+          return jsonEnvelope({ nodes: { "1:2": SIMPLE_FRAME } });
+        }
+        throw new Error(`Unexpected path ${path}`);
+      },
+    );
+
+    await action.run({
+      figmaUrl:
+        "https://www.figma.com/design/parentKey123/App/branch/branchKey456/App-Branch?node-id=1-2",
+    } as any);
+
+    expect(mocks.executeProviderApiRequest).toHaveBeenCalledWith(
+      expect.objectContaining({ path: "/files/branchKey456/nodes" }),
+    );
+  });
+
+  it("falls back to the first top-level frame when no node-id is given", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(
+      async ({ path, query }: any) => {
+        if (path === "/files/abcDEF12345" && query?.depth === 2) {
+          return jsonEnvelope({
+            document: {
+              children: [
+                {
+                  id: "page-1",
+                  children: [{ id: "9:9", name: "First Frame" }],
+                },
+              ],
+            },
+          });
+        }
+        if (path === "/files/abcDEF12345/nodes") {
+          expect(query).toEqual({ ids: "9:9", geometry: "paths" });
+          return jsonEnvelope({
+            nodes: {
+              "9:9": { document: { ...SIMPLE_FRAME.document, id: "9:9" } },
+            },
+          });
+        }
+        throw new Error(`Unexpected path ${path}`);
+      },
+    );
+
+    const result = await action.run({ fileKey: "abcDEF12345" } as any);
+    expect(result.figma.nodeId).toBe("9:9");
+  });
+
+  it("throws a clear error when the requested node is not found", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(async () =>
+      jsonEnvelope({ nodes: {} }),
+    );
+
+    await expect(
+      action.run({ fileKey: "abcDEF12345", nodeId: "1:2" } as any),
+    ).rejects.toThrow(/not found/);
+  });
+
+  it("throws when the provider request fails", async () => {
+    mocks.executeProviderApiRequest.mockImplementation(async () =>
+      errorEnvelope(401, "Invalid token"),
+    );
+
+    await expect(
+      action.run({ fileKey: "abcDEF12345", nodeId: "1:2" } as any),
+    ).rejects.toThrow(/Invalid token/);
+  });
+
+  it("rejects asNewScreen: false as not yet supported", async () => {
+    await expect(
+      action.run({
+        fileKey: "abcDEF12345",
+        nodeId: "1:2",
+        asNewScreen: false,
+      } as any),
+    ).rejects.toThrow(/not supported yet/);
+    expect(mocks.executeProviderApiRequest).not.toHaveBeenCalled();
+  });
+
+  it("fetches PNG fallbacks for unsupported node types and reports them", async () => {
+    const frameWithVector = {
+      document: {
+        id: "1:2",
+        name: "Hero",
+        type: "FRAME",
+        absoluteBoundingBox: { x: 0, y: 0, width: 200, height: 100 },
+        children: [
+          {
+            id: "1:3",
+            name: "Icon",
+            type: "VECTOR",
+            absoluteBoundingBox: { x: 10, y: 10, width: 24, height: 24 },
+          },
+        ],
+      },
+    };
+    mocks.executeProviderApiRequest.mockImplementation(
+      async ({ path, query }: any) => {
+        if (path === "/files/abcDEF12345/nodes") {
+          return jsonEnvelope({ nodes: { "1:2": frameWithVector } });
+        }
+        if (path === "/images/abcDEF12345") {
+          expect(query).toEqual({ ids: "1:3", format: "png", scale: 2 });
+          return jsonEnvelope({
+            images: { "1:3": "https://figma-renders.example.com/1-3.png" },
+          });
+        }
+        if (path === "/files/abcDEF12345/images") {
+          return jsonEnvelope({ images: {} });
+        }
+        throw new Error(`Unexpected path ${path}`);
+      },
+    );
+
+    const result = await action.run({
+      fileKey: "abcDEF12345",
+      nodeId: "1:2",
+    } as any);
+    expect(result.fidelityReport.imageFallbacks).toHaveLength(1);
+    expect(result.fidelityReport.imageFallbacks[0].nodeId).toBe("1:3");
+    const saveArgs = mocks.saveImportedDesignFiles.mock.calls[0]![0];
+    expect(saveArgs.files[0].content).toContain(
+      "https://figma-renders.example.com/1-3.png",
+    );
+  });
+});
diff --git a/templates/design/actions/import-figma-frame.ts b/templates/design/actions/import-figma-frame.ts
new file mode 100644
index 0000000000..3bd4fb4fb4
--- /dev/null
+++ b/templates/design/actions/import-figma-frame.ts
@@ -0,0 +1,95 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  buildScreenFilesFromFigmaNodes,
+  fetchFigmaNode,
+  resolveTargetNodeId,
+  summarizeFidelity,
+} from "../server/lib/figma-node-import.js";
+import { saveImportedDesignFiles } from "../server/lib/import-design-files.js";
+import { parseFigmaFileKey, parseFigmaNodeId } from "../shared/figma-url.js";
+
+const schemaInput = z
+  .object({
+    figmaUrl: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma file/frame URL, e.g. https://www.figma.com/design/<fileKey>/<name>?node-id=<id>. A branch URL (/branch/<key>/) resolves to the branch's own file.",
+      ),
+    fileKey: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Figma file key. Used when figmaUrl is omitted or has no key."),
+    nodeId: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Figma node id (colon or dash form, e.g. '12:34' or '12-34'). Used when figmaUrl has no node-id. Defaults to the file's first top-level frame when omitted.",
+      ),
+    designId: z
+      .string()
+      .optional()
+      .describe("Design id. Defaults to the active editor navigation state."),
+    asNewScreen: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Must be true today: the imported frame is always saved as a new screen. Reserved for a future 'replace existing screen' mode.",
+      ),
+  })
+  .refine((value) => value.figmaUrl || value.fileKey, {
+    message: "Pass figmaUrl or fileKey.",
+    path: ["figmaUrl"],
+  });
+
+export default defineAction({
+  description:
+    "Import a Figma frame/component by URL or file key + node id, mapping it to pixel-accurate HTML (position, auto-layout as flexbox, text, fills/gradients, strokes, corner radii, effects) and saving it as a new Design screen. Unsupported node types (vector networks, boolean ops) render as exact PNG fallbacks instead of approximated shapes. Returns a fidelity report of which properties were exact, approximated, or image-fallback. Requires the saved FIGMA_ACCESS_TOKEN secret.",
+  schema: schemaInput,
+  publicAgent: { expose: true, readOnly: false, requiresAuth: true },
+  run: async (args) => {
+    if (args.asNewScreen === false) {
+      throw new Error(
+        "asNewScreen: false is not supported yet. Omit it or pass true — the imported frame is always saved as a new screen.",
+      );
+    }
+
+    const fileKey =
+      parseFigmaFileKey(args.fileKey) ?? parseFigmaFileKey(args.figmaUrl);
+    if (!fileKey) {
+      throw new Error("Could not find a Figma file key in the provided URL.");
+    }
+    const requestedNodeId =
+      parseFigmaNodeId(args.nodeId) ?? parseFigmaNodeId(args.figmaUrl);
+
+    const nodeId = await resolveTargetNodeId(fileKey, requestedNodeId);
+    const rootNode = await fetchFigmaNode(fileKey, nodeId);
+
+    const { files, fidelityEntries } = await buildScreenFilesFromFigmaNodes(
+      fileKey,
+      { [nodeId]: rootNode },
+      {
+        source: () => ({ figmaUrl: args.figmaUrl ?? null }),
+      },
+    );
+
+    const saved = await saveImportedDesignFiles({
+      designId: args.designId,
+      sourceType: "figma-import",
+      files,
+    });
+
+    return {
+      ...saved,
+      figma: { fileKey, nodeId, nodeName: rootNode.name ?? null },
+      fidelityReport: summarizeFidelity(fidelityEntries),
+      guidance:
+        "Review fidelityReport.imageFallbacks for subtrees rendered as PNG (vector networks, boolean ops, unsupported node types) and fidelityReport.approximated for properties CSS cannot express exactly (rotation, per-side strokes, radial/angular/diamond gradients, blur radius scale).",
+    };
+  },
+});
diff --git a/templates/design/actions/index-design-system-with-builder.ts b/templates/design/actions/index-design-system-with-builder.ts
index bf6eb3b47a..1541b3131c 100644
--- a/templates/design/actions/index-design-system-with-builder.ts
+++ b/templates/design/actions/index-design-system-with-builder.ts
@@ -13,8 +13,23 @@ import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-sys
 
 const codeFileSchema = z.object({
   filename: z.string().trim().min(1).describe("File name or relative path"),
-  content: z.string().describe("Raw text content of the code/design file"),
+  content: z
+    .string()
+    .describe(
+      "File content. Text files (code, CSS, markdown, JSON, SVG): raw text. " +
+        "Binary files -- most importantly `.fig` (a zip/kiwi binary container, " +
+        'never valid text) -- MUST be base64-encoded with encoding: "base64"; ' +
+        "sending raw/binary-as-string content with the default utf8 encoding " +
+        "corrupts the file before it reaches Builder.",
+    ),
   mimeType: z.string().trim().optional().describe("Optional MIME type"),
+  encoding: z
+    .enum(["utf8", "base64"])
+    .optional()
+    .describe(
+      "Encoding of `content`. Defaults to utf8. Set to base64 for `.fig` and " +
+        "other binary files.",
+    ),
 });
 
 export default defineAction({
diff --git a/templates/design/actions/list-design-components.spec.ts b/templates/design/actions/list-design-components.spec.ts
new file mode 100644
index 0000000000..c0d989a90c
--- /dev/null
+++ b/templates/design/actions/list-design-components.spec.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+
+import action from "./list-design-components.js";
+
+describe("list-design-components schema", () => {
+  it("accepts the minimal designId payload", () => {
+    expect(action.schema.safeParse({ designId: "design_1" }).success).toBe(
+      true,
+    );
+  });
+
+  it("accepts an optional excludeName", () => {
+    const parsed = action.schema.safeParse({
+      designId: "design_1",
+      excludeName: "PrimaryButton",
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) expect(parsed.data.excludeName).toBe("PrimaryButton");
+  });
+
+  it("rejects a payload missing designId", () => {
+    expect(action.schema.safeParse({}).success).toBe(false);
+  });
+
+  it("is read-only over GET", () => {
+    expect(action.readOnly).toBe(true);
+    expect(action.http).toMatchObject({ method: "GET" });
+  });
+});
diff --git a/templates/design/actions/list-design-components.ts b/templates/design/actions/list-design-components.ts
new file mode 100644
index 0000000000..d3f3a1e9a1
--- /dev/null
+++ b/templates/design/actions/list-design-components.ts
@@ -0,0 +1,104 @@
+/**
+ * list-design-components — read action.
+ *
+ * Scans every HTML file in a design for `data-agent-native-component`
+ * annotations and returns one summary row per distinct component name
+ * (instance count + a representative instance to preview/source from).
+ *
+ * Unlike `index-components` (which only scans one file at a time and persists
+ * metadata into `component_index`), this action is a lightweight, read-only,
+ * cross-file scan purpose-built for the Swap Instance component picker — the
+ * caller needs to know every component name that exists ANYWHERE in the
+ * design, not just on the active screen.
+ *
+ * Inline/Alpine designs only; real-app sources return an empty list with a
+ * CTA (matches `index-components`' real-app posture).
+ */
+
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter, resolveAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  scanComponentLibrary,
+  summarizeComponentLibrary,
+} from "../shared/component-library.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+
+export default defineAction({
+  description:
+    "List every distinct component (by data-agent-native-component name) " +
+    "found across ALL html files in a design, with instance counts, for the " +
+    "Swap Instance component picker. Inline/Alpine designs only.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    excludeName: z
+      .string()
+      .optional()
+      .describe(
+        "Component name to omit from the results, e.g. the currently " +
+          "selected instance's own component so it isn't offered as a swap target.",
+      ),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId, excludeName }) => {
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    const rawData = (access.resource as { data?: unknown }).data;
+    const sourceType = designSourceTypeFromData(rawData);
+
+    if (sourceType !== "inline") {
+      return {
+        designId,
+        sourceType,
+        ctaRequired: true,
+        ctaMessage:
+          "Listing components across the design library requires a " +
+          "connected Builder app for real-app sources. Not yet available.",
+        components: [],
+        totalComponents: 0,
+      };
+    }
+
+    const db = getDb();
+
+    const files = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designFiles.designId, designId),
+          eq(schema.designFiles.fileType, "html"),
+        ),
+      )
+      .orderBy(schema.designFiles.createdAt);
+
+    const entries = scanComponentLibrary(files);
+    const components = summarizeComponentLibrary(entries).filter(
+      (component) => component.name !== excludeName,
+    );
+
+    return {
+      designId,
+      sourceType,
+      ctaRequired: false,
+      components,
+      totalComponents: components.length,
+    };
+  },
+});
diff --git a/templates/design/actions/list-figma-library-assets.spec.ts b/templates/design/actions/list-figma-library-assets.spec.ts
deleted file mode 100644
index 680a7db3ef..0000000000
--- a/templates/design/actions/list-figma-library-assets.spec.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { parseFigmaFileKey } from "./list-figma-library-assets";
-
-describe("parseFigmaFileKey", () => {
-  it("accepts a raw Figma file key", () => {
-    expect(parseFigmaFileKey("abcDEF_12345")).toBe("abcDEF_12345");
-  });
-
-  it("extracts design, file, and proto URL keys", () => {
-    expect(
-      parseFigmaFileKey("https://www.figma.com/design/abcDEF12345/App"),
-    ).toBe("abcDEF12345");
-    expect(
-      parseFigmaFileKey("https://www.figma.com/file/xyz98765432/System"),
-    ).toBe("xyz98765432");
-    expect(
-      parseFigmaFileKey("https://www.figma.com/proto/protoKey123/Flow"),
-    ).toBe("protoKey123");
-  });
-
-  it("returns null for invalid input", () => {
-    expect(parseFigmaFileKey("https://example.com/nope")).toBeNull();
-    expect(parseFigmaFileKey("")).toBeNull();
-  });
-});
diff --git a/templates/design/actions/list-figma-library-assets.ts b/templates/design/actions/list-figma-library-assets.ts
index cb8661b505..1e34138c97 100644
--- a/templates/design/actions/list-figma-library-assets.ts
+++ b/templates/design/actions/list-figma-library-assets.ts
@@ -2,8 +2,7 @@ import { defineAction } from "@agent-native/core";
 import { z } from "zod";
 
 import { executeProviderApiRequest } from "../server/lib/provider-api.js";
-
-const FIGMA_FILE_KEY_RE = /^[A-Za-z0-9_-]{8,}$/;
+import { parseFigmaFileKey } from "../shared/figma-url.js";
 
 const FigmaRenderFormatSchema = z.enum(["svg", "png"]).default("svg");
 
@@ -79,28 +78,6 @@ function numberOrDefault(value: number | undefined, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 
-export function parseFigmaFileKey(input: string | undefined): string | null {
-  const value = input?.trim();
-  if (!value) return null;
-  if (FIGMA_FILE_KEY_RE.test(value)) return value;
-
-  try {
-    const url = new URL(value);
-    const parts = url.pathname.split("/").filter(Boolean);
-    for (const segment of ["design", "file", "proto"]) {
-      const index = parts.indexOf(segment);
-      if (index >= 0) {
-        const candidate = parts[index + 1];
-        if (candidate && FIGMA_FILE_KEY_RE.test(candidate)) return candidate;
-      }
-    }
-  } catch {
-    return null;
-  }
-
-  return null;
-}
-
 function figmaNodeUrl(
   fileKey: string,
   nodeId: string,
diff --git a/templates/design/actions/open-component-source.spec.ts b/templates/design/actions/open-component-source.spec.ts
new file mode 100644
index 0000000000..18e673226e
--- /dev/null
+++ b/templates/design/actions/open-component-source.spec.ts
@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+
+import action from "./open-component-source.js";
+
+describe("open-component-source transport", () => {
+  it("uses the default mutation transport because it writes navigation state", () => {
+    expect(action.readOnly).not.toBe(true);
+    expect(action.http).toBeUndefined();
+  });
+});
diff --git a/templates/design/actions/open-component-source.ts b/templates/design/actions/open-component-source.ts
index fb58012775..52da0c8090 100644
--- a/templates/design/actions/open-component-source.ts
+++ b/templates/design/actions/open-component-source.ts
@@ -18,8 +18,8 @@
  * to open.
  *
  * Navigation is written via `writeAppState("navigate", ...)` — the same
- * mechanism used by the `navigate` action — so the caller can trigger UI
- * navigation without a round-trip.
+ * mechanism used by the `navigate` action. Because this writes transient
+ * application state, the action uses the default POST mutation transport.
  *
  * See DESIGN-STUDIO-PLAN.md §6.1 (jump-to-source) and §7 (action surface).
  */
@@ -80,8 +80,6 @@ export default defineAction({
       .optional()
       .describe("Design file id; defaults to index.html"),
   }),
-  readOnly: true,
-  http: { method: "GET" },
   run: async ({ designId, nodeId, fileId }) => {
     const db = getDb();
 
diff --git a/templates/design/actions/open-visual-edit.spec.ts b/templates/design/actions/open-visual-edit.spec.ts
index d2aed4c80c..e5f8293dcb 100644
--- a/templates/design/actions/open-visual-edit.spec.ts
+++ b/templates/design/actions/open-visual-edit.spec.ts
@@ -141,4 +141,24 @@ describe("open-visual-edit", () => {
       }),
     );
   });
+
+  it("accepts the complete capability list emitted by design connect route discovery", () => {
+    const parsed = action.schema.safeParse({
+      designId: "design_1",
+      devServerUrl: "http://localhost:5173",
+      capabilities: [
+        { operation: "select", status: "available" },
+        { operation: "resolveNodeToFile", status: "available" },
+        { operation: "readFile", status: "available" },
+        { operation: "applyEdit", status: "available" },
+        { operation: "writeFile", status: "available" },
+        { operation: "captureSnapshot", status: "available" },
+        { operation: "captureState", status: "available" },
+        { operation: "listFiles", status: "available" },
+      ],
+      paths: ["/"],
+    });
+
+    expect(parsed.success).toBe(true);
+  });
 });
diff --git a/templates/design/actions/present-design-variants.spec.ts b/templates/design/actions/present-design-variants.spec.ts
index c08b1c1ee6..41cd1a2a2c 100644
--- a/templates/design/actions/present-design-variants.spec.ts
+++ b/templates/design/actions/present-design-variants.spec.ts
@@ -1,13 +1,32 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => {
+  const schema = {
+    designs: {
+      id: "designs.id",
+      data: "designs.data",
+      updatedAt: "designs.updatedAt",
+    },
+    designShares: "designShares",
+    designFiles: {
+      id: "designFiles.id",
+      designId: "designFiles.designId",
+      filename: "designFiles.filename",
+      content: "designFiles.content",
+      fileType: "designFiles.fileType",
+      createdAt: "designFiles.createdAt",
+      updatedAt: "designFiles.updatedAt",
+    },
+  };
+
+  // Routed by `.from()`'s argument so the designs-table precheck read in
+  // cleanupUnpickedVariantSets and the design_files-table reads/inserts
+  // elsewhere in the action get independently controllable mock chains.
   const designSelectChain = {
     from: vi.fn(),
     where: vi.fn(),
-    limit: vi.fn(),
   };
   designSelectChain.from.mockReturnValue(designSelectChain);
-  designSelectChain.where.mockReturnValue(designSelectChain);
 
   const filesSelectChain = {
     from: vi.fn(),
@@ -30,6 +49,8 @@ const mocks = vi.hoisted(() => {
   };
   updateChain.set.mockReturnValue(updateChain);
 
+  const deleteChain = { where: vi.fn() };
+
   const txUpdateChain = {
     set: vi.fn(),
     where: vi.fn(),
@@ -42,13 +63,18 @@ const mocks = vi.hoisted(() => {
   };
 
   const db = {
-    select: vi.fn(),
+    select: vi.fn(() => ({
+      from: (table: unknown) =>
+        table === schema.designs ? designSelectChain : filesSelectChain,
+    })),
     insert: vi.fn(() => insertChain),
     update: vi.fn(() => updateChain),
+    delete: vi.fn(() => deleteChain),
     transaction: vi.fn(async (callback) => callback(tx)),
   };
 
   return {
+    schema,
     db,
     tx,
     designSelectChain,
@@ -56,15 +82,19 @@ const mocks = vi.hoisted(() => {
     txSelectChain,
     insertChain,
     updateChain,
+    deleteChain,
     txUpdateChain,
     writeAppState: vi.fn(),
     writeAppStateForCurrentTab: vi.fn(),
     deleteAppState: vi.fn(),
     assertAccess: vi.fn(),
+    accessFilter: vi.fn(() => ({ access: true })),
     seedFromText: vi.fn(),
     hasCollabState: vi.fn(),
     applyText: vi.fn(),
     eq: vi.fn((left, right) => ({ left, right })),
+    and: vi.fn((...conditions) => ({ conditions })),
+    inArray: vi.fn((column, values) => ({ column, values })),
     nanoid: vi.fn(),
     designData: {} as Record<string, unknown>,
     mutateDesignData: vi.fn(),
@@ -84,6 +114,7 @@ vi.mock("@agent-native/core/collab", () => ({
 }));
 
 vi.mock("@agent-native/core/sharing", () => ({
+  accessFilter: mocks.accessFilter,
   assertAccess: mocks.assertAccess,
   registerShareableResource: vi.fn(),
 }));
@@ -99,7 +130,9 @@ vi.mock("@agent-native/core/server", () => ({
 }));
 
 vi.mock("drizzle-orm", () => ({
+  and: mocks.and,
   eq: mocks.eq,
+  inArray: mocks.inArray,
   sql: vi.fn((strings, ...values) => ({ strings, values })),
 }));
 
@@ -109,22 +142,7 @@ vi.mock("nanoid", () => ({
 
 vi.mock("../server/db/index.js", () => ({
   getDb: () => mocks.db,
-  schema: {
-    designs: {
-      id: "designs.id",
-      data: "designs.data",
-      updatedAt: "designs.updatedAt",
-    },
-    designFiles: {
-      id: "designFiles.id",
-      designId: "designFiles.designId",
-      filename: "designFiles.filename",
-      content: "designFiles.content",
-      fileType: "designFiles.fileType",
-      createdAt: "designFiles.createdAt",
-      updatedAt: "designFiles.updatedAt",
-    },
-  },
+  schema: mocks.schema,
 }));
 
 vi.mock("../server/lib/design-data-mutation.js", () => ({
@@ -152,18 +170,32 @@ describe("present-design-variants", () => {
       },
     );
     mocks.filesSelectChain.where.mockResolvedValue([]);
+    // Ties the designs-table precheck read in cleanupUnpickedVariantSets to
+    // the same simulated `designs.data` blob mutateDesignData reads/writes,
+    // so a test that seeds `mocks.designData` before calling `action.run`
+    // sees a consistent view across both mocked layers.
+    mocks.designSelectChain.where.mockImplementation(() =>
+      Promise.resolve([{ data: JSON.stringify(mocks.designData) }]),
+    );
+    mocks.deleteChain.where.mockResolvedValue(undefined);
     mocks.insertChain.values.mockResolvedValue(undefined);
     mocks.updateChain.where.mockResolvedValue(undefined);
     mocks.txUpdateChain.where.mockResolvedValue(undefined);
     mocks.hasCollabState.mockResolvedValue(false);
     mocks.seedFromText.mockResolvedValue(undefined);
     mocks.deleteAppState.mockResolvedValue(true);
+    // `vi.clearAllMocks()` above clears call history but NOT a queued
+    // `mockReturnValueOnce` chain, so any value a test left unconsumed (e.g.
+    // a test that only creates 2 variants never consumes the 4th queued id)
+    // would otherwise bleed into the next test's queue instead of being
+    // discarded. Reset first so every test starts from the same 4-value
+    // sequence regardless of what earlier tests consumed.
+    mocks.nanoid.mockReset();
     mocks.nanoid
       .mockReturnValueOnce("variant-set-1")
       .mockReturnValueOnce("file-a")
       .mockReturnValueOnce("file-b")
       .mockReturnValueOnce("file-c");
-    mocks.db.select.mockReturnValue(mocks.filesSelectChain);
   });
 
   it("writes variants as overview screens and asks the user with chat buttons", async () => {
@@ -197,6 +229,10 @@ describe("present-design-variants", () => {
       "design_123",
       "editor",
     );
+    expect(mocks.accessFilter).toHaveBeenCalledWith(
+      mocks.schema.designs,
+      mocks.schema.designShares,
+    );
     expect(mocks.insertChain.values).toHaveBeenCalledTimes(3);
     expect(mocks.insertChain.values).toHaveBeenNthCalledWith(
       1,
@@ -580,4 +616,341 @@ describe("present-design-variants", () => {
     // persists just as any other AI-authored screen would.
     expect(fallbackInsert.content).toContain("data-agent-native-node-id");
   });
+
+  it("retries with a fresh filename when a concurrent insert wins the race for the same (designId, filename)", async () => {
+    mocks.nanoid.mockReset();
+    mocks.nanoid
+      .mockReturnValueOnce("variant-set-1")
+      .mockReturnValueOnce("file-a-loser")
+      .mockReturnValueOnce("file-a-winner")
+      .mockReturnValueOnce("file-b");
+
+    mocks.insertChain.values
+      .mockImplementationOnce(() => {
+        throw Object.assign(
+          new Error(
+            'duplicate key value violates unique constraint "design_files_design_filename_unique_idx"',
+          ),
+          { code: "23505" },
+        );
+      })
+      .mockResolvedValue(undefined);
+
+    const result = await action.run({
+      designId: "design_123",
+      variants: [
+        {
+          id: "pure-white",
+          label: "Pure White",
+          content: "<!doctype html><html><body>One</body></html>",
+        },
+        {
+          id: "soft-cards",
+          label: "Soft Cards",
+          content: "<!doctype html><html><body>Two</body></html>",
+        },
+      ],
+    });
+
+    // Two attempts for the first variant (loser + retry), one for the second.
+    expect(mocks.insertChain.values).toHaveBeenCalledTimes(3);
+    const firstAttempt = mocks.insertChain.values.mock.calls[0]![0] as {
+      id: string;
+      filename: string;
+    };
+    const secondAttempt = mocks.insertChain.values.mock.calls[1]![0] as {
+      id: string;
+      filename: string;
+    };
+    expect(firstAttempt.filename).toBe("variant-pure-white.html");
+    // uniqueFilename's local `used` set already contains the failed
+    // candidate, so the retry deterministically picks the next slot without
+    // needing the refreshed DB read to report anything new.
+    expect(secondAttempt.filename).toBe("variant-pure-white-2.html");
+    expect(secondAttempt.id).not.toBe(firstAttempt.id);
+    expect(secondAttempt.id).toBe("file-a-winner");
+
+    // Only the surviving (second) attempt is seeded and reported — the
+    // failed insert never created a row, so seeding it would target nothing.
+    expect(mocks.seedFromText).toHaveBeenCalledWith(
+      "file-a-winner",
+      expect.stringContaining("One"),
+    );
+    expect(mocks.seedFromText).not.toHaveBeenCalledWith(
+      "file-a-loser",
+      expect.anything(),
+    );
+    expect(
+      result.screens.find((screen) => screen.label === "Pure White"),
+    ).toMatchObject({
+      id: "file-a-winner",
+      filename: "variant-pure-white-2.html",
+    });
+  });
+
+  it("propagates a non-conflict insert error immediately without retrying", async () => {
+    mocks.insertChain.values.mockImplementationOnce(() => {
+      throw new Error("connection terminated unexpectedly");
+    });
+
+    await expect(
+      action.run({
+        designId: "design_123",
+        variants: [
+          { id: "a", label: "A", content: "<html>A</html>" },
+          { id: "b", label: "B", content: "<html>B</html>" },
+        ],
+      }),
+    ).rejects.toThrow("connection terminated unexpectedly");
+
+    expect(mocks.insertChain.values).toHaveBeenCalledTimes(1);
+  });
+
+  it("never deletes a possibly-picked previous variant set by default; it only marks it superseded", async () => {
+    // The critical data-loss scenario: a full untouched set from a previous
+    // call. The user may have picked one of its screens in chat (the pick is
+    // not observable server-side until the agent's delete-file turn runs), so
+    // a plain retry / second present-design-variants call must NOT delete
+    // anything from it.
+    mocks.designData = {
+      canvasFrames: {
+        "old-file-a": { x: 0, y: 0, width: 390, height: 844, z: 0 },
+        "old-file-b": { x: 500, y: 0, width: 390, height: 844, z: 1 },
+        "kept-screen": { x: 0, y: 900, width: 1280, height: 900, z: 0 },
+      },
+      screenMetadata: {
+        "old-file-a": { title: "Old A", variantSetId: "old-set" },
+        "old-file-b": { title: "Old B", variantSetId: "old-set" },
+        "kept-screen": { title: "Unrelated kept screen" },
+      },
+      designVariantSets: {
+        "old-set": {
+          id: "old-set",
+          prompt: "Old prompt",
+          createdAt: "2026-07-01T00:00:00.000Z",
+          screenCount: 2,
+          screens: [
+            { id: "old-file-a", variantId: "a", label: "Old A" },
+            { id: "old-file-b", variantId: "b", label: "Old B" },
+          ],
+        },
+      },
+    };
+
+    const result = await action.run({
+      designId: "design_123",
+      prompt: "Try again",
+      variants: [
+        {
+          id: "pure-white",
+          label: "Pure White",
+          content: "<!doctype html><html><body>New one</body></html>",
+        },
+        {
+          id: "soft-cards",
+          label: "Soft Cards",
+          content: "<!doctype html><html><body>Two</body></html>",
+        },
+      ],
+    });
+
+    // Nothing is hard-deleted: no design_files rows removed, all old screens
+    // and their metadata survive.
+    expect(mocks.db.delete).not.toHaveBeenCalled();
+    expect(mocks.designData.canvasFrames["old-file-a"]).toBeDefined();
+    expect(mocks.designData.canvasFrames["old-file-b"]).toBeDefined();
+    expect(mocks.designData.screenMetadata["old-file-a"]).toMatchObject({
+      title: "Old A",
+    });
+    expect(mocks.designData.screenMetadata["old-file-b"]).toMatchObject({
+      title: "Old B",
+    });
+
+    // The old set stays but is marked superseded (bookkeeping only), making
+    // it eligible for a later explicit deleteSupersededSetIds opt-in.
+    expect(mocks.designData.designVariantSets["old-set"]).toMatchObject({
+      superseded: true,
+      screenCount: 2,
+    });
+    expect(mocks.designData.designVariantSets["old-set"].screens).toHaveLength(
+      2,
+    );
+
+    // The new variant set's own screens are present and unaffected.
+    expect(mocks.designData.designVariantSets["variant-set-1"]).toBeDefined();
+    expect(
+      mocks.designData.designVariantSets["variant-set-1"].screens,
+    ).toHaveLength(2);
+
+    expect(result.cleanedUpPreviousVariantScreens).toBe(0);
+    expect(result.deletedSupersededSetIds).toEqual([]);
+  });
+
+  it("deletes a superseded set's screens only when the agent explicitly opts in via deleteSupersededSetIds", async () => {
+    mocks.designData = {
+      canvasFrames: {
+        "old-file-a": { x: 0, y: 0, width: 390, height: 844, z: 0 },
+        "old-file-b": { x: 500, y: 0, width: 390, height: 844, z: 1 },
+        "kept-screen": { x: 0, y: 900, width: 1280, height: 900, z: 0 },
+      },
+      screenMetadata: {
+        "old-file-a": { title: "Old A", variantSetId: "old-set" },
+        "old-file-b": { title: "Old B", variantSetId: "old-set" },
+        "kept-screen": { title: "Unrelated kept screen" },
+      },
+      designVariantSets: {
+        "old-set": {
+          id: "old-set",
+          prompt: "Old prompt",
+          createdAt: "2026-07-01T00:00:00.000Z",
+          screenCount: 2,
+          screens: [
+            { id: "old-file-a", variantId: "a", label: "Old A" },
+            { id: "old-file-b", variantId: "b", label: "Old B" },
+          ],
+        },
+      },
+    };
+
+    const result = await action.run({
+      designId: "design_123",
+      prompt: "Try again",
+      deleteSupersededSetIds: ["old-set"],
+      variants: [
+        {
+          id: "pure-white",
+          label: "Pure White",
+          content: "<!doctype html><html><body>New one</body></html>",
+        },
+        {
+          id: "soft-cards",
+          label: "Soft Cards",
+          content: "<!doctype html><html><body>Two</body></html>",
+        },
+      ],
+    });
+
+    // The named set's screens are gone from the design_files table...
+    expect(mocks.db.delete).toHaveBeenCalledWith(mocks.schema.designFiles);
+    expect(mocks.inArray).toHaveBeenCalledWith(
+      mocks.schema.designFiles.id,
+      expect.arrayContaining(["old-file-a", "old-file-b"]),
+    );
+    const deletedIds = mocks.inArray.mock.calls.find(
+      (call) => call[0] === mocks.schema.designFiles.id,
+    )?.[1] as string[];
+    expect(deletedIds).toHaveLength(2);
+
+    // ...and their metadata + the whole old variant set are pruned from the
+    // design's JSON data.
+    expect(mocks.designData.canvasFrames["old-file-a"]).toBeUndefined();
+    expect(mocks.designData.canvasFrames["old-file-b"]).toBeUndefined();
+    expect(mocks.designData.screenMetadata["old-file-a"]).toBeUndefined();
+    expect(mocks.designData.screenMetadata["old-file-b"]).toBeUndefined();
+    expect(mocks.designData.designVariantSets["old-set"]).toBeUndefined();
+
+    // An unrelated screen never referenced by the stale variant set survives
+    // untouched.
+    expect(mocks.designData.canvasFrames["kept-screen"]).toMatchObject({
+      x: 0,
+      y: 900,
+    });
+    expect(mocks.designData.screenMetadata["kept-screen"]).toMatchObject({
+      title: "Unrelated kept screen",
+    });
+
+    // The new variant set's own screens are present and unaffected.
+    expect(mocks.designData.designVariantSets["variant-set-1"]).toBeDefined();
+    expect(
+      mocks.designData.designVariantSets["variant-set-1"].screens,
+    ).toHaveLength(2);
+
+    expect(result.cleanedUpPreviousVariantScreens).toBe(2);
+    expect(result.deletedSupersededSetIds).toEqual(["old-set"]);
+  });
+
+  it("never deletes a partially-picked set even when explicitly requested (screenCount no longer matches)", async () => {
+    mocks.designData = {
+      canvasFrames: {
+        "old-file-a": { x: 0, y: 0, width: 390, height: 844, z: 0 },
+      },
+      screenMetadata: {
+        "old-file-a": { title: "Old A", variantSetId: "old-set" },
+      },
+      designVariantSets: {
+        "old-set": {
+          id: "old-set",
+          prompt: "Old prompt",
+          createdAt: "2026-07-01T00:00:00.000Z",
+          // screenCount (3) no longer matches screens.length (1): a pick has
+          // resolved against this set (delete-file.ts already removed 2 of 3
+          // screens), so the survivor is very likely the user's kept screen.
+          // It must never be deleted, even when the caller names the set.
+          screenCount: 3,
+          screens: [{ id: "old-file-a", variantId: "a", label: "Old A" }],
+        },
+      },
+    };
+
+    await action.run({
+      designId: "design_123",
+      deleteSupersededSetIds: ["old-set"],
+      variants: [
+        { id: "a", label: "A", content: "<html>A</html>" },
+        { id: "b", label: "B", content: "<html>B</html>" },
+      ],
+    });
+
+    expect(mocks.db.delete).not.toHaveBeenCalled();
+    expect(mocks.designData.designVariantSets["old-set"]).toBeDefined();
+    // A touched set is never marked superseded either.
+    expect(
+      mocks.designData.designVariantSets["old-set"].superseded,
+    ).toBeUndefined();
+    expect(mocks.designData.canvasFrames["old-file-a"]).toBeDefined();
+  });
+
+  it("never deletes a previous variant set lacking the screenCount field (legacy data), even when requested", async () => {
+    mocks.designData = {
+      canvasFrames: {
+        "old-file-a": { x: 0, y: 0, width: 390, height: 844, z: 0 },
+        "old-file-b": { x: 500, y: 0, width: 390, height: 844, z: 1 },
+      },
+      screenMetadata: {
+        "old-file-a": { title: "Old A" },
+        "old-file-b": { title: "Old B" },
+      },
+      designVariantSets: {
+        "old-set": {
+          id: "old-set",
+          prompt: "Old prompt",
+          createdAt: "2026-07-01T00:00:00.000Z",
+          // No screenCount at all — predates this field. Cannot be proven
+          // untouched, so it is never marked superseded and never deleted
+          // even when the caller names it.
+          screens: [
+            { id: "old-file-a", variantId: "a", label: "Old A" },
+            { id: "old-file-b", variantId: "b", label: "Old B" },
+          ],
+        },
+      },
+    };
+
+    await action.run({
+      designId: "design_123",
+      deleteSupersededSetIds: ["old-set"],
+      variants: [
+        { id: "a", label: "A", content: "<html>A</html>" },
+        { id: "b", label: "B", content: "<html>B</html>" },
+      ],
+    });
+
+    expect(mocks.db.delete).not.toHaveBeenCalled();
+    expect(mocks.designData.designVariantSets["old-set"]).toBeDefined();
+    expect(
+      mocks.designData.designVariantSets["old-set"].superseded,
+    ).toBeUndefined();
+    expect(mocks.designData.canvasFrames["old-file-a"]).toBeDefined();
+    expect(mocks.designData.canvasFrames["old-file-b"]).toBeDefined();
+  });
 });
diff --git a/templates/design/actions/present-design-variants.ts b/templates/design/actions/present-design-variants.ts
index ae1d2d0ff4..7d076472fc 100644
--- a/templates/design/actions/present-design-variants.ts
+++ b/templates/design/actions/present-design-variants.ts
@@ -6,8 +6,8 @@ import {
 } from "@agent-native/core/application-state";
 import { seedFromText } from "@agent-native/core/collab";
 import { buildDeepLink } from "@agent-native/core/server";
-import { assertAccess } from "@agent-native/core/sharing";
-import { eq } from "drizzle-orm";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq, inArray } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { z } from "zod";
 
@@ -18,6 +18,7 @@ import {
   mergeCanvasFramePlacements,
   type CanvasFramePlacement,
 } from "../shared/canvas-frames.js";
+import { isUniqueConstraintViolation } from "../shared/db-conflict.js";
 import { annotateScreenHtmlForPersist } from "../shared/screen-annotation.js";
 
 const VARIANT_GAP = 96;
@@ -120,6 +121,336 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
+const MAX_FILENAME_INSERT_ATTEMPTS = 5;
+
+/**
+ * True only when `rawSet` proves none of its screens has ever been removed by
+ * delete-file.ts. This action stamps every variant set it creates with
+ * `screenCount` — the exact number of screens it generated, which never
+ * changes afterward (present-design-variants.ts never mutates an existing
+ * set's `screenCount`, and delete-file.ts's `pruneDesignVariantSets` only
+ * ever shortens/removes a set's `screens` array, never touches `screenCount`).
+ * The moment any member is deleted, `screens.length` drops below the
+ * recorded `screenCount` (or the whole entry is removed once <=1 screens
+ * remain) — either way, `screens.length === screenCount` no longer holds. So
+ * this equality proves no delete-file call has EVER resolved against this
+ * set.
+ *
+ * IMPORTANT: this does NOT prove the user never picked a screen from the set.
+ * A pick only exists as a chat instruction (see `VARIANT_PICK_SUBMIT_MESSAGE`)
+ * until the agent's follow-up turn actually calls delete-file for the losers;
+ * there is no synchronous server-side seam that records a pick before that
+ * turn runs (an agent retry after a run cutoff, or a second
+ * present-design-variants call, can both land before the delete-file calls
+ * do). So `isUntouchedVariantSet` is used only to decide whether a set is
+ * eligible to be *marked* superseded — never as authority to delete its
+ * files. See `markSupersededVariantSets` / `deleteVariantSetsByIds` below.
+ * Sets without a numeric `screenCount` at all (legacy data predating this
+ * field) are NOT treated as untouched either, since we cannot prove those
+ * were never picked.
+ */
+function isUntouchedVariantSet(
+  rawSet: unknown,
+): rawSet is { screens: unknown[]; screenCount: number } & Record<
+  string,
+  unknown
+> {
+  return (
+    isRecord(rawSet) &&
+    Array.isArray(rawSet.screens) &&
+    typeof rawSet.screenCount === "number" &&
+    rawSet.screens.length === rawSet.screenCount
+  );
+}
+
+function collectUnmarkedSupersededCandidateIds(
+  variantSets: Record<string, unknown>,
+): string[] {
+  const setIds: string[] = [];
+  for (const [setId, rawSet] of Object.entries(variantSets)) {
+    if (!isUntouchedVariantSet(rawSet)) continue;
+    if (isRecord(rawSet) && rawSet.superseded === true) continue;
+    setIds.push(setId);
+  }
+  return setIds;
+}
+
+function screenFileIdsForSet(rawSet: { screens: unknown[] }): string[] {
+  const fileIds = new Set<string>();
+  for (const screen of rawSet.screens) {
+    const id = isRecord(screen)
+      ? screen.id
+      : typeof screen === "string"
+        ? screen
+        : undefined;
+    if (typeof id === "string") fileIds.add(id);
+  }
+  return Array.from(fileIds);
+}
+
+function pruneKeyedRecordForIds(
+  value: unknown,
+  ids: string[],
+): Record<string, unknown> {
+  const next = isRecord(value) ? { ...value } : {};
+  for (const id of ids) delete next[id];
+  return next;
+}
+
+/**
+ * Marks each PREVIOUS present-design-variants set for this design that is
+ * proven untouched (see `isUntouchedVariantSet`) as `superseded: true`,
+ * whenever a new variant set is created for the same design. This is
+ * bookkeeping ONLY — it never deletes files, never touches `canvasFrames` or
+ * `screenMetadata`, and is always safe to run unconditionally. A set with
+ * `superseded: true` still renders normally; the flag only makes it eligible
+ * for the opt-in `deleteSupersededSetIds` path below.
+ *
+ * Deletion is intentionally NOT automatic here. The failure mode this
+ * guards against: set V1=[S1,S2,S3] is generated; the user picks S2 in chat;
+ * before the agent's delete-file turn for S1/S3 actually runs (run cutoff,
+ * retry, or a second present-design-variants call arriving first),
+ * `screens.length === screenCount` still holds for V1 — a pick is not
+ * observable server-side until delete-file resolves it. Auto-deleting on
+ * that inference would have hard-deleted the picked screen S2 with no
+ * recovery. So this function only records bookkeeping; real deletion
+ * requires the agent to explicitly name the set via `deleteSupersededSetIds`
+ * — see that action param's description for the discipline expected of
+ * callers.
+ */
+async function markSupersededVariantSets(
+  designId: string,
+): Promise<{ markedSetIds: string[] }> {
+  const db = getDb();
+
+  // Cheap early-exit read so the common case (no stale variant set to mark)
+  // never bumps the design's updatedAt via a no-op mutateDesignData call —
+  // mutateDesignDataUnlocked always advances updatedAt on every commit, even
+  // when the payload is unchanged. The authoritative check still runs inside
+  // the mutate() callback below, so a race against this snapshot is harmless.
+  const [designRow] = await db
+    .select({ data: schema.designs.data })
+    .from(schema.designs)
+    .where(
+      and(
+        eq(schema.designs.id, designId),
+        accessFilter(schema.designs, schema.designShares),
+      ),
+    );
+  if (!designRow) return { markedSetIds: [] };
+  let precheckVariantSets: Record<string, unknown> = {};
+  if (designRow.data) {
+    try {
+      const parsed: unknown = JSON.parse(designRow.data);
+      if (isRecord(parsed) && isRecord(parsed.designVariantSets)) {
+        precheckVariantSets = parsed.designVariantSets;
+      }
+    } catch {
+      return { markedSetIds: [] };
+    }
+  }
+  if (collectUnmarkedSupersededCandidateIds(precheckVariantSets).length === 0) {
+    return { markedSetIds: [] };
+  }
+
+  let markedSetIds: string[] = [];
+
+  await mutateDesignData({
+    designId,
+    mutate: (current, { updatedAt }) => {
+      const variantSets = isRecord(current.designVariantSets)
+        ? current.designVariantSets
+        : {};
+      const setIds = collectUnmarkedSupersededCandidateIds(variantSets);
+      markedSetIds = setIds;
+      if (setIds.length === 0) return current;
+
+      const nextVariantSets = { ...variantSets };
+      for (const setId of setIds) {
+        const rawSet = variantSets[setId];
+        if (isRecord(rawSet)) {
+          nextVariantSets[setId] = { ...rawSet, superseded: true };
+        }
+      }
+
+      return {
+        ...current,
+        designVariantSets: nextVariantSets,
+        updatedAt,
+      };
+    },
+    isApplied: (current) => {
+      const variantSets = isRecord(current.designVariantSets)
+        ? current.designVariantSets
+        : {};
+      return markedSetIds.every(
+        (setId) =>
+          isRecord(variantSets[setId]) &&
+          variantSets[setId]!.superseded === true,
+      );
+    },
+  });
+
+  return { markedSetIds };
+}
+
+/**
+ * Explicit, opt-in permanent deletion of specific variant sets by id. This is
+ * the ONLY path that hard-deletes variant-set files; it never runs
+ * automatically. The caller (the agent) must pass `deleteSupersededSetIds`
+ * naming the exact sets it knows were abandoned without any user pick — e.g.
+ * generating a brand-new set after the user asked to see different options.
+ * Never pass a previous set's id here on the strength of a guess or a retry;
+ * only do so when there is no reason to believe the user discussed or picked
+ * one of its screens.
+ *
+ * As a safety net, a requested id is only honored when the set is already
+ * flagged `superseded: true` by `markSupersededVariantSets` (i.e. proven
+ * untouched by any delete-file call as of this same run). A set that has
+ * already had even one delete-file call resolve against it — the normal sign
+ * that a pick is mid-flight — is never marked superseded and is therefore
+ * never eligible here, regardless of what the caller requests.
+ */
+async function deleteVariantSetsByIds(
+  designId: string,
+  requestedSetIds: string[],
+): Promise<{ removedSetIds: string[]; removedFileIds: string[] }> {
+  const db = getDb();
+
+  // Same cheap early-exit as markSupersededVariantSets: skip the
+  // updatedAt-bumping mutateDesignData commit when none of the requested set
+  // ids currently qualifies for deletion. The authoritative check still runs
+  // inside the mutate() callback below.
+  const [designRow] = await db
+    .select({ data: schema.designs.data })
+    .from(schema.designs)
+    .where(
+      and(
+        eq(schema.designs.id, designId),
+        accessFilter(schema.designs, schema.designShares),
+      ),
+    );
+  if (!designRow) return { removedSetIds: [], removedFileIds: [] };
+  let precheckVariantSets: Record<string, unknown> = {};
+  if (designRow.data) {
+    try {
+      const parsed: unknown = JSON.parse(designRow.data);
+      if (isRecord(parsed) && isRecord(parsed.designVariantSets)) {
+        precheckVariantSets = parsed.designVariantSets;
+      }
+    } catch {
+      return { removedSetIds: [], removedFileIds: [] };
+    }
+  }
+  if (
+    !requestedSetIds.some((setId) => {
+      const rawSet = precheckVariantSets[setId];
+      return (
+        isRecord(rawSet) &&
+        rawSet.superseded === true &&
+        Array.isArray(rawSet.screens)
+      );
+    })
+  ) {
+    return { removedSetIds: [], removedFileIds: [] };
+  }
+
+  let removedSetIds: string[] = [];
+  let removedFileIds: string[] = [];
+
+  await mutateDesignData({
+    designId,
+    mutate: (current, { updatedAt }) => {
+      const variantSets = isRecord(current.designVariantSets)
+        ? current.designVariantSets
+        : {};
+      const setIds: string[] = [];
+      const fileIds = new Set<string>();
+      for (const setId of requestedSetIds) {
+        const rawSet = variantSets[setId];
+        if (
+          !isRecord(rawSet) ||
+          rawSet.superseded !== true ||
+          !Array.isArray(rawSet.screens)
+        ) {
+          continue;
+        }
+        setIds.push(setId);
+        for (const id of screenFileIdsForSet(
+          rawSet as { screens: unknown[] },
+        )) {
+          fileIds.add(id);
+        }
+      }
+      removedSetIds = setIds;
+      removedFileIds = Array.from(fileIds);
+      if (setIds.length === 0) return current;
+
+      const nextVariantSets = { ...variantSets };
+      for (const setId of setIds) delete nextVariantSets[setId];
+
+      return {
+        ...current,
+        canvasFrames: pruneKeyedRecordForIds(
+          current.canvasFrames,
+          removedFileIds,
+        ),
+        screenMetadata: pruneKeyedRecordForIds(
+          current.screenMetadata,
+          removedFileIds,
+        ),
+        designVariantSets: nextVariantSets,
+        updatedAt,
+      };
+    },
+    isApplied: (current) => {
+      const variantSets = isRecord(current.designVariantSets)
+        ? current.designVariantSets
+        : {};
+      return removedSetIds.every((setId) => !(setId in variantSets));
+    },
+  });
+
+  if (removedFileIds.length > 0) {
+    await db
+      .delete(schema.designFiles)
+      .where(inArray(schema.designFiles.id, removedFileIds));
+
+    // Closes the small window between the metadata prune above and the
+    // physical row delete: mirrors delete-file.ts's before/delete/after
+    // pattern so a sibling request that refreshed canvasFrames/screenMetadata
+    // for one of these now-deleted ids in that window still gets swept.
+    await mutateDesignData({
+      designId,
+      mutate: (current, { updatedAt }) => ({
+        ...current,
+        canvasFrames: pruneKeyedRecordForIds(
+          current.canvasFrames,
+          removedFileIds,
+        ),
+        screenMetadata: pruneKeyedRecordForIds(
+          current.screenMetadata,
+          removedFileIds,
+        ),
+        updatedAt,
+      }),
+      isApplied: (current) => {
+        const frames = isRecord(current.canvasFrames)
+          ? current.canvasFrames
+          : {};
+        const metadata = isRecord(current.screenMetadata)
+          ? current.screenMetadata
+          : {};
+        return removedFileIds.every(
+          (id) => !(id in frames) && !(id in metadata),
+        );
+      },
+    });
+  }
+
+  return { removedSetIds, removedFileIds };
+}
+
 function slugify(value: string, fallback: string) {
   return (
     value
@@ -432,7 +763,10 @@ export default defineAction({
     "compact representative screen; pass concise labels/descriptions/features " +
     "and omit content when full HTML would be too large. Design will render " +
     "compact screens from the direction data. Expand the chosen direction " +
-    "after the user picks.",
+    "after the user picks. Screens from an earlier variant set are never " +
+    "deleted automatically: if you are knowingly replacing your own earlier " +
+    "set that the user never picked from or discussed, pass its set id in " +
+    "deleteSupersededSetIds; otherwise leave old sets in place.",
   schema: z.object({
     designId: z.string().describe("Design project ID to show variants for"),
     prompt: z
@@ -446,6 +780,19 @@ export default defineAction({
       .describe(
         "2-5 concise, visually distinct generated design options to place as overview screens (3 is the sweet spot). Prefer short label/description/features for each direction; include inline HTML content only when it is compact enough to finish.",
       ),
+    deleteSupersededSetIds: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "OPT-IN permanent deletion of earlier variant sets you are knowingly " +
+          "replacing. Pass a previous variantSetId ONLY when you created that " +
+          "set yourself and the user never picked, kept, or discussed any of " +
+          "its screens (e.g. the user asked for a completely different set of " +
+          "directions). If the user may have picked a screen — even if the " +
+          "losing screens have not been deleted yet — do NOT pass the set id: " +
+          "deletion is permanent and would destroy the picked screen. Ids are " +
+          "only honored for sets provably untouched by any delete-file call.",
+      ),
   }),
   mcpApp: {
     compactCatalog: true,
@@ -458,9 +805,22 @@ export default defineAction({
       height: 720,
     }),
   },
-  run: async ({ designId, prompt, variants }) => {
+  run: async ({ designId, prompt, variants, deleteSupersededSetIds }) => {
     await assertAccess("design", designId, "editor");
 
+    // Non-destructive bookkeeping: flag earlier still-complete variant sets
+    // as superseded. Files are NEVER deleted automatically — a user's pick
+    // exists only as a chat instruction until the agent's delete-file turn
+    // runs, so an automatic sweep here could destroy the picked screen. Real
+    // deletion happens only for set ids the caller explicitly opts into via
+    // `deleteSupersededSetIds` below (and only when the set is provably
+    // untouched by any delete-file call).
+    await markSupersededVariantSets(designId);
+    const variantSetCleanup =
+      deleteSupersededSetIds && deleteSupersededSetIds.length > 0
+        ? await deleteVariantSetsByIds(designId, deleteSupersededSetIds)
+        : { removedSetIds: [], removedFileIds: [] };
+
     const db = getDb();
     const now = new Date().toISOString();
     const existingFiles = await db
@@ -475,9 +835,8 @@ export default defineAction({
       const variant = variants[index]!;
       const label = variant.label.trim() || optionName(index);
       const slug = slugify(label, `option-${index + 1}`);
-      const preferredFilename = `variant-${slug}.html`;
-      const filename = uniqueFilename(preferredFilename, usedFilenames);
-      const fileId = nanoid();
+      let filename = uniqueFilename(`variant-${slug}.html`, usedFilenames);
+      let fileId = nanoid();
       const providedContent = variant.content?.trim();
       const initialSize = inferVariantSize(variant, prompt);
       const rawContent =
@@ -491,15 +850,43 @@ export default defineAction({
       // operations as soon as it lands on the overview board.
       const content = annotateScreenHtmlForPersist(rawContent, "html");
 
-      await db.insert(schema.designFiles).values({
-        id: fileId,
-        designId,
-        filename,
-        fileType: "html",
-        content,
-        createdAt: now,
-        updatedAt: now,
-      });
+      // `usedFilenames` is a snapshot taken once at the top of run(), so a
+      // concurrent present-design-variants call (an agent retry after a
+      // timeout is the common trigger) can independently compute the same
+      // (designId, filename) pair and win the insert first. The
+      // `design_files_design_filename_unique_idx` unique index (see
+      // server/plugins/db.ts) turns the loser's insert into a constraint
+      // error instead of a silently duplicated screen; recover by refreshing
+      // the real filename list from the DB, picking a fresh unique name, and
+      // retrying — bounded so a persistent non-race failure still surfaces.
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          await db.insert(schema.designFiles).values({
+            id: fileId,
+            designId,
+            filename,
+            fileType: "html",
+            content,
+            createdAt: now,
+            updatedAt: now,
+          });
+          break;
+        } catch (err) {
+          if (
+            !isUniqueConstraintViolation(err) ||
+            attempt >= MAX_FILENAME_INSERT_ATTEMPTS
+          ) {
+            throw err;
+          }
+          const freshFiles = await db
+            .select({ filename: schema.designFiles.filename })
+            .from(schema.designFiles)
+            .where(eq(schema.designFiles.designId, designId));
+          for (const file of freshFiles) usedFilenames.add(file.filename);
+          filename = uniqueFilename(`variant-${slug}.html`, usedFilenames);
+          fileId = nanoid();
+        }
+      }
       await seedFromText(fileId, content);
 
       screens.push({
@@ -542,6 +929,13 @@ export default defineAction({
           id: variantSetId,
           prompt: prompt ?? "Pick a direction",
           createdAt: now,
+          // Immutable record of how many screens this set started with, so a
+          // later present-design-variants call can prove no delete-file call
+          // has ever resolved against any of this set's screens — see
+          // markSupersededVariantSets / isUntouchedVariantSet above.
+          // delete-file.ts's pruneDesignVariantSets only ever shortens or
+          // removes `screens`; it never rewrites this field.
+          screenCount: screens.length,
           screens: screens.map((screen) => ({
             id: screen.id,
             variantId: screen.variantId,
@@ -638,6 +1032,8 @@ export default defineAction({
       screens,
       path: `/design/${encodeURIComponent(designId)}?view=overview`,
       embed: true,
+      cleanedUpPreviousVariantScreens: variantSetCleanup.removedFileIds.length,
+      deletedSupersededSetIds: variantSetCleanup.removedSetIds,
       fallbackInstructions: FALLBACK_INSTRUCTIONS,
       nextRequiredAction:
         'Wait for the user to pick a screen in chat. Then delete each unchosen variant screen with delete-file at most once, call get-design-snapshot exactly once with fileId for the chosen screen, and call edit-design with that same fileId in a bounded pass. Use mode "replace-file" to replace the representative direction screen with a complete but compact requested app/product UI in the chosen visual style. Prioritize the primary workflow and render secondary details as visible controls, states, or affordances if the full feature list is too large for one reliable edit. Do not leave a direction board, variant brief, or summary card as the final result. Do not repeat delete/snapshot cycles. Do not call generate-design after a variant pick. Stop after the first successful edit-design save.',
diff --git a/templates/design/actions/preview-source-edit.spec.ts b/templates/design/actions/preview-source-edit.spec.ts
new file mode 100644
index 0000000000..d9d88bdce8
--- /dev/null
+++ b/templates/design/actions/preview-source-edit.spec.ts
@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// ---------------------------------------------------------------------------
+// preview-source-edit.spec.ts
+//
+// Regression test for an inverted `nextVersionHash`: the action used to
+// return `undefined` exactly when the edit DID change the content (the case
+// where a caller actually needs the post-edit hash to pass into
+// apply-source-edit's `expectedVersionHash` and close the preview -> apply
+// race), and returned the unchanged `currentVersionHash` when nothing
+// changed (where a "next" hash adds no value — it's identical to "current").
+// Fixed to compute the real post-edit hash via the same `sourceContentHash`
+// convention apply-source-edit.ts uses (server/source-workspace.ts's
+// writeInlineSourceFile hashes the persisted content the same way), and to
+// omit it only when there is genuinely no new content to hash.
+// ---------------------------------------------------------------------------
+
+const mocks = vi.hoisted(() => ({
+  resolveSourceWorkspace: vi.fn(),
+  findSourceWorkspaceFile: vi.fn(),
+  readLiveSourceFile: vi.fn(),
+}));
+
+vi.mock("@agent-native/core", () => ({
+  defineAction: (config: unknown) => config,
+}));
+vi.mock("../server/source-workspace.js", () => ({
+  resolveSourceWorkspace: mocks.resolveSourceWorkspace,
+  findSourceWorkspaceFile: mocks.findSourceWorkspaceFile,
+  readLiveSourceFile: mocks.readLiveSourceFile,
+}));
+
+import { sourceContentHash } from "../shared/source-workspace.js";
+import action from "./preview-source-edit.js";
+
+describe("preview-source-edit nextVersionHash", () => {
+  const liveContent = "<html><body>Hello</body></html>";
+
+  beforeEach(() => {
+    mocks.resolveSourceWorkspace.mockReset().mockResolvedValue({
+      canEdit: true,
+      sourceType: "inline",
+      files: [],
+    });
+    mocks.findSourceWorkspaceFile.mockReset().mockReturnValue({
+      id: "file_1",
+      filename: "index.html",
+    });
+    mocks.readLiveSourceFile.mockReset().mockResolvedValue({
+      content: liveContent,
+      versionHash: sourceContentHash(liveContent),
+    });
+  });
+
+  it("returns the post-edit hash (not the current hash, not undefined) when the edit actually changes content", async () => {
+    const result = (await action.run({
+      designId: "design_1",
+      fileId: "file_1",
+      edit: { kind: "exact-replace", search: "Hello", replace: "Goodbye" },
+    })) as { nextVersionHash?: string; currentVersionHash: string };
+
+    const expectedNextContent = liveContent.replace("Hello", "Goodbye");
+    expect(result.nextVersionHash).toBe(sourceContentHash(expectedNextContent));
+    expect(result.nextVersionHash).not.toBeUndefined();
+    expect(result.nextVersionHash).not.toBe(result.currentVersionHash);
+  });
+
+  it("omits nextVersionHash when the edit is a no-op (identical full-replace content)", async () => {
+    const result = (await action.run({
+      designId: "design_1",
+      fileId: "file_1",
+      edit: { kind: "full-replace", content: liveContent },
+    })) as { nextVersionHash?: string; editsApplied: number };
+
+    expect(result.editsApplied).toBe(0);
+    expect(result.nextVersionHash).toBeUndefined();
+  });
+});
diff --git a/templates/design/actions/preview-source-edit.ts b/templates/design/actions/preview-source-edit.ts
index 5197eb0d62..d95a25f467 100644
--- a/templates/design/actions/preview-source-edit.ts
+++ b/templates/design/actions/preview-source-edit.ts
@@ -9,6 +9,7 @@ import {
 import {
   applySourceEdit,
   previewSourceDiff,
+  sourceContentHash,
 } from "../shared/source-workspace.js";
 
 const sourceEditSchema = z.discriminatedUnion("kind", [
@@ -77,7 +78,19 @@ export default defineAction({
       conflict:
         workspace.sourceType === "inline" ? null : "unsupported-source-backend",
       currentVersionHash: live.versionHash,
-      nextVersionHash: next.changed ? undefined : live.versionHash,
+      // The hash the file WOULD have after this edit is applied. Do NOT pass
+      // this as apply-source-edit's expectedVersionHash — that CAS compares
+      // against the CURRENT pre-edit hash, so the post-edit hash would always
+      // fail; pass `currentVersionHash` (above) instead to close the
+      // preview→apply race, exactly as the code workbench's inline-provider
+      // does. `nextVersionHash` is for detecting that the preview's target
+      // content changed (compare a later preview/read against it) and for
+      // optimistic client bookkeeping of the expected post-apply hash.
+      // When nothing changed, the content is still `live.content`, so there
+      // is no new hash to report.
+      nextVersionHash: next.changed
+        ? sourceContentHash(next.content)
+        : undefined,
       editsApplied: next.editsApplied,
       diff: previewSourceDiff(live.content, next.content),
     };
diff --git a/templates/design/actions/run-design-audit.ts b/templates/design/actions/run-design-audit.ts
index 9cbb6150e7..de2c85e484 100644
--- a/templates/design/actions/run-design-audit.ts
+++ b/templates/design/actions/run-design-audit.ts
@@ -66,8 +66,20 @@ function extractSelector(tagHtml: string, tagName: string): string | undefined {
   if (idMatch) return `#${idMatch[1] ?? idMatch[2]}`;
   const classMatch = tagHtml.match(/\bclass\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
   if (classMatch) {
-    const first = (classMatch[1] ?? classMatch[2] ?? "").trim().split(/\s+/)[0];
-    if (first) return `${tagName.toLowerCase()}.${first}`;
+    const classNames = (classMatch[1] ?? classMatch[2] ?? "")
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean);
+    if (classNames.length > 0) {
+      // Include every class, not just the first: Tailwind screens commonly
+      // have several sibling elements sharing one common utility class (e.g.
+      // two buttons both carrying "h-4" but differing in every other class).
+      // A first-class-only selector is ambiguous and apply-a11y-fix's
+      // deterministic edit engine (which treats every dot segment after the
+      // tag as a required class, see shared/code-layer.ts) would match the
+      // wrong element among several sharing only that one class.
+      return `${tagName.toLowerCase()}.${classNames.join(".")}`;
+    }
   }
   return undefined;
 }
@@ -104,6 +116,13 @@ function checkMissingAlt(html: string): A11yFinding[] {
   return findings;
 }
 
+/** Escape regex metacharacters so untrusted HTML attribute values (e.g. an
+ * author-supplied `id`) can be safely interpolated into a `RegExp` source
+ * string instead of crashing the audit or matching unintended text. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 /** Check form inputs without an associated <label> or aria-label/aria-labelledby. */
 function checkMissingLabels(html: string): A11yFinding[] {
   const findings: A11yFinding[] = [];
@@ -126,7 +145,10 @@ function checkMissingLabels(html: string): A11yFinding[] {
     const idMatch = tag.match(/\bid\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
     const inputId = idMatch?.[1] ?? idMatch?.[2];
     const hasExplicitLabel = inputId
-      ? new RegExp(`for\\s*=\\s*(?:"${inputId}"|'${inputId}')`, "i").test(html)
+      ? new RegExp(
+          `for\\s*=\\s*(?:"${escapeRegExp(inputId)}"|'${escapeRegExp(inputId)}')`,
+          "i",
+        ).test(html)
       : false;
     const hasImplicitLabel = isWrappedByLabel(html, inputStart, inputEnd);
 
diff --git a/templates/design/actions/show-design-questions.spec.ts b/templates/design/actions/show-design-questions.spec.ts
index 45c72df4b3..39fed49de7 100644
--- a/templates/design/actions/show-design-questions.spec.ts
+++ b/templates/design/actions/show-design-questions.spec.ts
@@ -132,6 +132,30 @@ describe("show-design-questions", () => {
     ).toBe(false);
   });
 
+  it("rejects duplicate question ids, which would silently collide into one answer slot", () => {
+    const duplicateId = (n: number) => ({
+      id: "shared_id",
+      type: "freeform" as const,
+      question: `Question ${n}?`,
+    });
+
+    expect(
+      action.schema.safeParse({
+        designId: "design_123",
+        questions: [duplicateId(1), duplicateId(2)],
+      }).success,
+    ).toBe(false);
+    expect(
+      action.schema.safeParse({
+        designId: "design_123",
+        questions: [
+          { ...duplicateId(1), id: "q1" },
+          { ...duplicateId(2), id: "q2" },
+        ],
+      }).success,
+    ).toBe(true);
+  });
+
   it("returns an editor deep link for external hosts", () => {
     const link = action.link?.({
       args: {},
diff --git a/templates/design/actions/show-design-questions.ts b/templates/design/actions/show-design-questions.ts
index 7b558efa3d..fbb98b7dc2 100644
--- a/templates/design/actions/show-design-questions.ts
+++ b/templates/design/actions/show-design-questions.ts
@@ -87,6 +87,16 @@ export default defineAction({
       .describe(
         "1-8 focused design-intake questions. Prefer 4-6 concise questions " +
           "with useful choices, Other enabled, and Decide for me where appropriate.",
+      )
+      .refine(
+        (questions) =>
+          new Set(questions.map((question) => question.id)).size ===
+          questions.length,
+        {
+          message:
+            "Question ids must be unique — duplicate ids share one answer " +
+            "slot in the form, silently discarding one question's answer.",
+        },
       ),
   }),
   mcpApp: {
diff --git a/templates/design/actions/swap-component-instance.spec.ts b/templates/design/actions/swap-component-instance.spec.ts
new file mode 100644
index 0000000000..caf0368394
--- /dev/null
+++ b/templates/design/actions/swap-component-instance.spec.ts
@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+
+import action, {
+  findOpenTagEnd,
+  mergeComponentSwapOverrides,
+  reassignCopiedDescendantNodeIds,
+  setAttributeOnMarkup,
+} from "./swap-component-instance.js";
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+describe("swap-component-instance schema", () => {
+  const base = { designId: "design_1", nodeId: "node_1" };
+
+  it("accepts the minimal payload with a target component name", () => {
+    expect(
+      action.schema.safeParse({
+        ...base,
+        targetComponentName: "SecondaryButton",
+      }).success,
+    ).toBe(true);
+  });
+
+  it("rejects an empty targetComponentName", () => {
+    expect(
+      action.schema.safeParse({ ...base, targetComponentName: "" }).success,
+    ).toBe(false);
+  });
+
+  it("accepts an optional fileId and source revision guard", () => {
+    const parsed = action.schema.safeParse({
+      ...base,
+      targetComponentName: "SecondaryButton",
+      fileId: "file_about",
+      source: { currentContent: "<div></div>", revision: "2024-01-01" },
+    });
+    expect(parsed.success).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findOpenTagEnd
+// ---------------------------------------------------------------------------
+
+describe("findOpenTagEnd", () => {
+  it("finds the end of a simple opening tag", () => {
+    const markup = '<button class="a">Save</button>';
+    expect(findOpenTagEnd(markup)).toBe('<button class="a">'.length);
+  });
+
+  it("ignores a > inside a quoted attribute value", () => {
+    const markup = '<div data-note="a > b" class="x">Hi</div>';
+    const end = findOpenTagEnd(markup);
+    expect(markup.slice(0, end)).toBe('<div data-note="a > b" class="x">');
+  });
+
+  it("handles self-closing tags", () => {
+    const markup = '<img src="a.png" />';
+    expect(findOpenTagEnd(markup)).toBe(markup.length);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// setAttributeOnMarkup
+// ---------------------------------------------------------------------------
+
+describe("setAttributeOnMarkup", () => {
+  it("replaces an existing attribute value", () => {
+    const markup =
+      '<button data-agent-native-prop-variant="solid">Save</button>';
+    const result = setAttributeOnMarkup(
+      markup,
+      "data-agent-native-prop-variant",
+      "outline",
+    );
+    expect(result).toBe(
+      '<button data-agent-native-prop-variant="outline">Save</button>',
+    );
+  });
+
+  it("inserts a missing attribute before the closing >", () => {
+    const markup = "<button>Save</button>";
+    const result = setAttributeOnMarkup(
+      markup,
+      "data-agent-native-prop-variant",
+      "outline",
+    );
+    expect(result).toBe(
+      '<button data-agent-native-prop-variant="outline">Save</button>',
+    );
+  });
+
+  it("only touches the opening tag, not text content that looks like an attribute", () => {
+    const markup = '<span>data-agent-native-prop-variant="ignored"</span>';
+    const result = setAttributeOnMarkup(
+      markup,
+      "data-agent-native-node-id",
+      "n1",
+    );
+    expect(result).toBe(
+      '<span data-agent-native-node-id="n1">data-agent-native-prop-variant="ignored"</span>',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mergeComponentSwapOverrides
+// ---------------------------------------------------------------------------
+
+describe("mergeComponentSwapOverrides", () => {
+  it("carries over overrides for prop names both components share", () => {
+    const targetMarkup =
+      '<button data-agent-native-component="SecondaryButton" ' +
+      'data-agent-native-prop-variant="outline" data-agent-native-prop-size="md" ' +
+      "x-data=\"{ variant: 'outline', size: 'md' }\">Cancel</button>";
+
+    const currentProps = [
+      { name: "variant", value: "solid" },
+      { name: "tone", value: "danger" }, // not declared by the target
+    ];
+    const targetDefaultProps = [
+      { name: "variant", value: "outline" },
+      { name: "size", value: "md" },
+    ];
+
+    const result = mergeComponentSwapOverrides(
+      targetMarkup,
+      currentProps,
+      targetDefaultProps,
+      "btn1",
+    );
+
+    // "variant" was overridden onto the new markup.
+    expect(result.markup).toContain('data-agent-native-prop-variant="solid"');
+    // "size" was not overridden by the caller — keeps the target's default.
+    expect(result.markup).toContain('data-agent-native-prop-size="md"');
+    // The selected instance's stable node id is stamped onto the result.
+    expect(result.markup).toContain('data-agent-native-node-id="btn1"');
+    // The target's own x-data is left untouched (not merged).
+    expect(result.markup).toContain(
+      "x-data=\"{ variant: 'outline', size: 'md' }\"",
+    );
+
+    expect(result.overriddenProps).toEqual(["variant"]);
+    expect(result.droppedProps).toEqual(["tone"]);
+    expect(result.defaultedProps).toEqual(["size"]);
+  });
+
+  it("reports every current prop as dropped when the target declares none of them", () => {
+    const targetMarkup = '<div data-agent-native-component="Card">Body</div>';
+    const currentProps = [{ name: "tone", value: "info" }];
+    const result = mergeComponentSwapOverrides(
+      targetMarkup,
+      currentProps,
+      [],
+      "card1",
+    );
+    expect(result.overriddenProps).toEqual([]);
+    expect(result.droppedProps).toEqual(["tone"]);
+    expect(result.markup).not.toContain("data-agent-native-prop-tone");
+    expect(result.markup).toContain('data-agent-native-node-id="card1"');
+  });
+
+  it("re-keys copied descendants while preserving the selected root id", () => {
+    const targetMarkup =
+      '<article data-agent-native-node-id="source-root" data-agent-native-component="Card">' +
+      '<h2 data-agent-native-node-id="source-title">Title</h2>' +
+      '<div><span data-agent-native-node-id="source-label">Label</span></div>' +
+      "</article>";
+
+    let sequence = 0;
+    const rekeyed = reassignCopiedDescendantNodeIds(
+      targetMarkup,
+      () => `fresh-${++sequence}`,
+    );
+    expect(rekeyed).toContain('data-agent-native-node-id="source-root"');
+    expect(rekeyed).toContain('data-agent-native-node-id="fresh-1"');
+    expect(rekeyed).toContain('data-agent-native-node-id="fresh-2"');
+    expect(rekeyed).toContain('data-agent-native-node-id="fresh-3"');
+    expect(rekeyed).not.toContain("source-title");
+    expect(rekeyed).not.toContain("source-label");
+
+    const result = mergeComponentSwapOverrides(rekeyed, [], [], "selected");
+    expect(result.markup).toContain('data-agent-native-node-id="selected"');
+    expect(result.markup).not.toContain(
+      'data-agent-native-node-id="source-root"',
+    );
+  });
+});
diff --git a/templates/design/actions/swap-component-instance.ts b/templates/design/actions/swap-component-instance.ts
new file mode 100644
index 0000000000..b6eb3f52fb
--- /dev/null
+++ b/templates/design/actions/swap-component-instance.ts
@@ -0,0 +1,544 @@
+/**
+ * swap-component-instance — Figma's "Swap instance".
+ *
+ * DESIGN NOTE — mapping onto this codebase's data model: there is no
+ * separate component "definition"/template anywhere here (see
+ * `shared/component-model.ts`) — every instance is an independently
+ * duplicated copy of HTML matched purely by its
+ * `data-agent-native-component="Name"` annotation. "Swap to component B"
+ * therefore means: find an existing instance of B somewhere in the design
+ * (any screen), copy ITS current markup in as a replacement for the selected
+ * instance of A, and carry over whichever `data-agent-native-prop-*`
+ * overrides the selected instance had that B's own instances also declare
+ * (Figma's "preserve same-named overrides").
+ *
+ * Scope decisions, deliberately conservative:
+ * - Requires at least one existing instance of the target component
+ *   somewhere in the design (any file) to copy markup from. There is no
+ *   component library/definition to fall back to — this is a hard
+ *   requirement, not a data-model gap to route around.
+ * - Only `data-agent-native-prop-*` attribute overrides are carried over.
+ *   The `x-data` Alpine expression is intentionally NOT merged: Alpine state
+ *   can hold arbitrary JS (methods, nested objects, expressions) and this
+ *   codebase already treats blind x-data rewrites as unsafe (see
+ *   `component-section.tsx`'s `canRebuildAlpineDataLosslessly` bail-out) — the
+ *   swapped-in instance keeps ITS OWN component's default `x-data` as-is.
+ *   Prop names present on the old instance but not declared by the new
+ *   component are dropped (`droppedProps`); prop names the new component
+ *   declares that the old instance didn't override keep the new component's
+ *   default (`defaultedProps`). Both are reported so the caller/UI can tell
+ *   the user what changed.
+ * - The selected instance's own `data-agent-native-node-id` is preserved on
+ *   the swapped-in markup (rather than keeping whatever id the copied
+ *   instance had) so selection, undo, and any other node-id-keyed state keep
+ *   addressing the same slot on the canvas.
+ *
+ * Persists through the same deterministic HTML-patch + collab seam as
+ * `apply-component-prop-edit` (`writeInlineSourceFile` + `expectedVersionHash`
+ * CAS guard) — same undo/collab posture as every other HTML-mutating action.
+ *
+ * Inline/Alpine designs only; real-app sources fail closed.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import { defineAction } from "@agent-native/core/action";
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+import {
+  accessFilter,
+  assertAccess,
+  resolveAccess,
+} from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  writeInlineSourceFile,
+  type SourceWorkspaceFile,
+} from "../server/source-workspace.js";
+import {
+  buildCodeLayerProjection,
+  type CodeLayerNode,
+} from "../shared/code-layer.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import { agentSelectionDescriptor } from "../shared/collab-selection.js";
+import {
+  componentNameFor,
+  componentNodeIdMatches,
+  extractProps,
+  propNameToDataAttribute,
+} from "../shared/component-model.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+import { sourceContentHash } from "../shared/source-workspace.js";
+import { applyRootAttributeEdit } from "./apply-component-prop-edit.js";
+
+// ─── Pure markup helpers ────────────────────────────────────────────────────
+
+/**
+ * Find the end offset (exclusive) of the opening tag at the start of
+ * `markup`, respecting quoted attribute values that may themselves contain
+ * `>`. Returns `markup.length` if no unquoted `>` is found. Pure.
+ */
+export function findOpenTagEnd(markup: string): number {
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < markup.length; i++) {
+    const ch = markup[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ">") return i + 1;
+  }
+  return markup.length;
+}
+
+/**
+ * Set (or replace) a single attribute on a standalone markup string's opening
+ * tag — the same splice `applyRootAttributeEdit` performs against a full
+ * document, but for an already-extracted outerHTML fragment (e.g. copied from
+ * another instance elsewhere in the design). Pure — exported for tests.
+ */
+export function setAttributeOnMarkup(
+  markup: string,
+  attrName: string,
+  attrValue: string,
+): string {
+  const openEnd = findOpenTagEnd(markup);
+  const result = applyRootAttributeEdit(
+    markup,
+    { openStart: 0, openEnd },
+    attrName,
+    attrValue,
+  );
+  return result.content;
+}
+
+export interface SwapOverrideResult {
+  markup: string;
+  overriddenProps: string[];
+  droppedProps: string[];
+  defaultedProps: string[];
+}
+
+/**
+ * Re-key every descendant in markup copied from another component instance.
+ * Keeping the copied `data-agent-native-node-id` values would create duplicate
+ * stable layer identities, so selection and the aggregate layer-owner map
+ * could jump back to the source instance after a swap. The root keeps the
+ * selected instance's id later in `mergeComponentSwapOverrides`; descendants
+ * receive fresh ids here.
+ *
+ * `createNodeId` is injectable so the pure behavior stays deterministic in
+ * tests while production uses cryptographically unique ids.
+ */
+export function reassignCopiedDescendantNodeIds(
+  markup: string,
+  createNodeId: () => string = () => `an-${randomUUID()}`,
+): string {
+  const projection = buildCodeLayerProjection(markup);
+  const rootIds = new Set(projection.rootNodeIds);
+  const descendants = projection.nodes
+    .filter((node) => !rootIds.has(node.id) && node.source)
+    .sort(
+      (a, b) =>
+        (b.source?.openStart ?? Number.NEGATIVE_INFINITY) -
+        (a.source?.openStart ?? Number.NEGATIVE_INFINITY),
+    );
+
+  let content = markup;
+  for (const descendant of descendants) {
+    content = applyRootAttributeEdit(
+      content,
+      descendant.source,
+      "data-agent-native-node-id",
+      createNodeId(),
+    ).content;
+  }
+  return content;
+}
+
+/**
+ * Apply the selected instance's `data-agent-native-prop-*` overrides onto a
+ * copy of the target component's markup, carrying over only prop names the
+ * target component ALSO declares, then stamp the selected instance's stable
+ * node id onto the result. Pure — exported for tests.
+ */
+export function mergeComponentSwapOverrides(
+  targetMarkup: string,
+  currentProps: Array<{ name: string; value: string }>,
+  targetDefaultProps: Array<{ name: string; value: string }>,
+  nodeId: string,
+): SwapOverrideResult {
+  const targetNames = new Set(targetDefaultProps.map((p) => p.name));
+  const currentNames = new Set(currentProps.map((p) => p.name));
+
+  const overriddenProps: string[] = [];
+  const droppedProps: string[] = [];
+  const defaultedProps: string[] = [];
+
+  let markup = reassignCopiedDescendantNodeIds(targetMarkup);
+
+  for (const prop of currentProps) {
+    if (targetNames.has(prop.name)) {
+      markup = setAttributeOnMarkup(
+        markup,
+        propNameToDataAttribute(prop.name),
+        prop.value,
+      );
+      overriddenProps.push(prop.name);
+    } else {
+      droppedProps.push(prop.name);
+    }
+  }
+
+  for (const prop of targetDefaultProps) {
+    if (!currentNames.has(prop.name)) defaultedProps.push(prop.name);
+  }
+
+  markup = setAttributeOnMarkup(markup, "data-agent-native-node-id", nodeId);
+
+  return { markup, overriddenProps, droppedProps, defaultedProps };
+}
+
+// ─── Persistence ────────────────────────────────────────────────────────────
+
+async function persistEdit(file: {
+  id: string;
+  designId: string;
+  filename: string;
+  content: string;
+  expectedVersionHash: string;
+}): Promise<string> {
+  await assertAccess("design", file.designId, "editor");
+
+  agentEnterDocument(file.id);
+  try {
+    const workspaceFile: SourceWorkspaceFile = {
+      id: file.id,
+      designId: file.designId,
+      filename: file.filename,
+      fileType: "html",
+      content: file.content,
+      createdAt: null,
+      updatedAt: null,
+    };
+
+    const result = await writeInlineSourceFile({
+      designId: file.designId,
+      file: workspaceFile,
+      content: file.content,
+      expectedVersionHash: file.expectedVersionHash,
+    });
+
+    return result.updatedAt;
+  } finally {
+    agentLeaveDocument(file.id);
+  }
+}
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description:
+    "Swap a component instance for a different component from elsewhere in " +
+    "the design (Figma's Swap instance). Replaces the selected instance's " +
+    "markup with a copy of another existing instance of targetComponentName, " +
+    "carrying over data-agent-native-prop-* overrides whose prop name exists " +
+    "on both components. x-data (Alpine state) is not merged — the swapped-in " +
+    "instance keeps the target component's own x-data. Requires at least one " +
+    "existing instance of targetComponentName somewhere in the design. " +
+    "Inline/Alpine designs only.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    nodeId: z
+      .string()
+      .describe("data-agent-native-node-id of the component instance to swap"),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Design file id the instance currently lives in; defaults to index.html",
+      ),
+    targetComponentName: z
+      .string()
+      .min(1)
+      .describe(
+        "Name of the component to swap in, from list-design-components",
+      ),
+    source: z
+      .object({
+        currentContent: z
+          .string()
+          .optional()
+          .describe("Latest editor HTML snapshot, when available."),
+        revision: z
+          .string()
+          .optional()
+          .describe(
+            "design_files.updatedAt value the currentContent is based on.",
+          ),
+      })
+      .optional(),
+  }),
+  run: async ({ designId, nodeId, fileId, targetComponentName, source }) => {
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    const rawData = (access.resource as { data?: unknown }).data;
+    const sourceType = designSourceTypeFromData(rawData);
+
+    if (sourceType !== "inline") {
+      return {
+        designId,
+        nodeId,
+        sourceType,
+        swapped: false,
+        ctaRequired: true,
+        ctaMessage:
+          "Swap instance requires a dedicated consented, version-guarded " +
+          "compiled-source transform for real-app sources. Not yet available.",
+      };
+    }
+
+    await assertAccess("design", designId, "editor");
+    const db = getDb();
+
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+      fileId
+        ? eq(schema.designFiles.id, fileId)
+        : eq(schema.designFiles.filename, "index.html"),
+    ];
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+        updatedAt: schema.designFiles.updatedAt,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(and(...conditions))
+      .limit(1);
+
+    if (!file) throw new Error("Design HTML file not found.");
+
+    if (
+      source?.currentContent &&
+      source.revision &&
+      file.updatedAt &&
+      source.revision !== file.updatedAt
+    ) {
+      return {
+        designId,
+        nodeId,
+        swapped: false,
+        conflict: true,
+        fileId: file.id,
+        filename: file.filename,
+        error:
+          "This file changed since this swap was prepared. Refresh the editor and try again.",
+      };
+    }
+
+    const html =
+      typeof source?.currentContent === "string"
+        ? source.currentContent
+        : (file.content ?? "");
+    const baseVersionHash = sourceContentHash(html);
+
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+
+    const projection = buildCodeLayerProjection(html, {
+      source: codeLayerSource,
+    });
+
+    const node = projection.nodes.find((n) =>
+      componentNodeIdMatches(n, nodeId),
+    );
+    if (!node) {
+      throw new Error(
+        `Node "${nodeId}" not found. Run get-code-layer-projection to list current ids.`,
+      );
+    }
+
+    const componentName = componentNameFor(node);
+    if (!componentName) {
+      throw new Error(
+        `Node "${nodeId}" is not a component root (no data-agent-native-component attribute) — nothing to swap.`,
+      );
+    }
+
+    if (componentName === targetComponentName) {
+      return {
+        designId,
+        nodeId,
+        componentName,
+        swapped: false,
+        note: `Already an instance of "${targetComponentName}".`,
+      };
+    }
+
+    if (!node.source) {
+      throw new Error(
+        `Node "${nodeId}" has no resolvable source span; cannot swap.`,
+      );
+    }
+
+    // ── Find a markup source for the target component ──────────────────────
+    const allFiles = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designFiles.designId, designId),
+          eq(schema.designFiles.fileType, "html"),
+        ),
+      )
+      .orderBy(schema.designFiles.createdAt);
+
+    let targetNode: CodeLayerNode | undefined;
+    let targetHtml = "";
+
+    for (const row of allFiles) {
+      const rowHtml = row.id === file.id ? html : (row.content ?? "");
+      if (!rowHtml) continue;
+      const rowProjection =
+        row.id === file.id
+          ? projection
+          : buildCodeLayerProjection(rowHtml, {
+              source: {
+                kind: "design-file",
+                designId: row.designId,
+                fileId: row.id,
+                filename: row.filename,
+              },
+            });
+
+      const match = rowProjection.nodes.find((n) => {
+        if (row.id === file.id && n.id === node.id) return false;
+        return componentNameFor(n) === targetComponentName;
+      });
+
+      if (match) {
+        targetNode = match;
+        targetHtml = rowHtml;
+        break;
+      }
+    }
+
+    if (!targetNode) {
+      throw new Error(
+        `No existing instance of component "${targetComponentName}" found ` +
+          "anywhere in this design. Swap needs at least one existing " +
+          "instance to copy markup from — run list-design-components to see " +
+          "what's available.",
+      );
+    }
+    if (!targetNode.source) {
+      throw new Error(
+        `The matched "${targetComponentName}" instance has no resolvable source span; cannot swap.`,
+      );
+    }
+
+    const targetMarkup = targetHtml.slice(
+      targetNode.source.start,
+      targetNode.source.end,
+    );
+
+    const currentProps = extractProps(node);
+    const targetDefaultProps = extractProps(targetNode);
+
+    const {
+      markup: mergedMarkup,
+      overriddenProps,
+      droppedProps,
+      defaultedProps,
+    } = mergeComponentSwapOverrides(
+      targetMarkup,
+      currentProps,
+      targetDefaultProps,
+      nodeId,
+    );
+
+    const patchedContent =
+      html.slice(0, node.source.start) +
+      mergedMarkup +
+      html.slice(node.source.end);
+
+    if (patchedContent === html) {
+      return {
+        designId,
+        nodeId,
+        componentName,
+        swapped: false,
+        note: "Swap produced no change.",
+      };
+    }
+
+    const updatedAt = await persistEdit({
+      id: file.id,
+      designId: file.designId,
+      filename: file.filename,
+      content: patchedContent,
+      expectedVersionHash: baseVersionHash,
+    });
+
+    agentUpdateSelection(file.id, {
+      selection: agentSelectionDescriptor(
+        { nodeId, selector: node.selector },
+        "Swapping instance",
+      ),
+      nodeId,
+      editingFile: file.filename,
+      designId: file.designId,
+    });
+
+    return {
+      designId,
+      nodeId,
+      fromComponent: componentName,
+      toComponent: targetComponentName,
+      swapped: true,
+      overriddenProps,
+      droppedProps,
+      defaultedProps,
+      fileId: file.id,
+      filename: file.filename,
+      updatedAt,
+      content: patchedContent,
+      note: `Swapped "${componentName}" for "${targetComponentName}".`,
+    };
+  },
+});
diff --git a/templates/design/actions/take-design-screenshot.spec.ts b/templates/design/actions/take-design-screenshot.spec.ts
index ef7b498b10..06bb2afbe6 100644
--- a/templates/design/actions/take-design-screenshot.spec.ts
+++ b/templates/design/actions/take-design-screenshot.spec.ts
@@ -56,6 +56,19 @@ describe("resolveViewports", () => {
       expect(vp.heightPx).toBeGreaterThan(0);
     }
   });
+
+  it("uses an explicit `heights` entry instead of the device heuristic when provided", () => {
+    const viewports = resolveViewports([960], [543]);
+    expect(viewports).toEqual([
+      { label: "desktop-960", widthPx: 960, heightPx: 543 },
+    ]);
+  });
+
+  it("falls back to the device heuristic for indices missing from `heights`", () => {
+    const viewports = resolveViewports([1280, 375], [900]);
+    expect(viewports[0]).toMatchObject({ widthPx: 1280, heightPx: 900 });
+    expect(viewports[1]).toMatchObject({ widthPx: 375, heightPx: 812 });
+  });
 });
 
 // ---------------------------------------------------------------------------
diff --git a/templates/design/actions/take-design-screenshot.ts b/templates/design/actions/take-design-screenshot.ts
index 0050476ef6..399329c7e8 100644
--- a/templates/design/actions/take-design-screenshot.ts
+++ b/templates/design/actions/take-design-screenshot.ts
@@ -125,75 +125,50 @@ function labelForWidth(widthPx: number): string {
   return `desktop-${widthPx}`;
 }
 
-/** Resolve the viewport list from the optional `widths` input, defaulting to desktop + mobile. */
-export function resolveViewports(widths?: number[]): ScreenshotViewport[] {
+/**
+ * Resolve the viewport list from the optional `widths` input, defaulting to
+ * desktop + mobile. `heights`, when provided, is matched index-for-index
+ * against `widths` so a caller that already knows the exact content height
+ * (e.g. the annotate-to-agent draw pipeline compositing over a specific
+ * on-screen rect) gets a screenshot with the same aspect ratio instead of the
+ * device-heuristic default — annotation coordinates are recorded in that
+ * exact rect's pixel space, so a mismatched aspect ratio would misalign the
+ * composited drawing against the screenshot content. A missing/undefined
+ * entry at a given index falls back to `heightForWidth` unchanged, so
+ * existing callers that only pass `widths` are unaffected.
+ */
+export function resolveViewports(
+  widths?: number[],
+  heights?: number[],
+): ScreenshotViewport[] {
   if (!widths || widths.length === 0) return DEFAULT_VIEWPORTS;
-  return widths.map((widthPx) => ({
+  return widths.map((widthPx, index) => ({
     label: labelForWidth(widthPx),
     widthPx,
-    heightPx: heightForWidth(widthPx),
+    heightPx: heights?.[index] || heightForWidth(widthPx),
   }));
 }
 
 // ---------------------------------------------------------------------------
 // Playwright loading (mirrors packages/core/src/cli/recap.ts's runShot: a
 // dynamic import + system-Chrome fallback, so a missing browser binary is a
-// clean, catchable failure rather than an unhandled module-resolution crash)
+// clean, catchable failure rather than an unhandled module-resolution crash).
+// The actual bootstrap lives in `playwright-runtime.ts` so other server-side
+// Chromium consumers (e.g. the Figma SVG export's scene extractor in
+// `design-to-figma-svg.ts`) share it instead of duplicating it; re-exported
+// here for backward compatibility with this file's existing imports/spec.
 // ---------------------------------------------------------------------------
 
-type PlaywrightModule = { chromium: import("@playwright/test").BrowserType };
-
-async function importPlaywright(): Promise<PlaywrightModule> {
-  try {
-    // Bare "playwright" — present when @agent-native/core's optional
-    // dependency resolved (matches how packages/core/src/cli/recap.ts loads
-    // it). Loaded via a non-literal specifier so bundlers don't try to
-    // statically resolve/include it (it's optional and can be entirely
-    // absent, e.g. in a hosted deploy).
-    const specifier = "playwright";
-    return (await import(specifier)) as unknown as PlaywrightModule;
-  } catch {
-    // "@playwright/test" is a direct devDependency of this template (used by
-    // its own e2e suite) and re-exports the same chromium/Browser API.
-    return (await import("@playwright/test")) as unknown as PlaywrightModule;
-  }
-}
-
-const SYSTEM_CHROME_EXECUTABLES = [
-  "/usr/bin/google-chrome-stable",
-  "/usr/bin/google-chrome",
-  "/usr/bin/chromium-browser",
-  "/usr/bin/chromium",
-];
-
-/** Exported for tests — pure classifier for "no Chromium binary available" errors. */
-export function isMissingBrowserError(err: unknown): boolean {
-  const message = err instanceof Error ? err.message : String(err);
-  return /Executable doesn't exist|playwright install|browser.*not found|chromium.*not found/i.test(
-    message,
-  );
-}
-
-async function launchChromium(
-  chromium: import("@playwright/test").BrowserType,
-): Promise<import("@playwright/test").Browser> {
-  const launchOptions = { args: ["--no-sandbox"] };
-  try {
-    return await chromium.launch(launchOptions);
-  } catch (err) {
-    if (!isMissingBrowserError(err)) throw err;
-    const { existsSync } = await import("node:fs");
-    for (const executablePath of SYSTEM_CHROME_EXECUTABLES) {
-      if (!existsSync(executablePath)) continue;
-      try {
-        return await chromium.launch({ ...launchOptions, executablePath });
-      } catch {
-        // Try the next candidate; the original error is rethrown below.
-      }
-    }
-    throw err;
-  }
-}
+export {
+  importPlaywright,
+  isMissingBrowserError,
+  launchChromium,
+} from "../server/lib/playwright-runtime.js";
+import {
+  importPlaywright,
+  launchChromium,
+  type PlaywrightModule,
+} from "../server/lib/playwright-runtime.js";
 
 /** Human-readable, model-actionable message for the "no Chromium available" case. */
 export function chromiumUnavailableReason(err: unknown): string {
@@ -510,10 +485,20 @@ export default defineAction({
         "Viewport widths in px to render. Defaults to [1280, 375] (desktop + mobile). " +
           "Height is derived per width using standard device aspect ratios.",
       ),
+    heights: z
+      .array(z.number().int().min(200).max(4096))
+      .optional()
+      .describe(
+        "Exact viewport heights in px, matched index-for-index against `widths`. " +
+          "Use when the caller needs the screenshot's aspect ratio to match a " +
+          "known on-screen rect exactly (e.g. compositing an overlay on top) " +
+          "instead of the device-heuristic default. Omit an index to fall back " +
+          "to the standard derived height for that width.",
+      ),
   }),
   readOnly: true,
   http: { method: "POST" },
-  run: async ({ designId, fileId, filename, widths }, ctx) => {
+  run: async ({ designId, fileId, filename, widths, heights }, ctx) => {
     if (!designId && !fileId) {
       throw new Error("designId or fileId is required.");
     }
@@ -569,7 +554,7 @@ export default defineAction({
       return { ok: false, reason: chromiumUnavailableReason(err) };
     }
 
-    const viewports = resolveViewports(widths);
+    const viewports = resolveViewports(widths, heights);
     let browser: import("@playwright/test").Browser | undefined;
     try {
       browser = await launchChromium(playwright.chromium);
diff --git a/templates/design/actions/write-local-file.spec.ts b/templates/design/actions/write-local-file.spec.ts
index 2d8d8cd208..380c954de0 100644
--- a/templates/design/actions/write-local-file.spec.ts
+++ b/templates/design/actions/write-local-file.spec.ts
@@ -137,6 +137,50 @@ describe("write-local-file", () => {
     expect(body.expectedVersionHash).toBe("123-456");
   });
 
+  it("enforces and forwards the exact-hash contract for semantic source edits", async () => {
+    await expect(
+      action.run({
+        designId: "design_1",
+        connectionId: "conn_1",
+        relPath: "src/App.tsx",
+        patch: { search: "old", replace: "new" },
+        requireExpectedVersionHash: true,
+      }),
+    ).rejects.toThrow(/expectedVersionHash is required/);
+    expect(fetch).not.toHaveBeenCalled();
+
+    const exactHash = "a".repeat(64);
+    await action.run({
+      designId: "design_1",
+      connectionId: "conn_1",
+      relPath: "src/App.tsx",
+      patch: { search: "old", replace: "new" },
+      expectedVersionHash: exactHash,
+      requireExpectedVersionHash: true,
+    });
+
+    const call = (fetch as unknown as ReturnType<typeof vi.fn>).mock
+      .calls[0] as [string, RequestInit];
+    expect(JSON.parse(call[1].body as string)).toMatchObject({
+      expectedVersionHash: exactHash,
+      requireExpectedVersionHash: true,
+    });
+  });
+
+  it("rejects legacy stat hashes for the exact-hash contract", async () => {
+    await expect(
+      action.run({
+        designId: "design_1",
+        connectionId: "conn_1",
+        relPath: "src/App.tsx",
+        patch: { search: "old", replace: "new" },
+        expectedVersionHash: "123-456",
+        requireExpectedVersionHash: true,
+      }),
+    ).rejects.toThrow(/SHA-256 expectedVersionHash/);
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
   it("throws a version-conflict error on a 409 from the bridge", async () => {
     vi.stubGlobal(
       "fetch",
diff --git a/templates/design/actions/write-local-file.ts b/templates/design/actions/write-local-file.ts
index cfd1d03ae4..a307e93e8e 100644
--- a/templates/design/actions/write-local-file.ts
+++ b/templates/design/actions/write-local-file.ts
@@ -60,6 +60,7 @@ const ALLOWED_EXTENSIONS = new Set([
   ".yaml",
   ".svg",
 ]);
+const SHA256_VERSION_HASH = /^[a-f0-9]{64}$/i;
 
 /**
  * Secret-looking paths are never writable, regardless of extension. All
@@ -207,6 +208,14 @@ export default defineAction({
           "version-conflict error if the file changed on disk since that " +
           "hash was read.",
       ),
+    requireExpectedVersionHash: z
+      .boolean()
+      .optional()
+      .describe(
+        "Set true for semantic/compiled-source edits. The bridge rejects the " +
+          "write unless expectedVersionHash is present and still exact. Leave " +
+          "false only for legacy writes or deliberate new-file creation.",
+      ),
   }),
   run: async ({
     designId,
@@ -215,6 +224,7 @@ export default defineAction({
     content,
     patch,
     expectedVersionHash,
+    requireExpectedVersionHash,
   }) => {
     // --- Gate 1: access ---
     await assertAccess("design", designId, "editor");
@@ -246,6 +256,14 @@ export default defineAction({
         "content and patch are mutually exclusive. Provide one or the other.",
       );
     }
+    if (
+      requireExpectedVersionHash &&
+      (!expectedVersionHash || !SHA256_VERSION_HASH.test(expectedVersionHash))
+    ) {
+      throw new Error(
+        "A SHA-256 expectedVersionHash is required when requireExpectedVersionHash is true. Re-read the file through the current local Design bridge before retrying.",
+      );
+    }
 
     // --- Resolve bridge URL + current token ---
     const db = getDb();
@@ -289,7 +307,12 @@ export default defineAction({
       const res = await fetch(`${bridgeUrl}/write-file`, {
         method: "POST",
         headers,
-        body: JSON.stringify({ relPath, content, expectedVersionHash }),
+        body: JSON.stringify({
+          relPath,
+          content,
+          expectedVersionHash,
+          requireExpectedVersionHash,
+        }),
       });
       if (!res.ok) {
         if (res.status === 409) {
@@ -321,6 +344,7 @@ export default defineAction({
           search: patch!.search,
           replace: patch!.replace,
           expectedVersionHash,
+          requireExpectedVersionHash,
         }),
       });
       if (!applyRes.ok) {
diff --git a/templates/design/app/components/design/CanvasContextMenu.test.tsx b/templates/design/app/components/design/CanvasContextMenu.test.tsx
index 1f45cbddcc..70eaf1826d 100644
--- a/templates/design/app/components/design/CanvasContextMenu.test.tsx
+++ b/templates/design/app/components/design/CanvasContextMenu.test.tsx
@@ -111,3 +111,120 @@ describe("CanvasContextMenu Copy as PNG", () => {
     await view.cleanup();
   });
 });
+
+describe("CanvasContextMenu Select layer", () => {
+  it("renders the ordered hit stack and selects the exact candidate", async () => {
+    const onSelectLayer = vi.fn();
+    const candidates = [
+      {
+        key: "front",
+        label: "Front card",
+        info: {
+          tagName: "div",
+          sourceId: "front",
+          selector: '[data-agent-native-node-id="front"]',
+          classes: [],
+          computedStyles: {},
+          boundingRect: { x: 0, y: 0, width: 100, height: 100 },
+          isFlexChild: false,
+          isFlexContainer: false,
+        },
+      },
+      {
+        key: "parent",
+        label: "Parent frame",
+        info: {
+          tagName: "section",
+          sourceId: "parent",
+          selector: '[data-agent-native-node-id="parent"]',
+          classes: [],
+          computedStyles: {},
+          boundingRect: { x: 0, y: 0, width: 200, height: 200 },
+          isFlexChild: false,
+          isFlexContainer: false,
+        },
+      },
+    ];
+    const view = await renderContextMenu({
+      selectedCount: 1,
+      layerCandidates: candidates,
+      onSelectLayer,
+    });
+
+    expect(view.container.textContent).toContain("Select layer");
+    const buttons = Array.from(view.container.querySelectorAll("button"));
+    const front = buttons.find((button) =>
+      button.textContent?.includes("Front card"),
+    );
+    const parent = buttons.find((button) =>
+      button.textContent?.includes("Parent frame"),
+    );
+    expect(front).toBeDefined();
+    expect(parent).toBeDefined();
+    expect(buttons.indexOf(front!)).toBeLessThan(buttons.indexOf(parent!));
+
+    await act(async () => parent?.click());
+    expect(onSelectLayer).toHaveBeenCalledWith(candidates[1]);
+    await view.cleanup();
+  });
+});
+
+describe("CanvasContextMenu instance cluster (Go to main / Swap / Detach)", () => {
+  it("renders nothing for a non-instance selection (backward compatible default)", async () => {
+    const view = await renderContextMenu({
+      selectedCount: 1,
+      canCreateComponent: true,
+    });
+
+    expect(view.findButton("Go to main component")).toBeUndefined();
+    expect(view.findButton("Swap instance")).toBeUndefined();
+    expect(view.findButton("Detach instance")).toBeUndefined();
+    await view.cleanup();
+  });
+
+  it("renders and wires all three items when isComponentInstance is true", async () => {
+    const onGoToMainComponent = vi.fn();
+    const onSwapInstance = vi.fn();
+    const onDetachInstance = vi.fn();
+    const view = await renderContextMenu({
+      selectedCount: 1,
+      isComponentInstance: true,
+      onGoToMainComponent,
+      onSwapInstance,
+      onDetachInstance,
+    });
+
+    const detachButton = view.findButton("Detach instance");
+    expect(detachButton).toBeDefined();
+    expect(detachButton?.disabled).toBe(false);
+    await act(async () => detachButton?.click());
+    expect(onDetachInstance).toHaveBeenCalledTimes(1);
+    expect(onDetachInstance).toHaveBeenCalledWith(
+      expect.objectContaining({ action: "detach-instance", selectedCount: 1 }),
+    );
+
+    const swapButton = view.findButton("Swap instance");
+    await act(async () => swapButton?.click());
+    expect(onSwapInstance).toHaveBeenCalledTimes(1);
+
+    const mainButton = view.findButton("Go to main component");
+    await act(async () => mainButton?.click());
+    expect(onGoToMainComponent).toHaveBeenCalledTimes(1);
+
+    await view.cleanup();
+  });
+
+  it("disables items whose capability flag is explicitly false", async () => {
+    const onDetachInstance = vi.fn();
+    const view = await renderContextMenu({
+      selectedCount: 1,
+      isComponentInstance: true,
+      canDetachInstance: false,
+      onDetachInstance,
+    });
+
+    const detachButton = view.findButton("Detach instance");
+    expect(detachButton?.disabled).toBe(true);
+    await view.cleanup();
+  });
+});
diff --git a/templates/design/app/components/design/CanvasContextMenu.tsx b/templates/design/app/components/design/CanvasContextMenu.tsx
index 1e45a523ae..39499dc5ad 100644
--- a/templates/design/app/components/design/CanvasContextMenu.tsx
+++ b/templates/design/app/components/design/CanvasContextMenu.tsx
@@ -1,3 +1,10 @@
+import {
+  IconComponents,
+  IconFrame,
+  IconPhoto,
+  IconTypography,
+  IconVector,
+} from "@tabler/icons-react";
 import {
   forwardRef,
   useCallback,
@@ -22,6 +29,8 @@ import {
 } from "@/components/ui/context-menu";
 import { cn } from "@/lib/utils";
 
+import type { CanvasLayerHitCandidate } from "./types";
+
 // LIVE-VERIFIED (real Figma, UI3) canvas context menus:
 //
 // WITH a selection:
@@ -51,6 +60,15 @@ import { cn } from "@/lib/utils";
 // back-compat. App-specific extras with no Figma equivalent (e.g. "Edit
 // screen") are appended at the very bottom, below one more separator, so the
 // Figma-muscle-memory zone above stays byte-identical to the real menu.
+//
+// NOTE — instance-only cluster (Go to main component / Swap instance /
+// Detach instance): added for component-instance selections, gated behind
+// `isComponentInstance` so it renders nothing for existing callers (fully
+// backward compatible). Real Figma groups these together for an instance
+// selection, but this exact placement (right after Add auto layout / Create
+// component) was NOT independently re-verified against a live Figma session
+// in this pass — reposition if a future LIVE-VERIFIED sweep finds a
+// different spot.
 export type CanvasContextMenuAction =
   | "paste-here"
   | "select-all"
@@ -73,6 +91,9 @@ export type CanvasContextMenuAction =
   | "frame-selection"
   | "add-auto-layout"
   | "create-component"
+  | "go-to-main-component"
+  | "swap-instance"
+  | "detach-instance"
   | "rename"
   | "toggle-lock"
   | "toggle-hide"
@@ -112,6 +133,7 @@ export type CanvasContextMenuActionHandler = (
 ) => void;
 
 export interface CanvasContextMenuLabels {
+  selectLayer: string;
   pasteHere: string;
   selectAll: string;
   zoomToFit: string;
@@ -134,6 +156,9 @@ export interface CanvasContextMenuLabels {
   frameSelection: string;
   addAutoLayout: string;
   createComponent: string;
+  goToMainComponent: string;
+  swapInstance: string;
+  detachInstance: string;
   rename: string;
   lock: string;
   unlock: string;
@@ -177,6 +202,9 @@ export interface CanvasContextMenuShortcuts {
   frameSelection: string;
   addAutoLayout: string;
   createComponent: string;
+  goToMainComponent: string;
+  swapInstance: string;
+  detachInstance: string;
   rename: string;
   toggleLock: string;
   toggleHide: string;
@@ -199,6 +227,8 @@ export interface CanvasContextMenuProps {
   className?: string;
   contentClassName?: string;
   selectedCount?: number;
+  layerCandidates?: readonly CanvasLayerHitCandidate[];
+  onSelectLayer?: (candidate: CanvasLayerHitCandidate) => void;
   hasClipboard?: boolean;
   hasPropsClipboard?: boolean;
   hasAnimationClipboard?: boolean;
@@ -228,6 +258,14 @@ export interface CanvasContextMenuProps {
   canFrameSelection?: boolean;
   canAddAutoLayout?: boolean;
   canCreateComponent?: boolean;
+  // Whether the current selection IS a component instance — gates the
+  // whole Go to main component / Swap instance / Detach instance cluster on
+  // (rather than showing them permanently disabled for non-instance
+  // selections, since real Figma doesn't show this cluster at all then).
+  isComponentInstance?: boolean;
+  canGoToMainComponent?: boolean;
+  canSwapInstance?: boolean;
+  canDetachInstance?: boolean;
   // L12: this menu is target-agnostic — it has no built-in notion of "design
   // title" vs "layer". Rename is enabled by default for a single selection
   // (see the canRename default below) and fires through the onRename
@@ -288,6 +326,9 @@ export interface CanvasContextMenuProps {
   onFrameSelection?: CanvasContextMenuActionHandler;
   onAddAutoLayout?: CanvasContextMenuActionHandler;
   onCreateComponent?: CanvasContextMenuActionHandler;
+  onGoToMainComponent?: CanvasContextMenuActionHandler;
+  onSwapInstance?: CanvasContextMenuActionHandler;
+  onDetachInstance?: CanvasContextMenuActionHandler;
   // L12: fired when the Rename item is selected (details.selectedCount tells
   // the caller how many things are selected). The caller decides what
   // "rename" means for the current target — e.g. calling a LayersPanel
@@ -315,6 +356,7 @@ export interface CanvasContextMenuProps {
 }
 
 const DEFAULT_LABELS: CanvasContextMenuLabels = {
+  selectLayer: "Select layer",
   pasteHere: "Paste here",
   selectAll: "Select all",
   zoomToFit: "Zoom to fit",
@@ -337,6 +379,9 @@ const DEFAULT_LABELS: CanvasContextMenuLabels = {
   frameSelection: "Frame selection",
   addAutoLayout: "Add auto layout",
   createComponent: "Create component",
+  goToMainComponent: "Go to main component",
+  swapInstance: "Swap instance",
+  detachInstance: "Detach instance",
   rename: "Rename",
   lock: "Lock",
   unlock: "Unlock",
@@ -380,6 +425,9 @@ const DEFAULT_SHORTCUTS: CanvasContextMenuShortcuts = {
   frameSelection: "⌥⌘G",
   addAutoLayout: "⇧A",
   createComponent: "⌥⌘K",
+  goToMainComponent: "",
+  swapInstance: "",
+  detachInstance: "⌥⌘B",
   rename: "⌘R",
   toggleLock: "⇧⌘L",
   toggleHide: "⇧⌘H",
@@ -426,6 +474,8 @@ export const CanvasContextMenu = forwardRef<
     className,
     contentClassName,
     selectedCount = 0,
+    layerCandidates = [],
+    onSelectLayer,
     hasClipboard = false,
     hasPropsClipboard = false,
     hasAnimationClipboard = false,
@@ -444,6 +494,10 @@ export const CanvasContextMenu = forwardRef<
     canFrameSelection = selectedCount > 0,
     canAddAutoLayout = selectedCount > 0,
     canCreateComponent = selectedCount > 0,
+    isComponentInstance = false,
+    canGoToMainComponent = isComponentInstance,
+    canSwapInstance = isComponentInstance,
+    canDetachInstance = isComponentInstance,
     canRename = selectedCount === 1,
     canToggleLocked = selectedCount > 0,
     canToggleHidden = selectedCount > 0,
@@ -479,6 +533,9 @@ export const CanvasContextMenu = forwardRef<
     onFrameSelection,
     onAddAutoLayout,
     onCreateComponent,
+    onGoToMainComponent,
+    onSwapInstance,
+    onDetachInstance,
     onRename,
     onToggleLocked,
     onToggleHidden,
@@ -559,6 +616,9 @@ export const CanvasContextMenu = forwardRef<
       "frame-selection": onFrameSelection,
       "add-auto-layout": onAddAutoLayout,
       "create-component": onCreateComponent,
+      "go-to-main-component": onGoToMainComponent,
+      "swap-instance": onSwapInstance,
+      "detach-instance": onDetachInstance,
       rename: onRename,
       "toggle-lock": onToggleLocked,
       "toggle-hide": onToggleHidden,
@@ -585,9 +645,11 @@ export const CanvasContextMenu = forwardRef<
       onCopyAsSvg,
       onCopyProps,
       onCreateComponent,
+      onDetachInstance,
       onFlipHorizontal,
       onFlipVertical,
       onFrameSelection,
+      onGoToMainComponent,
       onGroup,
       onPaste,
       onPasteAnimation,
@@ -598,6 +660,7 @@ export const CanvasContextMenu = forwardRef<
       onRename,
       onSendBackward,
       onSendToBack,
+      onSwapInstance,
       onToggleComments,
       onToggleHidden,
       onToggleLocked,
@@ -674,6 +737,32 @@ export const CanvasContextMenu = forwardRef<
         className={cn(MENU_CONTENT_CLASS, contentClassName)}
         style={manualContentStyle}
       >
+        {layerCandidates.length > 0 && onSelectLayer ? (
+          <>
+            <ContextMenuGroup>
+              <ContextMenuSub>
+                <ContextMenuSubTrigger className={MENU_SUB_TRIGGER_CLASS}>
+                  {labels.selectLayer}
+                </ContextMenuSubTrigger>
+                <ContextMenuSubContent
+                  className={cn(MENU_CONTENT_CLASS, "w-56")}
+                >
+                  {layerCandidates.map((candidate) => (
+                    <CanvasLayerCandidateItem
+                      key={candidate.key}
+                      candidate={candidate}
+                      onSelect={() => {
+                        onSelectLayer(candidate);
+                        handleOpenChange(false);
+                      }}
+                    />
+                  ))}
+                </ContextMenuSubContent>
+              </ContextMenuSub>
+            </ContextMenuGroup>
+            <CanvasMenuSeparator />
+          </>
+        ) : null}
         {hasSelection ? (
           <>
             {/* LIVE-VERIFIED Figma "with selection" canvas menu. */}
@@ -839,6 +928,39 @@ export const CanvasContextMenu = forwardRef<
               />
             </ContextMenuGroup>
 
+            {isComponentInstance ? (
+              <>
+                <CanvasMenuSeparator />
+                <ContextMenuGroup>
+                  <CanvasMenuItem
+                    hidden={isHiddenAction("go-to-main-component")}
+                    disabled={
+                      !canRun("go-to-main-component", canGoToMainComponent)
+                    }
+                    label={labels.goToMainComponent}
+                    shortcut={shortcuts.goToMainComponent}
+                    onSelect={(event) =>
+                      runAction("go-to-main-component", event)
+                    }
+                  />
+                  <CanvasMenuItem
+                    hidden={isHiddenAction("swap-instance")}
+                    disabled={!canRun("swap-instance", canSwapInstance)}
+                    label={labels.swapInstance}
+                    shortcut={shortcuts.swapInstance}
+                    onSelect={(event) => runAction("swap-instance", event)}
+                  />
+                  <CanvasMenuItem
+                    hidden={isHiddenAction("detach-instance")}
+                    disabled={!canRun("detach-instance", canDetachInstance)}
+                    label={labels.detachInstance}
+                    shortcut={shortcuts.detachInstance}
+                    onSelect={(event) => runAction("detach-instance", event)}
+                  />
+                </ContextMenuGroup>
+              </>
+            ) : null}
+
             <CanvasMenuSeparator />
 
             <ContextMenuGroup>
@@ -936,6 +1058,36 @@ export const CanvasContextMenu = forwardRef<
   );
 });
 
+function CanvasLayerCandidateItem({
+  candidate,
+  onSelect,
+}: {
+  candidate: CanvasLayerHitCandidate;
+  onSelect: () => void;
+}) {
+  const tag = candidate.info.tagName.toLowerCase();
+  const Icon = candidate.info.componentName
+    ? IconComponents
+    : /^(h[1-6]|p|span|label|input|textarea)$/.test(tag)
+      ? IconTypography
+      : /^(img|picture|video)$/.test(tag)
+        ? IconPhoto
+        : /^(svg|path|circle|ellipse|polygon|line)$/.test(tag)
+          ? IconVector
+          : tag === "button" || tag === "a"
+            ? IconComponents
+            : IconFrame;
+  return (
+    <ContextMenuItem
+      className={cn(MENU_ITEM_CLASS, "gap-2")}
+      onSelect={onSelect}
+    >
+      <Icon className="size-3.5 shrink-0 text-muted-foreground" />
+      <span className="min-w-0 truncate">{candidate.label}</span>
+    </ContextMenuItem>
+  );
+}
+
 function CanvasMenuItem({
   hidden,
   disabled,
diff --git a/templates/design/app/components/design/DesignCanvas.bridge-restart.test.tsx b/templates/design/app/components/design/DesignCanvas.bridge-restart.test.tsx
new file mode 100644
index 0000000000..e32bcc6210
--- /dev/null
+++ b/templates/design/app/components/design/DesignCanvas.bridge-restart.test.tsx
@@ -0,0 +1,379 @@
+// @vitest-environment happy-dom
+//
+// Behavioral coverage for the live-edit bridge auto-reconnect decision logic
+// (see the classifyLiveEditHealthProbe doc comment in DesignCanvas.tsx). The
+// authenticated live-edit iframe is a real cross-origin navigation, so this
+// component can never read a 409 "unknown-bridge-key" response body directly
+// — it instead watches for the missing agent-native:editor-chrome-ready
+// handshake and probes /health to compare bridgeInstanceId. These tests drive
+// that flow end-to-end through mocked fetch responses rather than importing
+// the (intentionally unexported, see DesignCanvas.refreshBoundary.test.ts)
+// pure decision function directly.
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { DesignCanvas } from "./DesignCanvas";
+
+vi.mock("@agent-native/core/client", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("@agent-native/core/client")>();
+  return {
+    ...original,
+    useT: () => (key: string) => key,
+  };
+});
+
+const BRIDGE_URL = "http://127.0.0.1:7331";
+const PREVIEW_TOKEN = "preview-token";
+const PREVIEW_URL = "http://localhost:5173/forms";
+
+function jsonResponse(body: unknown, status = 200) {
+  return Promise.resolve({
+    ok: status >= 200 && status < 300,
+    status,
+    json: () => Promise.resolve(body),
+  } as Response);
+}
+
+async function flushMicrotasks(times = 8) {
+  for (let i = 0; i < times; i += 1) {
+    await Promise.resolve();
+  }
+}
+
+describe("DesignCanvas live-edit bridge restart detection", () => {
+  let container: HTMLDivElement;
+  let root: ReturnType<typeof createRoot>;
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    vi.useFakeTimers();
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  async function renderLiveEditCanvas() {
+    await act(async () => {
+      root.render(
+        <DesignCanvas
+          content={PREVIEW_URL}
+          contentKey="screen-a"
+          screenId="screen-a"
+          sourceType="localhost"
+          bridgeUrl={BRIDGE_URL}
+          previewToken={PREVIEW_TOKEN}
+          zoom={100}
+          deviceFrame="none"
+          interactMode={false}
+          editMode
+          readOnly={false}
+          onElementSelect={() => {}}
+          onElementHover={() => {}}
+          tweakValues={{}}
+        />,
+      );
+    });
+    await act(async () => {
+      await flushMicrotasks();
+    });
+  }
+
+  function healthCallCount() {
+    return fetchMock.mock.calls.filter(([input]) =>
+      String(input).startsWith(`${BRIDGE_URL}/health`),
+    ).length;
+  }
+
+  function registrationCallCount() {
+    return fetchMock.mock.calls.filter(([input]) =>
+      String(input).startsWith(`${BRIDGE_URL}/live-edit-bridge`),
+    ).length;
+  }
+
+  function postReadyHandshake(source?: Window) {
+    const iframeWindow =
+      source ?? container.querySelector("iframe")?.contentWindow;
+    if (!iframeWindow) {
+      throw new Error("expected a live-edit iframe window");
+    }
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        data: { type: "agent-native:editor-chrome-ready" },
+        origin: BRIDGE_URL,
+        source: iframeWindow,
+      }),
+    );
+  }
+
+  it("silently re-registers and reloads the frame when /health reports a different bridgeInstanceId (bridge process restarted)", async () => {
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.startsWith(`${BRIDGE_URL}/live-edit-bridge`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-1" });
+      }
+      if (url.startsWith(`${BRIDGE_URL}/health`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-2" });
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+
+    await renderLiveEditCanvas();
+
+    const registrationCallsBeforeTimeout = registrationCallCount();
+    expect(registrationCallsBeforeTimeout).toBe(1);
+
+    // No agent-native:editor-chrome-ready message ever arrives (simulating
+    // the bridge injecting nothing because it 409'd on the real navigation) —
+    // advance past the ready-handshake watchdog window.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(4200);
+      await flushMicrotasks();
+    });
+
+    const registrationCallsAfterTimeout = registrationCallCount();
+    // A second registration POST fired automatically — the silent
+    // re-register/reload path — without ever surfacing an error.
+    expect(registrationCallsAfterTimeout).toBeGreaterThanOrEqual(2);
+    expect(container.textContent ?? "").not.toContain(
+      "Live editor connection failed",
+    );
+  });
+
+  it("does NOT tear down the iframe or show an error when /health reports the SAME bridgeInstanceId at the first 4s timeout — it re-arms the watchdog instead (regression coverage)", async () => {
+    // /health always confirms the bridge process is the one we registered
+    // with — a slow-but-healthy dev server (e.g. a 6-10s cold compile), not a
+    // real failure. Before the fix under test, this used to be indistinguishable
+    // from a genuine unknown-bridge-key bug and immediately tore the iframe
+    // down (setRegisteredLiveEditBridgeKey(null)), flashing "Live editor
+    // connection failed" under a load that was still legitimately in flight.
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.startsWith(`${BRIDGE_URL}/live-edit-bridge`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-1" });
+      }
+      if (url.startsWith(`${BRIDGE_URL}/health`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-1" });
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+
+    await renderLiveEditCanvas();
+    expect(registrationCallCount()).toBe(1);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(4200);
+      await flushMicrotasks();
+    });
+
+    // Exactly one /health probe fired so far, and NEITHER error card is
+    // shown. Crucially, no second registration POST fired either — a
+    // same-instance-id "escalate" outcome must never touch
+    // registeredLiveEditBridgeKey/reload the frame the way a genuine restart
+    // ("reregister") does.
+    expect(healthCallCount()).toBe(1);
+    expect(registrationCallCount()).toBe(1);
+    expect(container.textContent ?? "").not.toContain(
+      "Live editor connection failed",
+    );
+    expect(container.textContent ?? "").not.toContain("Preparing live editor");
+    const iframeSrc = container.querySelector("iframe")?.getAttribute("src");
+    expect(iframeSrc).toContain("/live-edit");
+
+    // Advance past the re-armed (longer, ~8s) wait: the watchdog must probe
+    // /health again on its own rather than giving up after one attempt.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(8200);
+      await flushMicrotasks();
+    });
+    expect(healthCallCount()).toBeGreaterThanOrEqual(2);
+    expect(registrationCallCount()).toBe(1);
+    expect(container.textContent ?? "").not.toContain(
+      "Live editor connection failed",
+    );
+  });
+
+  it("surfaces a NON-destructive error once the same-instance-id escalation ceiling is exceeded, without nulling registeredLiveEditBridgeKey — and a late ready handshake still clears it", async () => {
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.startsWith(`${BRIDGE_URL}/live-edit-bridge`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-1" });
+      }
+      if (url.startsWith(`${BRIDGE_URL}/health`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-1" });
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+
+    await renderLiveEditCanvas();
+
+    // Escalation schedule: 4s, +8s, +16s, +16s, +16s (capped) — cumulative
+    // wait crosses the ~48s ceiling on the 5th probe, around the 60s mark.
+    // Advance in the same per-step chunks the real schedule uses (rather
+    // than one huge jump) so each nested setTimeout scheduled from inside the
+    // previous probe's async continuation is reliably due before the next
+    // advance runs.
+    for (const stepMs of [4200, 8200, 16200, 16200, 16200]) {
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(stepMs);
+        await flushMicrotasks();
+      });
+    }
+
+    // The non-destructive card renders (same title copy as the destructive
+    // card, since both describe the same user-facing situation), but the
+    // live-edit iframe was never torn down: its src still points at the real
+    // /live-edit document, not the blank "Preparing..." placeholder.
+    expect(container.textContent ?? "").toContain(
+      "Live editor connection failed",
+    );
+    expect(container.textContent ?? "").not.toContain("Preparing live editor");
+    const iframeSrc = container.querySelector("iframe")?.getAttribute("src");
+    expect(iframeSrc).toContain("/live-edit");
+    // No reregistration ever happened — this was a stalled-but-healthy same
+    // process the whole time, never a genuine restart.
+    expect(registrationCallCount()).toBe(1);
+
+    // A late ready handshake still wins: the still-loading document finally
+    // finished, and the error card must clear rather than staying stuck.
+    await act(async () => {
+      postReadyHandshake();
+      await flushMicrotasks();
+    });
+    expect(container.textContent ?? "").not.toContain(
+      "Live editor connection failed",
+    );
+  });
+
+  it("tears down the iframe and surfaces the destructive error when /health itself is unreachable (dev server actually down)", async () => {
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.startsWith(`${BRIDGE_URL}/live-edit-bridge`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-1" });
+      }
+      if (url.startsWith(`${BRIDGE_URL}/health`)) {
+        return Promise.reject(new Error("network error probing /health"));
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+
+    await renderLiveEditCanvas();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(4200);
+      await flushMicrotasks();
+    });
+
+    // /health being unreachable means the dev server process is genuinely
+    // down, not just slow — this destructive path (tear down + surface the
+    // error) is unchanged and still correct here.
+    expect(container.textContent ?? "").toContain(
+      "Live editor connection failed",
+    );
+    expect(container.textContent ?? "").toContain(
+      "Is the local dev server still running?",
+    );
+  });
+
+  it("recovers from a destructive watchdog error when the exact retired live document posts ready late", async () => {
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.startsWith(`${BRIDGE_URL}/live-edit-bridge`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-1" });
+      }
+      if (url.startsWith(`${BRIDGE_URL}/health`)) {
+        return Promise.reject(new Error("temporary health probe failure"));
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+
+    await renderLiveEditCanvas();
+    const liveIframe = container.querySelector("iframe");
+    const retiredLiveWindow = liveIframe?.contentWindow;
+    expect(retiredLiveWindow).toBeTruthy();
+    expect(liveIframe?.getAttribute("src")).toContain("/live-edit");
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(4200);
+      await flushMicrotasks();
+    });
+
+    expect(container.textContent ?? "").toContain(
+      "Live editor connection failed",
+    );
+    expect(container.querySelector("iframe")?.getAttribute("src")).toBeNull();
+
+    // Window identity is part of the recovery token: an otherwise well-formed
+    // ready packet from another same-origin window cannot revive the key.
+    await act(async () => {
+      postReadyHandshake(window);
+      await flushMicrotasks();
+    });
+    expect(container.textContent ?? "").toContain(
+      "Live editor connection failed",
+    );
+
+    // The live document that the watchdog retired had already queued ready.
+    // Its exact WindowProxy + bridge-key generation is allowed to restore the
+    // registration, clearing both the error and the pending placeholder.
+    await act(async () => {
+      postReadyHandshake(retiredLiveWindow!);
+      await flushMicrotasks();
+    });
+    expect(container.textContent ?? "").not.toContain(
+      "Live editor connection failed",
+    );
+    expect(container.textContent ?? "").not.toContain("Preparing live editor");
+    expect(container.querySelector("iframe")?.getAttribute("src")).toContain(
+      "/live-edit",
+    );
+  });
+
+  it("does not loop forever when the bridge never confirms (attempt cap)", async () => {
+    // /health always reports a fresh, distinct instance id — a pathological
+    // bridge that appears to restart on every single probe. The retry budget
+    // (MAX_LIVE_EDIT_RESTART_ATTEMPTS) must still cut this off with a visible
+    // error rather than polling forever.
+    let healthCallCounter = 0;
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.startsWith(`${BRIDGE_URL}/live-edit-bridge`)) {
+        return jsonResponse({ ok: true, bridgeInstanceId: "instance-1" });
+      }
+      if (url.startsWith(`${BRIDGE_URL}/health`)) {
+        healthCallCounter += 1;
+        return jsonResponse({
+          ok: true,
+          bridgeInstanceId: `instance-restart-${healthCallCounter}`,
+        });
+      }
+      throw new Error(`unexpected fetch: ${url}`);
+    });
+
+    await renderLiveEditCanvas();
+
+    // Fire the watchdog repeatedly — each cycle re-registers, remounts, and
+    // (since ready never arrives) times out again.
+    for (let cycle = 0; cycle < 6; cycle += 1) {
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(4200);
+        await flushMicrotasks();
+      });
+    }
+
+    expect(container.textContent ?? "").toContain(
+      "Live editor connection failed",
+    );
+  });
+});
diff --git a/templates/design/app/components/design/DesignCanvas.creation-overlay.test.ts b/templates/design/app/components/design/DesignCanvas.creation-overlay.test.ts
index 8926c40ccf..68be056695 100644
--- a/templates/design/app/components/design/DesignCanvas.creation-overlay.test.ts
+++ b/templates/design/app/components/design/DesignCanvas.creation-overlay.test.ts
@@ -57,6 +57,37 @@ describe("getScreenContentPointFromClient", () => {
     );
     expect(point).toEqual({ x: 100, y: 50 });
   });
+
+  it("lands a shape at the correct content position on a scrolled screen (unscaled)", () => {
+    // A click 25px into an unzoomed iframe, with the embedded screen
+    // scrolled 600px down internally, must resolve to content y = 620 —
+    // matching where that click actually landed in the full document, not
+    // just the currently-visible viewport slice.
+    const point = getScreenContentPointFromClient(
+      325,
+      420,
+      { left: 300, top: 400, width: 800, height: 600 },
+      { width: 800, height: 600 },
+      { left: 0, top: 600 },
+    );
+    expect(point).toEqual({ x: 25, y: 620 });
+  });
+
+  it("adds a scrolled screen's scroll offset unscaled, not divided by the outer zoom", () => {
+    // 50% host zoom (rect half the content size). A click at the iframe's
+    // top edge on a screen scrolled 600px down must map to content y = 600:
+    // the (clientY - rect.top) term is 0 here, so the entire result comes
+    // from the scroll offset, proving it is added as-is rather than being
+    // divided by scale (which would wrongly give 1200).
+    const point = getScreenContentPointFromClient(
+      100,
+      50,
+      { left: 100, top: 50, width: 400, height: 300 },
+      { width: 800, height: 600 },
+      { left: 0, top: 600 },
+    );
+    expect(point).toEqual({ x: 0, y: 600 });
+  });
 });
 
 describe("collapseDoubleClickPenAnchor", () => {
diff --git a/templates/design/app/components/design/DesignCanvas.embedded-frame-live.test.tsx b/templates/design/app/components/design/DesignCanvas.embedded-frame-live.test.tsx
new file mode 100644
index 0000000000..c73f849ba1
--- /dev/null
+++ b/templates/design/app/components/design/DesignCanvas.embedded-frame-live.test.tsx
@@ -0,0 +1,150 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+
+import { DesignCanvas } from "./DesignCanvas";
+
+vi.mock("@agent-native/core/client", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("@agent-native/core/client")>();
+  return {
+    ...original,
+    useT: () => (key: string) => key,
+  };
+});
+
+describe("DesignCanvas live embedded-frame offset", () => {
+  it("keeps the iframe identity stable when a board render window reanchors", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const root = createRoot(container);
+    const content = `<!doctype html><html><body><div data-agent-native-node-id="shape" style="position:absolute;left:-165px;top:-90px;width:84px;height:76px"></div></body></html>`;
+
+    const render = (offset: number) => (
+      <DesignCanvas
+        content={content}
+        contentKey="board:surface"
+        screenId="board"
+        zoom={100}
+        deviceFrame="none"
+        interactMode
+        onElementSelect={() => {}}
+        onElementHover={() => {}}
+        tweakValues={{}}
+        boardSurface
+        editMode={false}
+        embeddedFrame={{
+          viewportWidth: 8192,
+          viewportHeight: 8192,
+          displayWidth: 8192,
+          displayHeight: 8192,
+          fluid: true,
+          contentOffsetX: offset,
+          contentOffsetY: offset,
+        }}
+      />
+    );
+
+    try {
+      await act(async () => root.render(render(4096)));
+      const before = container.querySelector<HTMLIFrameElement>(
+        "iframe[data-design-preview-iframe]",
+      );
+      expect(before).not.toBeNull();
+      expect(before!.srcdoc).toContain("translate:4096px 4096px");
+
+      await act(async () => root.render(render(8192)));
+      const after = container.querySelector<HTMLIFrameElement>(
+        "iframe[data-design-preview-iframe]",
+      );
+      expect(after).toBe(before);
+      // srcdoc intentionally stays keyed to the existing browsing context;
+      // the live offset effect updates the document/bridge in place.
+      expect(after!.srcdoc).toContain("translate:4096px 4096px");
+      const liveOffsetStyle = after!.contentDocument?.querySelector(
+        "style[data-agent-native-content-offset]",
+      );
+      if (liveOffsetStyle) {
+        expect(liveOffsetStyle.textContent).toContain(
+          "translate:8192px 8192px",
+        );
+      }
+    } finally {
+      await act(async () => root.unmount());
+      container.remove();
+    }
+  });
+
+  it("queues and deduplicates runtime structure move requests until the bridge is ready", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const root = createRoot(container);
+    const request = {
+      requestId: 41,
+      subject: {
+        selector: ".repeated",
+        sourceId: "runtime-subject",
+      },
+      anchor: {
+        selector: ".repeated",
+        sourceId: "runtime-anchor",
+      },
+      placement: "inside" as const,
+    };
+    const render = (runtimeRequest: typeof request | null) => (
+      <DesignCanvas
+        content="<!doctype html><html><body></body></html>"
+        contentKey="runtime-structure"
+        runtimeStructureMoveRequest={runtimeRequest}
+        screenId="screen-a"
+        zoom={100}
+        deviceFrame="none"
+        interactMode={false}
+        onElementSelect={() => {}}
+        onElementHover={() => {}}
+        tweakValues={{}}
+        editMode
+      />
+    );
+
+    try {
+      await act(async () => root.render(render(null)));
+      const iframe = container.querySelector<HTMLIFrameElement>(
+        "iframe[data-design-preview-iframe]",
+      );
+      expect(iframe?.contentWindow).toBeTruthy();
+      const postMessage = vi.spyOn(iframe!.contentWindow!, "postMessage");
+
+      await act(async () => root.render(render(request)));
+      await act(async () => {
+        iframe!.dispatchEvent(new Event("load"));
+      });
+
+      const expected = {
+        type: "runtime-structure-move",
+        subjectSelector: ".repeated",
+        subjectSourceId: "runtime-subject",
+        anchorSelector: ".repeated",
+        anchorSourceId: "runtime-anchor",
+        placement: "inside",
+      };
+      expect(postMessage).toHaveBeenCalledWith(expected, "*");
+
+      const matchingCallsBefore = postMessage.mock.calls.filter(
+        ([message]) =>
+          (message as { type?: string }).type === "runtime-structure-move",
+      ).length;
+      await act(async () => root.render(render(request)));
+      const matchingCallsAfter = postMessage.mock.calls.filter(
+        ([message]) =>
+          (message as { type?: string }).type === "runtime-structure-move",
+      ).length;
+      expect(matchingCallsAfter).toBe(matchingCallsBefore);
+    } finally {
+      await act(async () => root.unmount());
+      container.remove();
+    }
+  });
+});
diff --git a/templates/design/app/components/design/DesignCanvas.localhost-preview.test.tsx b/templates/design/app/components/design/DesignCanvas.localhost-preview.test.tsx
index e9bf089e65..77d7b4532c 100644
--- a/templates/design/app/components/design/DesignCanvas.localhost-preview.test.tsx
+++ b/templates/design/app/components/design/DesignCanvas.localhost-preview.test.tsx
@@ -47,6 +47,127 @@ afterEach(async () => {
 });
 
 describe("DesignCanvas authenticated localhost source hydration", () => {
+  it("hands a successful overview registration to Full view without a placeholder reload or URL-only frame", async () => {
+    iframeServer = http.createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      response.end("<!doctype html><html><body>Live chat</body></html>");
+    });
+    const iframePort = await new Promise<number>((resolve, reject) => {
+      iframeServer!.once("error", reject);
+      iframeServer!.listen(0, "127.0.0.1", () => {
+        const address = iframeServer!.address();
+        resolve(typeof address === "object" && address ? address.port : 0);
+      });
+    });
+    const bridgeUrl = `http://127.0.0.1:${iframePort}`;
+    const previewUrl = "http://localhost:5173/chat";
+    let resolveSecondRegistration!: (response: Response) => void;
+    const secondRegistration = new Promise<Response>((resolve) => {
+      resolveSecondRegistration = resolve;
+    });
+    let registrationCount = 0;
+    const fetchMock = vi.fn((input: RequestInfo | URL) => {
+      const url = requestInfoUrl(input);
+      if (!url.endsWith("/live-edit-bridge")) {
+        return Promise.reject(new Error(`Unexpected fetch: ${url}`));
+      }
+      registrationCount += 1;
+      if (registrationCount === 1) {
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({ ok: true, bridgeInstanceId: "instance-1" }),
+            { status: 200, headers: { "content-type": "application/json" } },
+          ),
+        );
+      }
+      return secondRegistration;
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const renderCanvas = async (overview: boolean) => {
+      await act(async () => {
+        root.render(
+          <DesignCanvas
+            content={previewUrl}
+            contentKey="screen-chat"
+            screenId="screen-chat"
+            sourceType="localhost"
+            bridgeUrl={bridgeUrl}
+            previewToken="handoff-preview-token"
+            externalSnapshotHtml="<!doctype html><html><body><main>Chat preview</main></body></html>"
+            zoom={100}
+            deviceFrame="none"
+            embeddedFrame={
+              overview
+                ? {
+                    viewportWidth: 390,
+                    viewportHeight: 844,
+                    displayWidth: 390,
+                    displayHeight: 844,
+                  }
+                : undefined
+            }
+            editMode
+            interactMode={false}
+            onElementSelect={() => {}}
+            onElementHover={() => {}}
+            tweakValues={{}}
+          />,
+        );
+      });
+    };
+
+    await renderCanvas(true);
+    await vi.waitFor(() => {
+      expect(
+        container.querySelector<HTMLIFrameElement>(
+          "[data-design-preview-iframe]",
+        )?.src,
+      ).toContain("/live-edit?");
+    });
+
+    await act(async () => root.unmount());
+    root = createRoot(container);
+    await renderCanvas(false);
+
+    // The second registration is deliberately unresolved. Full view must
+    // still mount the one real live-edit URL immediately from the successful
+    // overview handoff, never an empty srcdoc that is replaced later.
+    const focusedIframe = container.querySelector<HTMLIFrameElement>(
+      "[data-design-preview-iframe]",
+    );
+    expect(focusedIframe?.getAttribute("src")).toContain("/live-edit?");
+    expect(focusedIframe?.getAttribute("srcdoc")).toBeNull();
+    const fallback = container.querySelector<HTMLIFrameElement>(
+      "[data-live-edit-transition-fallback]",
+    );
+    expect(fallback?.getAttribute("srcdoc")).toContain("Chat preview");
+    expect(fallback?.getAttribute("srcdoc")).not.toBe(previewUrl);
+
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          data: { type: "agent-native:editor-chrome-ready" },
+          origin: bridgeUrl,
+          source: focusedIframe?.contentWindow,
+        }),
+      );
+    });
+    expect(
+      container.querySelector("[data-live-edit-transition-fallback]"),
+    ).toBeNull();
+    expect(container.querySelector("[data-design-preview-iframe]")).toBe(
+      focusedIframe,
+    );
+
+    resolveSecondRegistration(
+      new Response(
+        JSON.stringify({ ok: true, bridgeInstanceId: "instance-1" }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
+    );
+  });
+
   it("hydrates source HTML in parallel without replacing the keyed live iframe", async () => {
     iframeServer = http.createServer((_request, response) => {
       response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
diff --git a/templates/design/app/components/design/DesignCanvas.refreshBoundary.test.ts b/templates/design/app/components/design/DesignCanvas.refreshBoundary.test.ts
index 4895769c05..12123bdcec 100644
--- a/templates/design/app/components/design/DesignCanvas.refreshBoundary.test.ts
+++ b/templates/design/app/components/design/DesignCanvas.refreshBoundary.test.ts
@@ -19,10 +19,19 @@ describe("DesignCanvas Fast Refresh boundary", () => {
     const hasModifier = (statement: ts.Statement, kind: ts.SyntaxKind) =>
       ts.canHaveModifiers(statement) &&
       Boolean(ts.getModifiers(statement)?.some((item) => item.kind === kind));
+    // Type-only declarations (interfaces, type aliases) are erased entirely
+    // during compilation — they produce zero runtime exports, so an
+    // `export interface`/`export type` can never affect the Fast Refresh
+    // component boundary this test actually guards. Only count statements
+    // that still exist at runtime after TypeScript strips types.
+    const isTypeOnlyDeclaration = (statement: ts.Statement) =>
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement);
     const exportedStatements = sourceFile.statements.filter(
       (statement) =>
-        ts.isExportDeclaration(statement) ||
-        hasModifier(statement, ts.SyntaxKind.ExportKeyword),
+        !isTypeOnlyDeclaration(statement) &&
+        (ts.isExportDeclaration(statement) ||
+          hasModifier(statement, ts.SyntaxKind.ExportKeyword)),
     );
 
     expect(exportedStatements).toHaveLength(1);
diff --git a/templates/design/app/components/design/DesignCanvas.tsx b/templates/design/app/components/design/DesignCanvas.tsx
index 633d4c6d25..14498f476a 100644
--- a/templates/design/app/components/design/DesignCanvas.tsx
+++ b/templates/design/app/components/design/DesignCanvas.tsx
@@ -14,6 +14,7 @@ import {
   createSmoothNode,
   isPenCloseTarget,
   serializePenPath,
+  translatePenPath,
   type PenPath,
   type PenPoint,
 } from "@shared/pen-path";
@@ -31,7 +32,7 @@ import {
   CanvasCommentPins,
   type CanvasPin,
 } from "@/components/visual-editor";
-import { sendToDesignAgentChat } from "@/lib/agent-chat";
+import { sendToDesignAgentChatAndConfirm } from "@/lib/agent-chat";
 import { cn } from "@/lib/utils";
 
 import { editorChromeBridgeScript } from "../../../.generated/bridge/editor-chrome.generated";
@@ -43,6 +44,7 @@ import { shaderRuntimeBridgeScript } from "../../../.generated/bridge/shader-run
 import { tweakBridgeScript } from "../../../.generated/bridge/tweak.generated";
 import { zoomBridgeScript } from "../../../.generated/bridge/zoom.generated";
 import { isTrustedCanvasBridgeMessage } from "./bridge-security";
+import { captureAnnotatedScreenshot } from "./design-canvas/annotation-snapshot";
 import { submitDesignAnnotations } from "./design-canvas/annotation-submit";
 import {
   getScreenContentPointFromClient,
@@ -55,6 +57,7 @@ import {
 } from "./design-canvas/creation";
 import { isElementInfoPayload } from "./design-canvas/element-payload";
 import {
+  embeddedContentOffsetCss,
   embeddedContentOffsetStyle,
   getEmbeddedFrameBackgroundStyle,
   getEmbeddedFrameDocumentContent,
@@ -91,6 +94,7 @@ import type {
   ElementInfo,
   ElementSelectionIntent,
   DeviceFrameType,
+  RuntimeStructureMoveRequest,
 } from "./types";
 
 /**
@@ -320,6 +324,10 @@ interface DesignCanvasProps {
     status?: number;
     contentType?: string;
   }) => void;
+  onRuntimeLayerSnapshot?: (snapshot: {
+    html: string;
+    nodeCount: number;
+  }) => void;
   /**
    * Explicit Builder-hosted app URL for fusion source rendering.
    *
@@ -381,6 +389,8 @@ interface DesignCanvasProps {
     requestId: number;
     acks: Array<{ requestId: string; applied: boolean }>;
   } | null;
+  /** One-shot host request to optimistically move a runtime-only layer. */
+  runtimeStructureMoveRequest?: RuntimeStructureMoveRequest | null;
   embeddedFrameBackground?: string;
   transparentBackground?: boolean;
   editorChromeScaleX?: number;
@@ -432,8 +442,10 @@ interface DesignCanvasProps {
       anchorSourceId?: string;
       requestId?: string;
       dropMode?: "flow-insert" | "absolute-container";
+      forceFlowPositionOverride?: boolean;
       sourceRect?: { x: number; y: number; width: number; height: number };
       anchorRect?: { x: number; y: number; width: number; height: number };
+      anchorElementInfo?: ElementInfo;
     },
   ) => boolean | "pending" | void;
   onVisualDuplicateChange?: (
@@ -452,6 +464,20 @@ interface DesignCanvasProps {
   drawMode?: boolean;
   /** Called when the user exits draw mode (X / Escape / after Send). */
   onExitDrawMode?: () => void;
+  /**
+   * Bumped by the parent exactly when the user deliberately discards the
+   * current annotation batch (the same moment `onExitDrawMode` fires from
+   * the overlay's own X button or a confirmed Send). SharedDrawOverlay only
+   * clears its strokes/text annotations when this changes — NOT merely
+   * because `drawMode` toggled off for some other reason (switching tools,
+   * views, or side panels) — so unsent annotation work survives an
+   * unrelated exit instead of being silently discarded.
+   */
+  drawOverlayResetSignal?: number;
+  /** Keeps the active focused overlay bitmap alive across mode/view hides. */
+  retainDrawOverlayWhenHidden?: boolean;
+  /** Reports focused annotation delivery state so global Escape stays inert too. */
+  onAnnotationSendingChange?: (sending: boolean) => void;
   /** Whether comment-pin drop mode is active. */
   pinMode?: boolean;
   /**
@@ -685,6 +711,120 @@ function snapshotEndpointUrl(bridgeUrl: string, previewUrl: string): string {
   return endpoint.toString();
 }
 
+function healthEndpointUrl(bridgeUrl: string): string {
+  return new URL("/health", bridgeUrl).toString();
+}
+
+/**
+ * Classifies a suspected `unknown-bridge-key` failure on the localhost
+ * live-edit bridge, based on a `/health` probe fired when the
+ * "agent-native:editor-chrome-ready" handshake hasn't arrived in time.
+ *
+ * The bridge mints a fresh `bridgeInstanceId` every time its process boots
+ * (see `startDesignConnectBridge` in packages/core/src/cli/design-connect.ts)
+ * and echoes it on `/health`, on a successful `/live-edit-bridge`
+ * registration, and on the "unknown bridge key" 409 from `/live-edit`. The
+ * 409 itself is usually unreadable here: the live iframe navigates directly
+ * to the bridge's `/live-edit` URL (a real cross-origin request), so this
+ * component can't inspect the response body or status code the way a
+ * same-origin `fetch` could. Instead, callers probe `/health` — a route that
+ * never requires the preview token — and pass its `bridgeInstanceId` in as
+ * `responseBridgeInstanceId`.
+ *
+ * - Different id than what we last registered with ⇒ the bridge PROCESS
+ *   restarted (crash, machine sleep/wake, manual restart) since our last
+ *   successful registration. That's not a caller bug: silently re-POST the
+ *   same script/key and reload the frame with no user-facing error
+ *   ("reregister").
+ * - Same id ⇒ the process that accepted our registration is still running
+ *   and reachable — the iframe just hasn't finished loading yet (e.g. a
+ *   6-10s cold dev-server compile), NOT a genuine failure. Callers must NOT
+ *   tear the iframe down for this outcome: re-arm the ready-handshake
+ *   watchdog with a longer wait instead ("escalate") — see
+ *   handleSuspectedBridgeRestart's escalation loop, which only gives up and
+ *   shows a (non-destructive) error after a generous total ceiling.
+ * - No id at all (missing from either side) ⇒ inconclusive — `/health`
+ *   responded but we can't confirm process identity either way. Treat this
+ *   like a real, unresolved failure and surface the existing error/Retry UI
+ *   ("error").
+ *
+ * Deliberately NOT exported: every other pure helper in this file
+ * (getExternalPreviewUrl, snapshotEndpointUrl, buildEditorChromeBridgeScript,
+ * contentHash, isAllowedFusionOrigin, originFromUrl, ...) stays module-private
+ * so DesignCanvas.tsx keeps exporting only the DesignCanvas component itself
+ * — see DesignCanvas.refreshBoundary.test.ts, which guards the Fast Refresh
+ * boundary this file relies on given how often it's edited during live design
+ * sessions. Its decision logic is covered by behavioral tests in
+ * DesignCanvas.bridge-restart.test.tsx instead of a direct unit import.
+ */
+function classifyLiveEditHealthProbe(
+  cachedBridgeInstanceId: string | null | undefined,
+  responseBridgeInstanceId: string | null | undefined,
+): "reregister" | "escalate" | "error" {
+  if (!cachedBridgeInstanceId || !responseBridgeInstanceId) return "error";
+  return cachedBridgeInstanceId === responseBridgeInstanceId
+    ? "escalate"
+    : "reregister";
+}
+
+// Grace period after the live-edit bridge is (re)registered and the real
+// iframe document is mounted before a missing "agent-native:editor-chrome-ready"
+// handshake is treated as a suspected bridge restart rather than an in-flight
+// page load. Generous relative to typical localhost load times so a slow but
+// healthy dev server is never misdiagnosed as restarted.
+const LIVE_EDIT_READY_TIMEOUT_MS = 4000;
+// Caps the silent auto-reregister loop below so a pathological bridge that
+// keeps minting a new bridgeInstanceId on every probe (or that never manages
+// to actually register) can't retry forever without ever surfacing an error.
+const MAX_LIVE_EDIT_RESTART_ATTEMPTS = 3;
+// When a /health probe confirms the SAME bridgeInstanceId as last registered
+// (bridge process healthy, page just slow to post ready), each re-arm of the
+// watchdog waits longer than the last — 4s, 8s, 16s — capped here so the
+// backoff doesn't grow unbounded on a very long-running compile.
+const LIVE_EDIT_SAME_INSTANCE_MAX_REARM_DELAY_MS = 16_000;
+// Total cumulative time to keep silently re-arming on a same-instance-id
+// "still healthy" response before finally surfacing a non-destructive error
+// affordance. Generous relative to even a slow cold dev-server compile so a
+// genuinely-loading page is never misdiagnosed as failed; a legitimately
+// long compile that finishes after this point still clears the error the
+// moment the ready handshake arrives (see the message-handler branch below).
+const LIVE_EDIT_SAME_INSTANCE_ERROR_CEILING_MS = 48_000;
+
+// Successful bridge registrations belong to the localhost bridge process,
+// not to one React DesignCanvas instance. Overview -> Full view currently
+// replaces the overview canvas component with a focused canvas component; a
+// component-local registration flag made that transition mount an empty
+// srcdoc first and then replace it with the live URL after an identical POST.
+// Keep a deliberately short handoff cache so the focused instance can mount
+// the already-registered live document exactly once. A stale entry during
+// HMR is harmless: the ready watchdog probes the bridge instance and silently
+// re-registers, while the ready-gated fallback below prevents blank content.
+const LIVE_EDIT_REGISTRATION_HANDOFF_TTL_MS = 30_000;
+const liveEditRegistrationHandoff = new Map<string, number>();
+
+function liveEditRegistrationHandoffKey(
+  bridgeUrl: string | undefined,
+  bridgeKey: string,
+): string | null {
+  if (!bridgeUrl) return null;
+  try {
+    return `${new URL(bridgeUrl).origin}|${bridgeKey}`;
+  } catch {
+    return null;
+  }
+}
+
+function hasRecentLiveEditRegistration(key: string | null): boolean {
+  if (!key) return false;
+  const registeredAt = liveEditRegistrationHandoff.get(key);
+  if (registeredAt === undefined) return false;
+  if (Date.now() - registeredAt <= LIVE_EDIT_REGISTRATION_HANDOFF_TTL_MS) {
+    return true;
+  }
+  liveEditRegistrationHandoff.delete(key);
+  return false;
+}
+
 function originFromUrl(value: string | undefined): string | null {
   if (!value) return null;
   try {
@@ -701,6 +841,9 @@ function buildEditorChromeBridgeScript(args: {
   editorChromeScaleY: number;
   screenId: string;
   boardSurface: boolean;
+  contentOffsetX: number;
+  contentOffsetY: number;
+  runtimeLayerSnapshotEnabled: boolean;
 }) {
   return (
     createEditorBridgeThemeScript(readEditorBridgeThemeVars()) +
@@ -716,6 +859,18 @@ function buildEditorChromeBridgeScript(args: {
         "__DESIGN_CANVAS_BOARD_SURFACE__",
         args.boardSurface ? "true" : "false",
       )
+      .replace(
+        "__DESIGN_CANVAS_CONTENT_OFFSET_X__",
+        String(Math.round(args.contentOffsetX)),
+      )
+      .replace(
+        "__DESIGN_CANVAS_CONTENT_OFFSET_Y__",
+        String(Math.round(args.contentOffsetY)),
+      )
+      .replace(
+        "__RUNTIME_LAYER_SNAPSHOT_ENABLED__",
+        args.runtimeLayerSnapshotEnabled ? "true" : "false",
+      )
   );
 }
 
@@ -727,6 +882,29 @@ function contentHash(value: string): string {
   return `${value.length}:${hash >>> 0}`;
 }
 
+/**
+ * Safely reads an embedded screen iframe's own internal document scroll
+ * position, in the iframe's own unscaled content pixels — the same units
+ * `getScreenContentPointFromClient`'s `scrollOffset` param folds in. Inline
+ * (srcdoc) screens are same-origin, so the happy path below is the common
+ * case, but externally-hosted localhost/fusion previews can be cross-origin,
+ * and `contentWindow.scrollX`/`scrollY` THROWS (it is not merely
+ * `undefined`) when accessed cross-origin. Always degrade to `{0, 0}` rather
+ * than letting that throw escape into a render or event handler.
+ */
+function readIframeScrollOffset(iframe: HTMLIFrameElement | null | undefined): {
+  left: number;
+  top: number;
+} {
+  try {
+    const win = iframe?.contentWindow;
+    if (!win) return { left: 0, top: 0 };
+    return { left: win.scrollX || 0, top: win.scrollY || 0 };
+  } catch {
+    return { left: 0, top: 0 };
+  }
+}
+
 export function DesignCanvas({
   content,
   contentKey,
@@ -734,6 +912,7 @@ export function DesignCanvas({
   bridgeUrl,
   externalSnapshotHtml,
   onExternalContentSnapshot,
+  onRuntimeLayerSnapshot,
   fusionUrl,
   previewToken,
   zoom,
@@ -747,6 +926,7 @@ export function DesignCanvas({
   styleBaselineResetRequest,
   textRevertRequest,
   structureAckRequest,
+  runtimeStructureMoveRequest,
   embeddedFrameBackground,
   transparentBackground = false,
   editorChromeScaleX = 1,
@@ -773,6 +953,9 @@ export function DesignCanvas({
   tweakValues,
   drawMode,
   onExitDrawMode,
+  drawOverlayResetSignal,
+  retainDrawOverlayWhenHidden = false,
+  onAnnotationSendingChange,
   pinMode,
   commentPinsHidden,
   selectedSelector,
@@ -847,6 +1030,8 @@ export function DesignCanvas({
   // fallback for older/interact-mode documents that never inject the chrome
   // bridge and thus never post ready) and flush in order.
   const bridgeReadyRef = useRef(false);
+  const [readyIframeDocumentIdentity, setReadyIframeDocumentIdentity] =
+    useState<string | null>(null);
   const previousIframeDocumentIdentityRef = useRef<string | null>(null);
   const pendingOneShotMessagesRef = useRef<unknown[]>([]);
   const flushPendingOneShotMessages = useCallback(() => {
@@ -861,8 +1046,11 @@ export function DesignCanvas({
   const postOneShotBridgeMessage = useCallback((message: unknown) => {
     const iframe = iframeRef.current;
     const win = iframe?.contentWindow;
-    if (!win) return false;
-    if (!bridgeReadyRef.current) {
+    // A one-shot prop can arrive in the same render that first creates the
+    // iframe. Keep it queued even when the ref/contentWindow is not attached
+    // yet; otherwise the effect records its request id as handled and the
+    // command is lost permanently before the bridge can announce readiness.
+    if (!win || !bridgeReadyRef.current) {
       pendingOneShotMessagesRef.current.push(message);
       return true;
     }
@@ -872,6 +1060,12 @@ export function DesignCanvas({
   const [renderedContent, setRenderedContent] = useState(content);
   const [annotationPins, setAnnotationPins] = useState<CanvasPin[]>([]);
   const [pinSubmitSignal, setPinSubmitSignal] = useState(0);
+  // True while a drawing send is capturing/compositing/uploading the
+  // annotated screenshot (see design-canvas/annotation-snapshot.ts). Drives
+  // SharedDrawOverlay's busy Send state so a slow capture can't be triggered
+  // twice from the same drawing.
+  const [annotationCaptureBusy, setAnnotationCaptureBusy] = useState(false);
+  const annotationCaptureBusyRef = useRef(false);
   const [fetchedExternalSnapshot, setFetchedExternalSnapshot] = useState<{
     url: string;
     html: string;
@@ -891,6 +1085,83 @@ export function DesignCanvas({
   // manual retry click (see handleManualSnapshotRetry) so the next failure
   // starts the backoff over rather than continuing to climb.
   const snapshotRetryAttemptRef = useRef(0);
+  // Mirrors the snapshot fetch's own retry/error state above: the
+  // /live-edit-bridge registration POST used to have no retry/backoff or
+  // error surface at all — a transient failure (dev server hiccup, brief
+  // network blip) left registeredLiveEditBridgeKey stuck at null forever,
+  // which pins waitingForLiveEditBridge true and the user stares at
+  // "Preparing live editor..." with no explanation and no way to recover
+  // short of reloading the whole page.
+  const bridgeRegistrationRetryAttemptRef = useRef(0);
+  const [bridgeRegistrationRetryNonce, setBridgeRegistrationRetryNonce] =
+    useState(0);
+  const [bridgeRegistrationError, setBridgeRegistrationError] = useState<{
+    bridgeKey: string;
+    message: string;
+  } | null>(null);
+  // Cache of the bridgeInstanceId returned by the client's LAST successful
+  // /live-edit-bridge registration POST (see the registration effect below).
+  // Compared against a later /health probe's bridgeInstanceId to tell "the
+  // bridge process restarted since we registered" apart from "the same
+  // process really doesn't know this key" — see classifyLiveEditHealthProbe
+  // above.
+  const bridgeInstanceIdRef = useRef<string | null>(null);
+  // A destructive watchdog outcome replaces the live iframe with the neutral
+  // pending document. The live document can still have queued its ready
+  // handshake immediately before that replacement; once unmounted, its
+  // WindowProxy no longer equals iframeRef.current.contentWindow and would be
+  // rejected by the normal bridge trust check. Preserve exactly that retired
+  // generation so its late ready can restore the matching bridge key. Both
+  // source-window identity and bridge-key identity must match, preventing a
+  // stale document from reviving a different screen/script generation.
+  const lateLiveEditReadyRecoveryRef = useRef<{
+    source: Window;
+    bridgeKey: string;
+    registrationHandoffKey: string | null;
+  } | null>(null);
+  // Guards the auto-reregister probe below against overlapping runs and bounds
+  // how many times it will silently retry before giving up and surfacing the
+  // existing error/Retry UI (MAX_LIVE_EDIT_RESTART_ATTEMPTS). This budget is
+  // specific to the "reregister" (different bridgeInstanceId, genuine bridge
+  // restart) loop — the same-instance-id "escalate" loop below has its own,
+  // separate ceiling and does not consume this budget.
+  const liveEditRestartInFlightRef = useRef(false);
+  const liveEditRestartAttemptRef = useRef(0);
+  // Same-instance-id ("escalate") loop state: how long we've cumulatively
+  // waited on THIS bridge key while /health keeps confirming the bridge
+  // process is healthy, the current per-arm wait, and the pending re-arm
+  // timer (so it can be cancelled on ready/unmount/key-change). See
+  // handleSuspectedBridgeRestart and classifyLiveEditHealthProbe above.
+  const liveEditSameInstanceElapsedMsRef = useRef(0);
+  const liveEditSameInstanceDelayRef = useRef(LIVE_EDIT_READY_TIMEOUT_MS);
+  const liveEditSameInstanceRearmTimerRef = useRef<number | undefined>(
+    undefined,
+  );
+  // Non-destructive counterpart to bridgeRegistrationError: shown as an
+  // overlay error/Retry card WITHOUT nulling registeredLiveEditBridgeKey, so
+  // the still-loading iframe is never torn down while it's shown. Only set
+  // once the same-instance-id escalation loop above exceeds its ceiling; a
+  // late ready handshake clears it (see the message-handler branch below).
+  const [
+    liveEditSameInstanceStalledError,
+    setLiveEditSameInstanceStalledError,
+  ] = useState<{
+    bridgeKey: string;
+    message: string;
+  } | null>(null);
+  // Set on unmount so the async /health probe (and its escalation re-arm
+  // timer) never touches state after this component is gone.
+  const isUnmountedRef = useRef(false);
+  useEffect(
+    () => () => {
+      isUnmountedRef.current = true;
+      if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+        window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+        liveEditSameInstanceRearmTimerRef.current = undefined;
+      }
+    },
+    [],
+  );
   const onExternalContentSnapshotRef = useRef(onExternalContentSnapshot);
   const isEmbeddedFrame = Boolean(embeddedFrame);
   // Resolve the URL to render in the iframe:
@@ -912,6 +1183,10 @@ export function DesignCanvas({
     }
     return getExternalPreviewUrl(renderedContent);
   }, [fusionUrl, renderedContent, sourceType]);
+  const runtimeLayerSnapshotEnabled =
+    sourceType === "localhost" &&
+    Boolean(rawExternalPreviewUrl) &&
+    Boolean(onRuntimeLayerSnapshot);
   const activeExternalSnapshotHtml =
     externalSnapshotHtml ??
     (fetchedExternalSnapshot?.url === rawExternalPreviewUrl
@@ -921,6 +1196,21 @@ export function DesignCanvas({
   // registered with the localhost bridge via a large POST, so folding live zoom
   // in would re-fire the registration effect on every zoom tick. Live scale is
   // pushed separately over the `set-editor-chrome-scale` postMessage below.
+  //
+  // readOnly and editMode are ALSO intentionally excluded from the deps below
+  // (only read for their FIRST-render baked value) — mirroring the srcdoc
+  // useMemo's own "readOnly and editMode are intentionally NOT deps" comment
+  // for inline screens further down this file. Before this fix, this memo
+  // (unlike the inline srcdoc one) DID list them as deps: every readOnly/
+  // editMode change rebuilt this script, which changed liveEditBridgeKey
+  // (its contentHash), which is embedded in the localhost iframe's `src` via
+  // resolveLiveEditPreviewUrl — so a routine Edit ⇄ Preview toggle (or a
+  // canEditDesign permission flip) forced a real cross-origin navigation of
+  // the embedded dev-server iframe, losing its in-app route/scroll/state.
+  // Live readOnly/editMode changes flow through the set-read-only and
+  // set-text-editing-enabled postMessages (see the useEffects below) exactly
+  // like the inline path, so no live-update behavior is lost by removing
+  // them here.
   const editorChromeBridgeForCurrentState = useMemo(
     () =>
       buildEditorChromeBridgeScript({
@@ -930,19 +1220,24 @@ export function DesignCanvas({
         editorChromeScaleY: 1,
         screenId: screenId ?? contentKey ?? "",
         boardSurface,
+        contentOffsetX: embeddedFrame?.contentOffsetX ?? 0,
+        contentOffsetY: embeddedFrame?.contentOffsetY ?? 0,
+        runtimeLayerSnapshotEnabled,
       }),
-    [boardSurface, contentKey, editMode, readOnly, screenId],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [boardSurface, contentKey, runtimeLayerSnapshotEnabled, screenId],
   );
+  // Keep the installed gesture script identical between overview and focused
+  // mode. The live flags are posted below; baking `isEmbeddedFrame` into the
+  // script changed the bridge key during Full view and defeated the
+  // registration handoff cache, forcing an avoidable iframe navigation.
   const embeddedGestureBridgeForCurrentState = useMemo(
     () =>
       EMBEDDED_WHEEL_BRIDGE_SCRIPT.replace(
         "__EMBEDDED_WHEEL_FORWARDING_ENABLED__",
-        isEmbeddedFrame ? "true" : "false",
-      ).replace(
-        "__EMBEDDED_SPACE_KEY_FORWARDING_ENABLED__",
-        interactMode || readOnly ? "true" : "false",
-      ),
-    [interactMode, isEmbeddedFrame, readOnly],
+        "false",
+      ).replace("__EMBEDDED_SPACE_KEY_FORWARDING_ENABLED__", "false"),
+    [],
   );
   const includeLiveEditEditorChrome = !interactMode && !readOnly;
   const liveEditBridgeScript = useMemo(
@@ -966,6 +1261,10 @@ export function DesignCanvas({
     () => contentHash(liveEditBridgeScript),
     [liveEditBridgeScript],
   );
+  const registrationHandoffKey = liveEditRegistrationHandoffKey(
+    bridgeUrl,
+    liveEditBridgeKey,
+  );
   const hasLiveEditExternalFrame =
     sourceType === "localhost" && Boolean(bridgeUrl && rawExternalPreviewUrl);
   const hasAuthenticatedLiveEditExternalFrame =
@@ -975,9 +1274,14 @@ export function DesignCanvas({
     Boolean(bridgeUrl && previewToken && rawExternalPreviewUrl);
   const usesLiveEditEditorBridge =
     usesLiveEditInjectedBridge && includeLiveEditEditorChrome;
+  const effectiveRegisteredLiveEditBridgeKey =
+    registeredLiveEditBridgeKey ??
+    (hasRecentLiveEditRegistration(registrationHandoffKey)
+      ? liveEditBridgeKey
+      : null);
   const liveEditBridgeRegistered =
     usesLiveEditInjectedBridge &&
-    registeredLiveEditBridgeKey === liveEditBridgeKey;
+    effectiveRegisteredLiveEditBridgeKey === liveEditBridgeKey;
   // The live iframe and the editable source model are deliberately separate:
   // render exactly one authenticated /live-edit document while fetching
   // /snapshot in parallel so DesignEditor patches real HTML rather than the
@@ -995,7 +1299,7 @@ export function DesignCanvas({
     previewToken,
     previewUrl: rawExternalPreviewUrl,
     bridgeKey: liveEditBridgeKey,
-    registeredBridgeKey: registeredLiveEditBridgeKey,
+    registeredBridgeKey: effectiveRegisteredLiveEditBridgeKey,
   });
   const iframeRenderContent =
     !hasAuthenticatedLiveEditExternalFrame && activeExternalSnapshotHtml
@@ -1024,16 +1328,45 @@ export function DesignCanvas({
 
   // Register the editor bridge script with the localhost live-edit bridge so
   // it gets injected into the proxied preview. Re-runs only when the script
-  // content (liveEditBridgeKey) or the bridge target changes.
+  // content (liveEditBridgeKey) or the bridge target changes (or a retry —
+  // auto or manual — bumps bridgeRegistrationRetryNonce).
+  //
+  // Mirrors the external-source-snapshot fetch effect's own retry/backoff:
+  // a transient failure used to leave registeredLiveEditBridgeKey stuck at
+  // null forever (console.warn only, no retry, no error UI), pinning
+  // waitingForLiveEditBridge true with no way to recover short of a full
+  // page reload.
   useEffect(() => {
     if (!usesLiveEditInjectedBridge || !bridgeUrl || !previewToken) {
+      bridgeRegistrationRetryAttemptRef.current = 0;
+      liveEditRestartAttemptRef.current = 0;
+      liveEditSameInstanceElapsedMsRef.current = 0;
+      liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+      if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+        window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+        liveEditSameInstanceRearmTimerRef.current = undefined;
+      }
       setRegisteredLiveEditBridgeKey(null);
+      setBridgeRegistrationError(null);
+      setLiveEditSameInstanceStalledError(null);
+      lateLiveEditReadyRecoveryRef.current = null;
       return;
     }
     let cancelled = false;
+    let retryTimer: number | undefined;
     setRegisteredLiveEditBridgeKey((current) =>
       current === liveEditBridgeKey ? current : null,
     );
+    const scheduleRetry = () => {
+      if (cancelled) return;
+      const delay = getSnapshotRetryDelayMs(
+        bridgeRegistrationRetryAttemptRef.current,
+      );
+      bridgeRegistrationRetryAttemptRef.current += 1;
+      retryTimer = window.setTimeout(() => {
+        setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
+      }, delay);
+    };
     void (async () => {
       const endpoint = new URL("/live-edit-bridge", bridgeUrl).toString();
       try {
@@ -1051,25 +1384,320 @@ export function DesignCanvas({
         if (!response.ok) {
           throw new Error(`Bridge registration failed (${response.status})`);
         }
-        if (!cancelled) setRegisteredLiveEditBridgeKey(liveEditBridgeKey);
+        const payload = (await response.json().catch(() => null)) as {
+          bridgeInstanceId?: string;
+        } | null;
+        if (payload && typeof payload.bridgeInstanceId === "string") {
+          // Cache the instance id from THIS successful registration so a
+          // later suspected-restart probe (see handleSuspectedBridgeRestart)
+          // can tell a genuinely restarted bridge process apart from the same
+          // process rejecting a stale key.
+          bridgeInstanceIdRef.current = payload.bridgeInstanceId;
+        }
+        if (cancelled) return;
+        bridgeRegistrationRetryAttemptRef.current = 0;
+        if (registrationHandoffKey) {
+          liveEditRegistrationHandoff.set(registrationHandoffKey, Date.now());
+        }
+        // liveEditRestartAttemptRef is intentionally NOT reset here: a
+        // successful registration POST only proves the bridge accepted the
+        // script, not that the live document actually loaded it (that's what
+        // the ready-handshake watchdog below still has to confirm). Resetting
+        // the restart budget on every registration success — rather than only
+        // on a genuine agent-native:editor-chrome-ready — would let a
+        // pathological bridge that keeps minting a new bridgeInstanceId
+        // reregister forever, defeating MAX_LIVE_EDIT_RESTART_ATTEMPTS.
+        setBridgeRegistrationError(null);
+        lateLiveEditReadyRecoveryRef.current = null;
+        setRegisteredLiveEditBridgeKey(liveEditBridgeKey);
       } catch (error) {
         if (!cancelled) {
+          if (registrationHandoffKey) {
+            liveEditRegistrationHandoff.delete(registrationHandoffKey);
+          }
           console.warn("live-edit bridge registration failed", error);
           setRegisteredLiveEditBridgeKey(null);
+          setBridgeRegistrationError({
+            bridgeKey: liveEditBridgeKey,
+            message: error instanceof Error ? error.message : String(error),
+          });
+          scheduleRetry();
         }
       }
     })();
     return () => {
       cancelled = true;
+      if (retryTimer) window.clearTimeout(retryTimer);
     };
   }, [
+    bridgeRegistrationRetryNonce,
     bridgeUrl,
     liveEditBridgeKey,
     liveEditBridgeScript,
     previewToken,
+    registrationHandoffKey,
     usesLiveEditInjectedBridge,
   ]);
 
+  // A liveEditBridgeKey change means the registered script content changed
+  // (different screen, mode, or scale bake) — a completely new registration
+  // target. Reset the reregister-attempt budget and the same-instance-id
+  // escalation state (elapsed wait, backoff delay, pending re-arm timer, and
+  // any stalled-error card) so a previous screen's exhausted retries/backoff
+  // never leak into this new screen's fresh watchdog cycle. Deliberately
+  // separate from the watchdog-arm effect below, which resets the escalation
+  // state on every successful (re)registration INCLUDING same-key reregister
+  // cycles — liveEditRestartAttemptRef must NOT reset on those, or the
+  // MAX_LIVE_EDIT_RESTART_ATTEMPTS budget it guards would never trip (see
+  // that effect's own comment).
+  useEffect(() => {
+    liveEditRestartAttemptRef.current = 0;
+    liveEditSameInstanceElapsedMsRef.current = 0;
+    liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+    if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+      window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+      liveEditSameInstanceRearmTimerRef.current = undefined;
+    }
+    setLiveEditSameInstanceStalledError(null);
+    lateLiveEditReadyRecoveryRef.current = null;
+  }, [liveEditBridgeKey]);
+
+  // Manual retry (offline-state "Retry" button): reset the backoff so the
+  // user-initiated attempt fires immediately, mirroring
+  // handleManualSnapshotRetry below. Also clears the non-destructive
+  // same-instance-id stalled-error card and its escalation state, since a
+  // manual retry (from either error card) should start every counter fresh.
+  const handleManualBridgeRegistrationRetry = useCallback(() => {
+    bridgeRegistrationRetryAttemptRef.current = 0;
+    liveEditRestartAttemptRef.current = 0;
+    liveEditSameInstanceElapsedMsRef.current = 0;
+    liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+    if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+      window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+      liveEditSameInstanceRearmTimerRef.current = undefined;
+    }
+    setLiveEditSameInstanceStalledError(null);
+    setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
+  }, []);
+
+  // The registered iframe's `src` is a real cross-origin navigation straight
+  // to the bridge's authenticated /live-edit URL, so this component can never
+  // read that response's status or body (a 409 "unknown-bridge-key" looks
+  // identical to any other document from here). What IS observable is
+  // whether the editor-chrome bridge's "agent-native:editor-chrome-ready"
+  // handshake (see the message handler below) arrives within a reasonable
+  // window after we mounted the real document. A healthy load posts ready
+  // almost immediately; a 409 never injects the bridge script at all, so
+  // ready never arrives. Treat a stuck non-ready state as a suspected restart
+  // and settle it with a /health probe instead of guessing from the error UI.
+  const handleSuspectedBridgeRestart = useCallback(async () => {
+    if (!bridgeUrl || !previewToken) return;
+    if (liveEditRestartInFlightRef.current) return;
+    liveEditRestartInFlightRef.current = true;
+    try {
+      const response = await fetch(healthEndpointUrl(bridgeUrl));
+      const payload = (await response.json().catch(() => null)) as {
+        bridgeInstanceId?: string;
+      } | null;
+      if (isUnmountedRef.current) return;
+      const responseBridgeInstanceId =
+        payload && typeof payload.bridgeInstanceId === "string"
+          ? payload.bridgeInstanceId
+          : null;
+      const decision = classifyLiveEditHealthProbe(
+        bridgeInstanceIdRef.current,
+        responseBridgeInstanceId,
+      );
+      if (decision === "reregister") {
+        if (
+          liveEditRestartAttemptRef.current >= MAX_LIVE_EDIT_RESTART_ATTEMPTS
+        ) {
+          if (registrationHandoffKey) {
+            liveEditRegistrationHandoff.delete(registrationHandoffKey);
+          }
+          const lateReadySource = iframeRef.current?.contentWindow;
+          lateLiveEditReadyRecoveryRef.current = lateReadySource
+            ? {
+                source: lateReadySource,
+                bridgeKey: liveEditBridgeKey,
+                registrationHandoffKey,
+              }
+            : null;
+          setRegisteredLiveEditBridgeKey(null);
+          setBridgeRegistrationError({
+            bridgeKey: liveEditBridgeKey,
+            message: t("designCanvas.localBridge.confirmationRetryExhausted"),
+          });
+          return;
+        }
+        liveEditRestartAttemptRef.current += 1;
+        if (registrationHandoffKey) {
+          liveEditRegistrationHandoff.delete(registrationHandoffKey);
+        }
+        // The bridge process restarted since our last registration — silently
+        // re-POST the same script/key and reload the frame. Resetting
+        // registeredLiveEditBridgeKey (without setting an error) re-arms the
+        // "Preparing live editor..." placeholder — the same neutral state
+        // already shown on first connect — and bumping the retry nonce
+        // re-triggers the registration effect above.
+        bridgeInstanceIdRef.current = responseBridgeInstanceId;
+        setRegisteredLiveEditBridgeKey(null);
+        setBridgeRegistrationError(null);
+        setLiveEditSameInstanceStalledError(null);
+        // A genuine restart makes any same-instance-id wait we'd accumulated
+        // against the OLD process meaningless — reset the escalation clock so
+        // the fresh document this reregister produces gets the full ceiling,
+        // not whatever was left over from the previous one.
+        liveEditSameInstanceElapsedMsRef.current = 0;
+        liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+        if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+          window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+          liveEditSameInstanceRearmTimerRef.current = undefined;
+        }
+        setBridgeRegistrationRetryNonce((nonce) => nonce + 1);
+        return;
+      }
+      if (decision === "escalate") {
+        // Same bridge process, still healthy and reachable — the page is
+        // just slow (e.g. a cold dev-server compile), not actually failing.
+        // Do NOT touch registeredLiveEditBridgeKey or bridgeRegistrationError
+        // here: that would tear down the still-legitimately-loading iframe
+        // (the regression this fix addresses). Re-arm with a longer wait
+        // instead, up to a generous total ceiling, before finally surfacing a
+        // separate NON-destructive error card that leaves the iframe alone.
+        liveEditSameInstanceElapsedMsRef.current +=
+          liveEditSameInstanceDelayRef.current;
+        if (
+          liveEditSameInstanceElapsedMsRef.current >=
+          LIVE_EDIT_SAME_INSTANCE_ERROR_CEILING_MS
+        ) {
+          setLiveEditSameInstanceStalledError({
+            bridgeKey: liveEditBridgeKey,
+            message: t("designCanvas.localBridge.connectionNotConfirmed"),
+          });
+          return;
+        }
+        const nextDelay = Math.min(
+          liveEditSameInstanceDelayRef.current * 2,
+          LIVE_EDIT_SAME_INSTANCE_MAX_REARM_DELAY_MS,
+        );
+        liveEditSameInstanceDelayRef.current = nextDelay;
+        if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+          window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+        }
+        liveEditSameInstanceRearmTimerRef.current = window.setTimeout(() => {
+          liveEditSameInstanceRearmTimerRef.current = undefined;
+          if (isUnmountedRef.current || bridgeReadyRef.current) return;
+          void handleSuspectedBridgeRestart();
+        }, nextDelay);
+        return;
+      }
+      // decision === "error": no bridgeInstanceId on one or both sides, so we
+      // can't confirm the same-process-still-healthy story above. Treat this
+      // as a genuine, unresolved failure and surface the existing
+      // (destructive) error/Retry UI instead of looping forever.
+      if (registrationHandoffKey) {
+        liveEditRegistrationHandoff.delete(registrationHandoffKey);
+      }
+      const lateReadySource = iframeRef.current?.contentWindow;
+      lateLiveEditReadyRecoveryRef.current = lateReadySource
+        ? {
+            source: lateReadySource,
+            bridgeKey: liveEditBridgeKey,
+            registrationHandoffKey,
+          }
+        : null;
+      setRegisteredLiveEditBridgeKey(null);
+      setBridgeRegistrationError({
+        bridgeKey: liveEditBridgeKey,
+        message: t("designCanvas.localBridge.connectionNotConfirmed"),
+      });
+    } catch (error) {
+      if (isUnmountedRef.current) return;
+      // /health itself is unreachable (network error / thrown before a
+      // response) — the dev server process is actually down, not just slow.
+      // This destructive path (tear down + surface the error) is justified.
+      if (registrationHandoffKey) {
+        liveEditRegistrationHandoff.delete(registrationHandoffKey);
+      }
+      const lateReadySource = iframeRef.current?.contentWindow;
+      lateLiveEditReadyRecoveryRef.current = lateReadySource
+        ? {
+            source: lateReadySource,
+            bridgeKey: liveEditBridgeKey,
+            registrationHandoffKey,
+          }
+        : null;
+      setRegisteredLiveEditBridgeKey(null);
+      setBridgeRegistrationError({
+        bridgeKey: liveEditBridgeKey,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      liveEditRestartInFlightRef.current = false;
+    }
+  }, [bridgeUrl, liveEditBridgeKey, previewToken, registrationHandoffKey, t]);
+
+  // Manual retry for the NON-destructive same-instance-id stalled card only
+  // (see liveEditSameInstanceStalledError below): unlike
+  // handleManualBridgeRegistrationRetry, registeredLiveEditBridgeKey was
+  // never nulled here, so bumping bridgeRegistrationRetryNonce would not
+  // reschedule a fresh watchdog probe (liveEditBridgeRegistered never flips
+  // false→true to rearm that effect). Reset the backoff and probe /health
+  // again directly instead.
+  const handleManualLiveEditSameInstanceRetry = useCallback(() => {
+    liveEditSameInstanceElapsedMsRef.current = 0;
+    liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+    if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+      window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+      liveEditSameInstanceRearmTimerRef.current = undefined;
+    }
+    setLiveEditSameInstanceStalledError(null);
+    void handleSuspectedBridgeRestart();
+  }, [handleSuspectedBridgeRestart]);
+
+  // Arm the ready-handshake watchdog whenever the real authenticated live-edit
+  // document is (re)mounted in editor-chrome mode (the only mode that ever
+  // posts agent-native:editor-chrome-ready — see usesLiveEditEditorBridge).
+  // liveEditBridgeRegistered flips false→true on every fresh mount (including
+  // the reregister cycle above), so this effect reliably rearms each time.
+  //
+  // NOTE: deliberately does NOT reset the same-instance-id escalation refs
+  // (liveEditSameInstance*) here even though this effect conceptually marks a
+  // fresh mount: handleSuspectedBridgeRestart depends on `t`, whose identity
+  // is not guaranteed stable across renders (see useT), so this effect's own
+  // dependency array can cause it to re-run on unrelated re-renders — not
+  // only on a genuine fresh mount. Resetting escalation state here would
+  // then race with (and can clobber) the very state update that triggered
+  // that extra re-render, e.g. immediately wiping the non-destructive stalled
+  // error the moment it's set. The escalation refs are instead reset from
+  // known-good, less-churny signals: the liveEditBridgeKey-keyed effect below
+  // (genuinely new script/screen) and the "reregister" branch inside
+  // handleSuspectedBridgeRestart itself (genuine bridge-process restart).
+  useEffect(() => {
+    if (
+      !usesLiveEditEditorBridge ||
+      !liveEditBridgeRegistered ||
+      !externalPreviewUrl
+    ) {
+      return;
+    }
+    let cancelled = false;
+    const timer = window.setTimeout(() => {
+      if (cancelled || bridgeReadyRef.current) return;
+      void handleSuspectedBridgeRestart();
+    }, LIVE_EDIT_READY_TIMEOUT_MS);
+    return () => {
+      cancelled = true;
+      window.clearTimeout(timer);
+    };
+  }, [
+    usesLiveEditEditorBridge,
+    liveEditBridgeRegistered,
+    externalPreviewUrl,
+    handleSuspectedBridgeRestart,
+  ]);
+
   useEffect(() => {
     const previewUrl = rawExternalPreviewUrl;
     if (
@@ -1326,7 +1954,16 @@ export function DesignCanvas({
           .replace(
             "__DESIGN_CANVAS_BOARD_SURFACE__",
             boardSurface ? "true" : "false",
-          );
+          )
+          .replace(
+            "__DESIGN_CANVAS_CONTENT_OFFSET_X__",
+            String(Math.round(embeddedFrame?.contentOffsetX ?? 0)),
+          )
+          .replace(
+            "__DESIGN_CANVAS_CONTENT_OFFSET_Y__",
+            String(Math.round(embeddedFrame?.contentOffsetY ?? 0)),
+          )
+          .replace("__RUNTIME_LAYER_SNAPSHOT_ENABLED__", "false");
     // ALWAYS injected (like the other always-on bridges above) so
     // MultiScreenCanvas's cross-screen drag hit-testing
     // (agent-native:hit-test / agent-native:hit-test-result) resolves an
@@ -1380,8 +2017,6 @@ export function DesignCanvas({
     externalPreviewUrl,
     interactMode,
     isEmbeddedFrame,
-    embeddedFrame?.contentOffsetX,
-    embeddedFrame?.contentOffsetY,
     embeddedFrameBackground,
     embeddedGestureBridgeForCurrentState,
     iframeRenderContent,
@@ -1398,11 +2033,22 @@ export function DesignCanvas({
     previousIframeDocumentIdentityRef.current = iframeDocumentIdentity;
     bridgeReadyRef.current = false;
   }
+  const liveEditDocumentPending =
+    usesLiveEditEditorBridge &&
+    Boolean(externalPreviewUrl) &&
+    readyIframeDocumentIdentity !== iframeDocumentIdentity;
+  const liveEditTransitionFallbackHtml = liveEditDocumentPending
+    ? activeExternalSnapshotHtml
+    : undefined;
 
   // Listen for messages from the iframe
   useEffect(() => {
     function handleMessage(e: MessageEvent) {
       const iframeWindow = iframeRef.current?.contentWindow;
+      const lateReadyRecovery =
+        e.data?.type === "agent-native:editor-chrome-ready"
+          ? lateLiveEditReadyRecoveryRef.current
+          : null;
       // For fusion sources the Builder-hosted app is cross-origin, so the strict
       // `origin === parentOrigin` check can never match. We still require window
       // identity (the message must come from our own iframe window, not any
@@ -1411,7 +2057,7 @@ export function DesignCanvas({
       // *.builder.io family) before relaxing the origin check. If the origin is
       // not on the allowlist we keep the strict check so a hostile frame that
       // somehow shares our window reference still can't be trusted.
-      const trusted =
+      const trustedCurrentFrame =
         sourceType === "fusion"
           ? iframeWindow !== null &&
             e.source === iframeWindow &&
@@ -1428,12 +2074,80 @@ export function DesignCanvas({
                     )
                   : [],
             });
+      const trustedLateLiveEditReady =
+        sourceType === "localhost" &&
+        lateReadyRecovery !== null &&
+        lateReadyRecovery.bridgeKey === liveEditBridgeKey &&
+        isTrustedCanvasBridgeMessage({
+          source: e.source,
+          origin: e.origin,
+          iframeWindow: lateReadyRecovery.source,
+          parentOrigin: window.location.origin,
+          allowedOrigins: [originFromUrl(bridgeUrl)].filter(
+            (origin): origin is string => Boolean(origin),
+          ),
+        });
+      const trusted = trustedCurrentFrame || trustedLateLiveEditReady;
       if (!trusted) {
         return;
       }
       if (!e.data || !e.data.type) return;
+      if (e.data.type === "agent-native:runtime-layer-snapshot") {
+        const payload = e.data.payload;
+        if (
+          payload &&
+          typeof payload.html === "string" &&
+          payload.html.length <= 2_000_000 &&
+          Number.isFinite(payload.nodeCount)
+        ) {
+          onRuntimeLayerSnapshot?.({
+            html: payload.html,
+            nodeCount: Math.max(0, Math.floor(payload.nodeCount)),
+          });
+        }
+        return;
+      }
       if (e.data.type === "agent-native:editor-chrome-ready") {
+        if (trustedLateLiveEditReady && lateReadyRecovery) {
+          // This handshake belongs to the one retired live document saved by
+          // the destructive watchdog path, not the pending iframe now in the
+          // DOM. Restore its exact registration generation and let the newly
+          // mounted live document send the normal ready signal; do not mark
+          // the pending document ready or flush one-shot messages into it.
+          lateLiveEditReadyRecoveryRef.current = null;
+          if (lateReadyRecovery.registrationHandoffKey) {
+            liveEditRegistrationHandoff.set(
+              lateReadyRecovery.registrationHandoffKey,
+              Date.now(),
+            );
+          }
+          setBridgeRegistrationError((current) =>
+            current?.bridgeKey === lateReadyRecovery.bridgeKey ? null : current,
+          );
+          setRegisteredLiveEditBridgeKey(lateReadyRecovery.bridgeKey);
+          return;
+        }
+        lateLiveEditReadyRecoveryRef.current = null;
         bridgeReadyRef.current = true;
+        setReadyIframeDocumentIdentity(iframeDocumentIdentity);
+        // A confirmed ready handshake proves this bridgeInstanceId/key pair
+        // is genuinely live — clear the suspected-restart attempt counter so
+        // a later transient hiccup gets the full retry budget again instead
+        // of inheriting an already-elevated count from an unrelated earlier
+        // load.
+        liveEditRestartAttemptRef.current = 0;
+        // A late ready handshake wins even after the same-instance-id
+        // escalation loop gave up and showed its non-destructive error card:
+        // cancel any pending re-arm timer, reset the backoff, and clear the
+        // error so the now-loaded iframe (which was never torn down) reads
+        // as fully connected.
+        if (liveEditSameInstanceRearmTimerRef.current !== undefined) {
+          window.clearTimeout(liveEditSameInstanceRearmTimerRef.current);
+          liveEditSameInstanceRearmTimerRef.current = undefined;
+        }
+        liveEditSameInstanceElapsedMsRef.current = 0;
+        liveEditSameInstanceDelayRef.current = LIVE_EDIT_READY_TIMEOUT_MS;
+        setLiveEditSameInstanceStalledError(null);
         flushPendingOneShotMessages();
         return;
       }
@@ -1577,8 +2291,13 @@ export function DesignCanvas({
               sourceId,
               anchorSourceId,
               dropMode,
+              forceFlowPositionOverride:
+                e.data.forceFlowPositionOverride === true,
               sourceRect,
               anchorRect,
+              anchorElementInfo: isElementInfoPayload(e.data.anchorPayload)
+                ? e.data.anchorPayload
+                : undefined,
             },
           );
           if (requestId && applied !== "pending") {
@@ -1705,11 +2424,39 @@ export function DesignCanvas({
               ? iframeRect.height / iframe.clientHeight
               : 1;
           onIframeContextMenu?.({
+            screenId:
+              typeof e.data.screenId === "string" ? e.data.screenId : undefined,
             clientX,
             clientY,
             viewportClientX: (iframeRect?.left ?? 0) + clientX * scaleX,
             viewportClientY: (iframeRect?.top ?? 0) + clientY * scaleY,
             info: e.data.payload ?? null,
+            layerCandidates: Array.isArray(e.data.layerCandidates)
+              ? e.data.layerCandidates
+                  .filter(
+                    (candidate: unknown) =>
+                      candidate &&
+                      typeof candidate === "object" &&
+                      isElementInfoPayload(
+                        (candidate as { info?: unknown }).info,
+                      ),
+                  )
+                  .map((candidate: any, index: number) => ({
+                    key:
+                      typeof candidate.key === "string"
+                        ? candidate.key
+                        : `layer-hit-${index}`,
+                    label:
+                      typeof candidate.label === "string"
+                        ? candidate.label.slice(0, 80)
+                        : "Layer",
+                    screenId:
+                      typeof e.data.screenId === "string"
+                        ? e.data.screenId
+                        : undefined,
+                    info: candidate.info,
+                  }))
+              : [],
           });
         }
         return;
@@ -1842,6 +2589,7 @@ export function DesignCanvas({
     return () => window.removeEventListener("message", handleMessage);
   }, [
     onElementSelect,
+    onRuntimeLayerSnapshot,
     onElementMarqueeSelect,
     onElementHover,
     onClearSelection,
@@ -1863,6 +2611,7 @@ export function DesignCanvas({
     isEmbeddedFrame,
     sourceType,
     bridgeUrl,
+    liveEditBridgeKey,
     fusionUrl,
     flushPendingOneShotMessages,
     postOneShotBridgeMessage,
@@ -2127,6 +2876,66 @@ export function DesignCanvas({
     postOneShotBridgeMessage,
   ]);
 
+  // Overview/focused placement is presentation state, not document identity.
+  // Update gesture routing in place so entering Full view reuses the same
+  // registered bridge key instead of rebuilding the injected script.
+  useEffect(() => {
+    postOneShotBridgeMessage({
+      type: "embedded-canvas-gesture-mode",
+      wheelEnabled: isEmbeddedFrame,
+      spaceKeyForwardingEnabled: interactMode || readOnly,
+    });
+  }, [interactMode, isEmbeddedFrame, postOneShotBridgeMessage, readOnly]);
+
+  // The board iframe is a finite paint window over an infinite logical
+  // canvas. Re-centering that window must update its CSS/bridge coordinate
+  // offset in place; rebuilding srcdoc here would reload the iframe, flash,
+  // and discard transient Alpine state on every chunk crossing.
+  const embeddedContentOffsetX = embeddedFrame?.contentOffsetX ?? 0;
+  const embeddedContentOffsetY = embeddedFrame?.contentOffsetY ?? 0;
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    const applyOffset = () => {
+      try {
+        const doc = iframe.contentDocument;
+        if (doc) {
+          const css = embeddedContentOffsetCss(
+            embeddedContentOffsetX,
+            embeddedContentOffsetY,
+          );
+          let style = doc.querySelector<HTMLStyleElement>(
+            "style[data-agent-native-content-offset]",
+          );
+          if (!css) {
+            style?.remove();
+          } else {
+            if (!style) {
+              style = doc.createElement("style");
+              style.setAttribute("data-agent-native-content-offset", "");
+              (doc.head ?? doc.documentElement).appendChild(style);
+            }
+            style.textContent = css;
+          }
+        }
+      } catch {
+        // Cross-origin localhost/fusion frames are updated only through their
+        // own bridge below; direct document access is intentionally optional.
+      }
+      iframe.contentWindow?.postMessage(
+        {
+          type: "set-content-offset",
+          x: embeddedContentOffsetX,
+          y: embeddedContentOffsetY,
+        },
+        "*",
+      );
+    };
+    applyOffset();
+    iframe.addEventListener("load", applyOffset);
+    return () => iframe.removeEventListener("load", applyOffset);
+  }, [embeddedContentOffsetX, embeddedContentOffsetY]);
+
   // Sync readOnly to the bridge IN-PLACE via postMessage so switching the active
   // surface (board ↔ screen) does not rebuild srcdoc / reload the iframe.
   // The initial baked __READ_ONLY__ placeholder covers first paint; subsequent
@@ -2372,6 +3181,27 @@ export function DesignCanvas({
     }
   }, [postOneShotBridgeMessage, structureAckRequest]);
 
+  const lastRuntimeStructureMoveRequestIdRef = useRef<number | null>(null);
+  useEffect(() => {
+    if (!runtimeStructureMoveRequest) return;
+    if (
+      lastRuntimeStructureMoveRequestIdRef.current ===
+      runtimeStructureMoveRequest.requestId
+    ) {
+      return;
+    }
+    lastRuntimeStructureMoveRequestIdRef.current =
+      runtimeStructureMoveRequest.requestId;
+    postOneShotBridgeMessage({
+      type: "runtime-structure-move",
+      subjectSelector: runtimeStructureMoveRequest.subject.selector,
+      subjectSourceId: runtimeStructureMoveRequest.subject.sourceId,
+      anchorSelector: runtimeStructureMoveRequest.anchor.selector,
+      anchorSourceId: runtimeStructureMoveRequest.anchor.sourceId,
+      placement: runtimeStructureMoveRequest.placement,
+    });
+  }, [postOneShotBridgeMessage, runtimeStructureMoveRequest]);
+
   /**
    * Send a motion-preview scrub tick to the iframe.  `t` is the normalised
    * playhead position in [0, 1].  Tracks must have been loaded first via the
@@ -2747,10 +3577,13 @@ export function DesignCanvas({
       const rect = iframe?.getBoundingClientRect();
       const screenContentPoint =
         iframe && rect
-          ? getScreenContentPointFromClient(e.clientX, e.clientY, rect, {
-              width: iframe.clientWidth,
-              height: iframe.clientHeight,
-            })
+          ? getScreenContentPointFromClient(
+              e.clientX,
+              e.clientY,
+              rect,
+              { width: iframe.clientWidth, height: iframe.clientHeight },
+              readIframeScrollOffset(iframe),
+            )
           : { x: e.clientX, y: e.clientY };
       onDropFiles(files, { screenContentPoint, screenId });
     },
@@ -2810,6 +3643,21 @@ export function DesignCanvas({
           : null),
       }}
     >
+      {liveEditTransitionFallbackHtml ? (
+        <iframe
+          data-live-edit-transition-fallback
+          srcDoc={liveEditTransitionFallbackHtml}
+          sandbox=""
+          aria-hidden="true"
+          tabIndex={-1}
+          className="pointer-events-none absolute inset-0 block h-full w-full border-0 bg-transparent"
+          style={{
+            background: iframeBackgroundColor,
+            backgroundColor: iframeBackgroundColor,
+          }}
+          title=""
+        />
+      ) : null}
       <iframe
         key={iframeDocumentIdentity}
         ref={iframeRef}
@@ -2829,7 +3677,10 @@ export function DesignCanvas({
             ? "localhost" // inferred — content is a URL
             : "inline")
         }
-        className="block h-full w-full border-0 bg-transparent"
+        className={cn(
+          "relative block h-full w-full border-0 bg-transparent",
+          liveEditTransitionFallbackHtml && "pointer-events-none opacity-0",
+        )}
         style={{
           background: iframeBackgroundColor,
           backgroundColor: iframeBackgroundColor,
@@ -2868,9 +3719,84 @@ export function DesignCanvas({
           </div>
         </div>
       ) : null}
-      {waitingForEditableExternalSnapshot || waitingForLiveEditBridge ? (
+      {liveEditSameInstanceStalledError?.bridgeKey === liveEditBridgeKey ? (
+        // Non-destructive counterpart to the registration-failure card below:
+        // the same-instance-id escalation loop in handleSuspectedBridgeRestart
+        // hit its ceiling, but /health confirmed the bridge process is still
+        // the one we registered with — registeredLiveEditBridgeKey was never
+        // nulled, so the iframe underneath is still the real, still-loading
+        // document rather than the blank placeholder. Render as a small
+        // floating banner (not an opaque full-cover overlay like the cards
+        // below) so that still-loading iframe stays visible, and a late
+        // agent-native:editor-chrome-ready handshake clears this card (see
+        // the message-handler branch above) even after this point.
+        <div className="pointer-events-none absolute inset-x-0 bottom-4 z-10 flex justify-center px-4">
+          <div className="pointer-events-auto flex max-w-[28rem] flex-col items-center gap-2 rounded-md border bg-card px-4 py-3 shadow-sm">
+            <div className="flex items-center gap-1.5 font-medium text-foreground">
+              <IconPlugConnectedX className="size-4 shrink-0 text-destructive" />
+              {
+                "Live editor connection failed" /* i18n-ignore local dev bridge same-instance stall title, mirrors the registration-failure card's copy */
+              }
+            </div>
+            <div className="text-xs text-muted-foreground">
+              {
+                "Is the local dev server still running?" /* i18n-ignore local dev bridge same-instance stall subtitle */
+              }
+            </div>
+            <div className="w-full truncate rounded bg-muted px-2 py-1 font-mono text-[11px] text-muted-foreground">
+              {liveEditSameInstanceStalledError.message}
+            </div>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={handleManualLiveEditSameInstanceRetry}
+            >
+              <IconRefresh className="size-3.5" />
+              {"Retry" /* i18n-ignore local dev bridge retry button */}
+            </Button>
+          </div>
+        </div>
+      ) : null}
+      {waitingForEditableExternalSnapshot ||
+      waitingForLiveEditBridge ||
+      (liveEditDocumentPending && !liveEditTransitionFallbackHtml) ? (
         <div className="pointer-events-auto absolute inset-0 z-10 flex items-center justify-center bg-background/85 px-4 text-center text-sm text-muted-foreground">
-          {waitingForLiveEditBridge ? (
+          {waitingForLiveEditBridge &&
+          bridgeRegistrationError?.bridgeKey === liveEditBridgeKey ? (
+            // Mirrors the snapshot-fetch offline card below: a stuck
+            // registration used to look identical to ordinary "still
+            // registering" with no explanation and no way to recover short
+            // of a full page reload. Only shown for the CURRENT
+            // liveEditBridgeKey — a stale error from a previous script
+            // revision must not linger after content/mode changes move on
+            // to registering a new one.
+            <div className="pointer-events-auto flex max-w-[28rem] flex-col items-center gap-2 rounded-md border bg-card px-4 py-3 shadow-sm">
+              <div className="flex items-center gap-1.5 font-medium text-foreground">
+                <IconPlugConnectedX className="size-4 shrink-0 text-destructive" />
+                {
+                  "Live editor connection failed" /* i18n-ignore local dev bridge registration failure title */
+                }
+              </div>
+              <div className="text-xs text-muted-foreground">
+                {
+                  "Is the local dev server still running?" /* i18n-ignore local dev bridge registration failure subtitle */
+                }
+              </div>
+              <div className="w-full truncate rounded bg-muted px-2 py-1 font-mono text-[11px] text-muted-foreground">
+                {bridgeRegistrationError.message}
+              </div>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={handleManualBridgeRegistrationRetry}
+              >
+                <IconRefresh className="size-3.5" />
+                {"Retry" /* i18n-ignore local dev bridge retry button */}
+              </Button>
+            </div>
+          ) : waitingForLiveEditBridge ? (
             <div className="max-w-[28rem] rounded-md border bg-card px-4 py-3 shadow-sm">
               {
                 "Preparing live editor..." /* i18n-ignore transient localhost live-edit bridge loading state */
@@ -2923,11 +3849,16 @@ export function DesignCanvas({
       {/* Draw-to-prompt overlay — sits over the iframe, NOT inside it. */}
       <SharedDrawOverlay
         visible={!!drawMode}
+        clearSignal={drawOverlayResetSignal}
+        scopeKey={screenId}
+        retainSurfaceWhenHidden={retainDrawOverlayWhenHidden}
         canvasInteractive={!pinMode}
         queuedAnnotationCount={queuedAnnotationPins.length}
         zoom={zoom}
+        sending={annotationCaptureBusy}
         onClose={() => onExitDrawMode?.()}
         onSend={(annotations, instruction, canvasSize) => {
+          if (annotationCaptureBusyRef.current) return;
           const summary = annotations
             .map((a) =>
               a.type === "path"
@@ -2960,25 +3891,70 @@ export function DesignCanvas({
             "",
             instruction || "Apply these annotations to the design.",
           ];
-          submitDesignAnnotations({
-            message: lines.join("\n"),
-            hasQueuedPins: queuedAnnotationPins.length > 0,
-            send: (message) => {
-              sendToDesignAgentChat({
+          const message = lines.join("\n");
+          const hasQueuedPins = queuedAnnotationPins.length > 0;
+
+          // Best-effort: render the annotated screen + composited drawing as
+          // ONE image the agent can see (see design-canvas/annotation-snapshot.ts),
+          // then send it alongside the existing text summary in the same chat
+          // turn. Never blocks or drops the annotation — any capture failure
+          // (no Chromium in hosted deploys, network blip, upload not
+          // configured, timeout) silently resolves to `null` and the message
+          // still goes out text-only, exactly as it did before this feature.
+          annotationCaptureBusyRef.current = true;
+          setAnnotationCaptureBusy(true);
+          onAnnotationSendingChange?.(true);
+          captureAnnotatedScreenshot({
+            designId,
+            fileId: screenId,
+            sourceType:
+              sourceType ?? (externalPreviewUrl ? "localhost" : "inline"),
+            annotations,
+            canvasSize,
+          })
+            .catch(() => null)
+            .then((imageUrl) =>
+              submitDesignAnnotations({
                 message,
-                submit: true,
-                openSidebar: true,
-              });
-            },
-            markQueuedPinsSubmitted: () => {
-              setPinSubmitSignal((signal) => signal + 1);
-            },
-            exitDrawMode: () => onExitDrawMode?.(),
-            onError: (error) => {
-              console.error("[DesignCanvas] failed to submit drawing:", error);
-              toast.error(t("designEditor.toasts.annotationSendError"));
-            },
-          });
+                hasQueuedPins,
+                // Ack-confirmed send: only exit draw mode / mark pins
+                // submitted once the message is CONFIRMED to have reached
+                // the chat (became a visible turn). A fire-and-forget send
+                // here would let the overlay tear down and the pins clear
+                // even when delivery is silently dropped — e.g. no LLM/agent
+                // engine configured, or the panel never finished mounting —
+                // discarding the user's drawing with no way to retry it.
+                send: async (message) => {
+                  const result = await sendToDesignAgentChatAndConfirm({
+                    message,
+                    images: imageUrl ? [imageUrl] : undefined,
+                    submit: true,
+                    openSidebar: true,
+                  });
+                  if (!result.delivered) {
+                    throw new Error(
+                      `Annotation message was not delivered to the agent chat (${result.reason ?? "unknown"})`,
+                    );
+                  }
+                },
+                markQueuedPinsSubmitted: () => {
+                  setPinSubmitSignal((signal) => signal + 1);
+                },
+                exitDrawMode: () => onExitDrawMode?.(),
+                onError: (error) => {
+                  console.error(
+                    "[DesignCanvas] failed to submit drawing:",
+                    error,
+                  );
+                  toast.error(t("designEditor.toasts.annotationSendError"));
+                },
+              }),
+            )
+            .finally(() => {
+              annotationCaptureBusyRef.current = false;
+              setAnnotationCaptureBusy(false);
+              onAnnotationSendingChange?.(false);
+            });
         }}
       />
     </div>
@@ -3222,15 +4198,28 @@ function SingleScreenCreationOverlay({
   const [penPointer, setPenPointer] = useState<PenPoint | null>(null);
   const [penCloseHover, setPenCloseHover] = useState(false);
 
+  // Returns the click/pointer point in SCREEN-CONTENT (document-absolute)
+  // coordinates — the same "screen's own pixel coordinate system" contract
+  // `onCreatePrimitive` documents, which already folds in the embedded
+  // screen's own internal scroll (see `getScreenContentPointFromClient`).
+  // Anything that renders these points directly as this overlay's own CSS
+  // position (the drag/line preview below, and `SingleScreenPenPathOverlay`)
+  // must convert back to overlay-local (viewport-relative) coordinates by
+  // subtracting the same scroll offset — the overlay itself never scrolls
+  // with the embedded screen's internal document, it only tracks the
+  // iframe's host-page box.
   const toContentPoint = useCallback(
     (clientX: number, clientY: number) => {
       const iframe = iframeRef.current;
       const rect = iframe?.getBoundingClientRect();
       if (!iframe || !rect) return { x: clientX, y: clientY };
-      return getScreenContentPointFromClient(clientX, clientY, rect, {
-        width: iframe.clientWidth,
-        height: iframe.clientHeight,
-      });
+      return getScreenContentPointFromClient(
+        clientX,
+        clientY,
+        rect,
+        { width: iframe.clientWidth, height: iframe.clientHeight },
+        readIframeScrollOffset(iframe),
+      );
     },
     [iframeRef],
   );
@@ -3524,7 +4513,7 @@ function SingleScreenCreationOverlay({
           e.currentTarget.releasePointerCapture(e.pointerId);
         }
         if (gesture.closing) {
-          finishPenPath(nextPath);
+          finishPenPath(nextPath, { preserveActiveTool: true });
         } else {
           updatePenPath(nextPath);
         }
@@ -3602,7 +4591,7 @@ function SingleScreenCreationOverlay({
       event.preventDefault();
       event.stopPropagation();
       event.stopImmediatePropagation();
-      finishPenPath(path);
+      finishPenPath(path, { preserveActiveTool: true });
     };
 
     window.addEventListener("keydown", handleKeyDown, true);
@@ -3623,19 +4612,49 @@ function SingleScreenCreationOverlay({
   // overlay's own (unscaled, layout-space) coordinates. The overlay div is
   // sized to the iframe's layout box (via inset-0 on a wrapper that already
   // matches iframe.clientWidth/Height 1:1 before the outer zoom transform),
-  // so screen-content coordinates ARE this overlay's local coordinates —
-  // no extra scale conversion is needed for the preview's own CSS position.
+  // so screen-content coordinates equal this overlay's local coordinates
+  // when the screen is unscrolled — no extra scale conversion is needed for
+  // the preview's own CSS position. When the embedded screen IS scrolled,
+  // `drag.startContent`/`currentContent` (from `toContentPoint`) carry that
+  // scroll baked in (screen-content space is document-absolute, per
+  // `onCreatePrimitive`'s contract), but this overlay div never scrolls with
+  // the iframe's internal document — it only tracks the iframe's fixed host-
+  // page box — so the scroll must be subtracted back out here to keep the
+  // live preview aligned under the cursor.
+  const previewScrollOffset = readIframeScrollOffset(iframeRef.current);
+  const toOverlayLocal = (point: { x: number; y: number }) => ({
+    x: point.x - previewScrollOffset.left,
+    y: point.y - previewScrollOffset.top,
+  });
   const previewRect =
     drag && drag.moved && !isLineTool && tool !== "pen"
-      ? getDraftGeometryFromPoints(drag.startContent, drag.currentContent, {
-          minWidth: tool === "text" ? 24 : 8,
-          minHeight: tool === "text" ? 18 : 8,
-        })
+      ? getDraftGeometryFromPoints(
+          toOverlayLocal(drag.startContent),
+          toOverlayLocal(drag.currentContent),
+          {
+            minWidth: tool === "text" ? 24 : 8,
+            minHeight: tool === "text" ? 18 : 8,
+          },
+        )
       : null;
   const previewLine =
     drag && drag.moved && isLineTool
-      ? { start: drag.startContent, end: drag.currentContent }
+      ? {
+          start: toOverlayLocal(drag.startContent),
+          end: toOverlayLocal(drag.currentContent),
+        }
       : null;
+  // Same overlay-local conversion for the live pen path — its anchors/
+  // handles are stored in screen-content (document-absolute) space via
+  // `toContentPoint`/`getPenAnchor`, but `SingleScreenPenPathOverlay` renders
+  // them directly as this overlay's own (unscrolled) SVG/CSS coordinates.
+  const displayedPenPathOverlay = displayedPenPath
+    ? translatePenPath(
+        displayedPenPath,
+        -previewScrollOffset.left,
+        -previewScrollOffset.top,
+      )
+    : null;
 
   return (
     <div
@@ -3659,9 +4678,9 @@ function SingleScreenCreationOverlay({
         }
       }}
     >
-      {tool === "pen" && displayedPenPath ? (
+      {tool === "pen" && displayedPenPathOverlay ? (
         <SingleScreenPenPathOverlay
-          path={displayedPenPath}
+          path={displayedPenPathOverlay}
           closeHover={penCloseHover}
           iframeRef={iframeRef}
         />
diff --git a/templates/design/app/components/design/DesignEditorSkeleton.tsx b/templates/design/app/components/design/DesignEditorSkeleton.tsx
index ec9356c7a8..db72ac7b1d 100644
--- a/templates/design/app/components/design/DesignEditorSkeleton.tsx
+++ b/templates/design/app/components/design/DesignEditorSkeleton.tsx
@@ -19,7 +19,7 @@ export function DesignEditorSkeleton({
       <div className="flex h-full overflow-hidden bg-[var(--design-editor-canvas-bg)]">
         {!embedded && (
           <aside className="relative flex min-h-0 shrink-0 border-r border-[var(--design-editor-panel-divider-color)] bg-[var(--design-editor-panel-bg)]">
-            <div className="flex w-[52px] shrink-0 flex-col items-center p-3">
+            <div className="flex w-[57px] shrink-0 flex-col items-center p-3">
               <Skeleton className={`size-8 rounded-md ${panelGhost}`} />
               <div className="mt-8 flex w-full flex-col items-center gap-3">
                 <Skeleton className={`size-8 rounded-lg ${panelGhost}`} />
@@ -27,7 +27,7 @@ export function DesignEditorSkeleton({
                 <Skeleton className={`size-8 rounded-lg ${panelGhost}`} />
               </div>
             </div>
-            <div className="flex w-[320px] min-w-0 flex-col bg-[var(--design-editor-panel-bg)]">
+            <div className="flex w-[280px] min-w-0 flex-col bg-[var(--design-editor-panel-bg)]">
               <div className="border-b border-[var(--design-editor-panel-divider-color)] p-3">
                 <Skeleton className={`h-5 w-28 rounded ${panelGhost}`} />
               </div>
@@ -60,8 +60,8 @@ export function DesignEditorSkeleton({
   return (
     <div className="flex h-full overflow-hidden bg-background">
       {!embedded && (
-        <aside className="hidden w-80 shrink-0 bg-[var(--design-editor-panel-bg)] lg:flex">
-          <div className="flex w-[52px] shrink-0 flex-col items-center p-3">
+        <aside className="hidden w-[337px] shrink-0 bg-[var(--design-editor-panel-bg)] lg:flex">
+          <div className="flex w-[57px] shrink-0 flex-col items-center p-3">
             <Skeleton className={`size-8 rounded-md ${panelGhost}`} />
             <Skeleton className={`mt-8 h-40 w-full rounded-lg ${panelGhost}`} />
           </div>
@@ -89,7 +89,7 @@ export function DesignEditorSkeleton({
       </main>
 
       {!embedded && (
-        <aside className="hidden w-80 shrink-0 flex-col bg-[var(--design-editor-panel-bg)] lg:flex">
+        <aside className="hidden w-[240px] shrink-0 flex-col bg-[var(--design-editor-panel-bg)] lg:flex">
           <div className="flex h-12 shrink-0 items-center justify-end px-3">
             <Skeleton className={`h-6 w-40 rounded-md ${panelGhost}`} />
           </div>
diff --git a/templates/design/app/components/design/DesignExtensionsPanel.spec.ts b/templates/design/app/components/design/DesignExtensionsPanel.spec.ts
new file mode 100644
index 0000000000..672aeec069
--- /dev/null
+++ b/templates/design/app/components/design/DesignExtensionsPanel.spec.ts
@@ -0,0 +1,122 @@
+/**
+ * DesignExtensionsPanel bug-hunt regression tests.
+ *
+ * Bug: `installExtension`'s `finally` block cleared `installingId` (which
+ * re-enables the Install button and re-shows the extension in "Available")
+ * immediately after the install POST resolved, without waiting for the
+ * `invalidateQueries` calls that refresh the "installed"/"available" slot
+ * lists to actually settle. That left a window where a fast double-click (or
+ * any click during that gap) fired a second install POST for the same
+ * extension before the UI caught up — a duplicate-install race. The fix
+ * extracts the network + invalidation sequence into `installExtensionRequest`
+ * and awaits both `invalidateQueries` calls before resolving, so callers
+ * can't regain control (and re-enable the button) until the lists are
+ * provably current.
+ *
+ * This file also locks in the postMessage origin/source hygiene requirement
+ * called out for this panel: DesignExtensionsPanel.tsx must not add a raw
+ * `window.addEventListener("message", ...)` listener of its own. All
+ * cross-iframe messaging here goes through the shared `EmbeddedApp` (asset
+ * picker) and `EmbeddedExtension` (installed extensions) components, which
+ * already validate both `event.origin` and `event.source` against the
+ * specific iframe — see packages/core/src/embedding/react.tsx (line ~110,
+ * ~240) and packages/core/src/client/extensions/EmbeddedExtension.tsx (line
+ * ~255), matching the `isMessageFromOwnPreviewIframe` pattern used elsewhere
+ * in this app (e.g. edit-panel/component-section.tsx).
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { installExtensionRequest } from "./DesignExtensionsPanel";
+
+describe("installExtensionRequest — duplicate-install race", () => {
+  const originalFetch = global.fetch;
+
+  beforeEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("does not resolve until both slot queries finish refetching", async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({}),
+    }) as unknown as typeof fetch;
+
+    // invalidateQueries is called once per queryKey (two calls total), each
+    // returning its own pending promise — collect every resolver so the test
+    // can release all of them together instead of only the last one.
+    const pendingResolvers: Array<() => void> = [];
+    const invalidateQueries = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          pendingResolvers.push(resolve);
+        }),
+    );
+    const resolveInvalidate = () => {
+      pendingResolvers.forEach((resolve) => resolve());
+    };
+
+    let requestSettled = false;
+    const requestPromise = installExtensionRequest(
+      "design.editor.inspector",
+      "ext_1",
+      { invalidateQueries },
+    ).then(() => {
+      requestSettled = true;
+    });
+
+    // Flush the microtasks tied to the fetch/json resolution, but leave the
+    // invalidateQueries promise pending.
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(invalidateQueries).toHaveBeenCalledTimes(2);
+    expect(invalidateQueries).toHaveBeenCalledWith({
+      queryKey: ["design-editor-extension-slot"],
+    });
+    expect(invalidateQueries).toHaveBeenCalledWith({
+      queryKey: ["design-editor-extension-slot-available"],
+    });
+    // Regression guard: before the fix, the function resolved here — before
+    // the lists had refetched — which is exactly the race that let a second
+    // install fire while the just-installed extension still showed as
+    // "Available".
+    expect(requestSettled).toBe(false);
+
+    resolveInvalidate();
+    await requestPromise;
+
+    expect(requestSettled).toBe(true);
+  });
+
+  it("rejects on a failed install POST without invalidating either query", async () => {
+    global.fetch = vi
+      .fn()
+      .mockResolvedValue({ ok: false, status: 500 }) as unknown as typeof fetch;
+    const invalidateQueries = vi.fn().mockResolvedValue(undefined);
+
+    await expect(
+      installExtensionRequest("design.editor.inspector", "ext_1", {
+        invalidateQueries,
+      }),
+    ).rejects.toThrow(/Install failed/);
+    expect(invalidateQueries).not.toHaveBeenCalled();
+  });
+});
+
+describe("DesignExtensionsPanel source — postMessage origin/source hygiene", () => {
+  it("adds no raw window message listener outside the shared EmbeddedApp/EmbeddedExtension origin+source checks", () => {
+    const source = readFileSync(
+      path.join(
+        path.dirname(fileURLToPath(import.meta.url)),
+        "DesignExtensionsPanel.tsx",
+      ),
+      "utf8",
+    );
+    expect(source).not.toMatch(/addEventListener\(\s*["']message["']/);
+  });
+});
diff --git a/templates/design/app/components/design/DesignExtensionsPanel.tsx b/templates/design/app/components/design/DesignExtensionsPanel.tsx
index 05b2d63877..7b380a906a 100644
--- a/templates/design/app/components/design/DesignExtensionsPanel.tsx
+++ b/templates/design/app/components/design/DesignExtensionsPanel.tsx
@@ -271,7 +271,12 @@ function useSlotInstalls(slotId: string) {
           `/_agent-native/slots/${encodeURIComponent(slotId)}/installs`,
         ),
       );
-      if (!res.ok) return [];
+      // Surface fetch failures as a query error instead of swallowing them as
+      // an empty list — an empty list renders identically to "nothing
+      // installed", which hides real server/network errors from the user.
+      if (!res.ok) {
+        throw new Error(`Failed to load installed extensions: ${res.status}`);
+      }
       return res.json();
     },
     placeholderData: (prev) => prev,
@@ -288,13 +293,59 @@ function useAvailableExtensions(slotId: string) {
           `/_agent-native/slots/${encodeURIComponent(slotId)}/available`,
         ),
       );
-      if (!res.ok) return [];
+      // See the matching note in useSlotInstalls above — don't mask a fetch
+      // failure as "no extensions available".
+      if (!res.ok) {
+        throw new Error(`Failed to load available extensions: ${res.status}`);
+      }
       return res.json();
     },
     placeholderData: (prev) => prev,
   });
 }
 
+/**
+ * POSTs the install request for `extensionId` and waits for both the
+ * "installed" and "available" slot queries to fully refetch before
+ * resolving.
+ *
+ * Exported so a test can verify the ordering directly: the previous
+ * implementation invalidated the queries without awaiting them, so the
+ * component's `finally` block re-enabled the Install button (by clearing
+ * `installingId`) while the "Available" list still listed the
+ * just-installed extension — a race that let a fast double-click fire a
+ * second install request before the list caught up. Awaiting here means the
+ * caller doesn't regain control (and hasn't cleared its "installing" state)
+ * until the lists are provably current.
+ */
+export async function installExtensionRequest(
+  slotId: string,
+  extensionId: string,
+  queryClient: {
+    invalidateQueries: (options: { queryKey: unknown[] }) => Promise<unknown>;
+  },
+): Promise<void> {
+  const res = await fetch(
+    agentNativePath(
+      `/_agent-native/slots/${encodeURIComponent(slotId)}/install`,
+    ),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ extensionId }),
+    },
+  );
+  if (!res.ok) throw new Error(`Install failed: ${res.status}`);
+  await Promise.all([
+    queryClient.invalidateQueries({
+      queryKey: ["design-editor-extension-slot"],
+    }),
+    queryClient.invalidateQueries({
+      queryKey: ["design-editor-extension-slot-available"],
+    }),
+  ]);
+}
+
 // ─── First-party extension rows ───────────────────────────────────────────────
 
 interface FirstPartyRowProps {
@@ -1390,8 +1441,13 @@ export function DesignExtensionsPanel({
     null,
   );
   const slotId = DESIGN_EDITOR_EXTENSION_SLOT_ID;
-  const { data: installs = [], isLoading } = useSlotInstalls(slotId);
-  const { data: available = [] } = useAvailableExtensions(slotId);
+  const {
+    data: installs = [],
+    isLoading,
+    isError: installsErrored,
+  } = useSlotInstalls(slotId);
+  const { data: available = [], isError: availableErrored } =
+    useAvailableExtensions(slotId);
   const installedIds = useMemo(
     () => new Set(installs.map((install) => install.extensionId)),
     [installs],
@@ -1420,23 +1476,12 @@ export function DesignExtensionsPanel({
   const installExtension = async (extensionId: string) => {
     setInstallingId(extensionId);
     try {
-      const res = await fetch(
-        agentNativePath(
-          `/_agent-native/slots/${encodeURIComponent(slotId)}/install`,
-        ),
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ extensionId }),
-        },
-      );
-      if (!res.ok) throw new Error(`Install failed: ${res.status}`);
-      queryClient.invalidateQueries({
-        queryKey: ["design-editor-extension-slot"],
-      });
-      queryClient.invalidateQueries({
-        queryKey: ["design-editor-extension-slot-available"],
-      });
+      // Awaits both slot queries' refetch, not just firing invalidation —
+      // see installExtensionRequest's doc comment for the duplicate-install
+      // race this closes: installingId (and therefore the disabled Install
+      // button) must stay set until the "Available" list has actually
+      // dropped this extension, not just until the POST resolves.
+      await installExtensionRequest(slotId, extensionId, queryClient);
     } catch {
       toast.error(t("designEditor.extensionsInstallError"));
     } finally {
@@ -1570,6 +1615,13 @@ export function DesignExtensionsPanel({
           />
         </div>
 
+        {(installsErrored || availableErrored) && (
+          <p className="mb-3 rounded border border-destructive/30 bg-destructive/5 px-2 py-1.5 text-[10px] leading-snug text-destructive">
+            Couldn&apos;t load extensions. Built-in tools are still available
+            below — check your connection and try again.
+          </p>
+        )}
+
         {isLoading ? (
           <div className="space-y-3">
             <Skeleton className="h-12 rounded-md" />
diff --git a/templates/design/app/components/design/EditPanel.componentProps.spec.ts b/templates/design/app/components/design/EditPanel.componentProps.spec.ts
index d5612fa46c..35d4fbc0eb 100644
--- a/templates/design/app/components/design/EditPanel.componentProps.spec.ts
+++ b/templates/design/app/components/design/EditPanel.componentProps.spec.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 
+import { buildComponentPropRows } from "./edit-panel/component-section";
 import {
   alpineDataValueLiteral,
   canRebuildAlpineDataLosslessly,
@@ -310,6 +311,85 @@ describe("canRebuildAlpineDataLosslessly", () => {
 // isBooleanPropValue — toggle detection
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// buildComponentPropRows — row model + persist-surface selection (Bug: a
+// never-observed persisted-variant group used to route its first edit to
+// whichever surface an UNRELATED sibling x-data key happened to use).
+// ---------------------------------------------------------------------------
+
+describe("buildComponentPropRows", () => {
+  it("lists Alpine x-data keys first, tagged for the alpineData surface", () => {
+    const rows = buildComponentPropRows({
+      instance: { alpineData: "{ variant: 'solid', open: false }" },
+      observedProps: [],
+      persistedVariants: { variant: ["solid", "outline"] },
+    });
+    const variantRow = rows.find((r) => r.name === "variant");
+    expect(variantRow).toMatchObject({
+      value: "solid",
+      surface: "alpineData",
+      options: ["solid", "outline"],
+    });
+    const openRow = rows.find((r) => r.name === "open");
+    expect(openRow).toMatchObject({ value: "false", surface: "alpineData" });
+  });
+
+  it("lists observed data-attribute props not already in x-data, tagged attribute", () => {
+    const rows = buildComponentPropRows({
+      instance: { alpineData: "{ open: false }" },
+      observedProps: [{ name: "label", value: "Save" }],
+      persistedVariants: {},
+    });
+    expect(rows.find((r) => r.name === "label")).toMatchObject({
+      value: "Save",
+      surface: "attribute",
+    });
+    // The x-data key isn't duplicated as an attribute row.
+    expect(rows.filter((r) => r.name === "open")).toHaveLength(1);
+  });
+
+  it("defaults a never-observed persisted-variant group to the attribute surface even when x-data exists for other keys", () => {
+    // This instance's x-data only carries `open` — `size` is a persisted
+    // variant group that has never appeared in x-data or observedProps on
+    // this instance, meaning it must be attribute-driven. Regression: this
+    // used to key off `alpineData` being truthy for the unrelated `open`
+    // key and route `size`'s first edit into an x-data rewrite instead.
+    const rows = buildComponentPropRows({
+      instance: { alpineData: "{ open: false }" },
+      observedProps: [],
+      persistedVariants: { size: ["sm", "md", "lg"] },
+    });
+    const sizeRow = rows.find((r) => r.name === "size");
+    expect(sizeRow).toMatchObject({
+      value: "sm",
+      surface: "attribute",
+      options: ["sm", "md", "lg"],
+    });
+  });
+
+  it("defaults a never-observed persisted-variant group to attribute when there is no x-data at all", () => {
+    const rows = buildComponentPropRows({
+      instance: null,
+      observedProps: [],
+      persistedVariants: { size: ["sm", "lg"] },
+    });
+    expect(rows.find((r) => r.name === "size")).toMatchObject({
+      value: "sm",
+      surface: "attribute",
+    });
+  });
+
+  it("does not duplicate a group already covered by x-data or an observed attribute", () => {
+    const rows = buildComponentPropRows({
+      instance: { alpineData: "{ variant: 'solid' }" },
+      observedProps: [{ name: "label", value: "Save" }],
+      persistedVariants: { variant: ["solid", "outline"], label: [] },
+    });
+    expect(rows.filter((r) => r.name === "variant")).toHaveLength(1);
+    expect(rows.filter((r) => r.name === "label")).toHaveLength(1);
+  });
+});
+
 describe("isBooleanPropValue", () => {
   it("recognizes true/false case-insensitively", () => {
     expect(isBooleanPropValue("true")).toBe(true);
diff --git a/templates/design/app/components/design/EditPanel.document-colors.test.ts b/templates/design/app/components/design/EditPanel.document-colors.test.ts
index 0052bff571..a5d6412bea 100644
--- a/templates/design/app/components/design/EditPanel.document-colors.test.ts
+++ b/templates/design/app/components/design/EditPanel.document-colors.test.ts
@@ -1,6 +1,19 @@
 import { describe, expect, it } from "vitest";
 
+import { selectionColorValues } from "./edit-panel/document-colors";
 import { extractDocumentColorPalette } from "./EditPanel";
+import type { ElementInfo } from "./types";
+
+function fakeElement(computedStyles: Record<string, string>): ElementInfo {
+  return {
+    tagName: "DIV",
+    classes: [],
+    computedStyles,
+    boundingRect: { x: 0, y: 0, width: 0, height: 0 },
+    isFlexChild: false,
+    isFlexContainer: false,
+  };
+}
 
 describe("extractDocumentColorPalette", () => {
   it("collects hex colors from inline styles across multiple files", () => {
@@ -117,3 +130,77 @@ describe("extractDocumentColorPalette", () => {
     ).not.toThrow();
   });
 });
+
+describe("selectionColorValues", () => {
+  it("skips the literal transparent spellings (existing behavior)", () => {
+    const values = selectionColorValues(
+      fakeElement({
+        color: "rgb(0, 0, 0)",
+        backgroundColor: "transparent",
+        borderColor: "rgba(0, 0, 0, 0)",
+        outlineColor: "",
+      }),
+    );
+
+    expect(values).toEqual([{ property: "color", value: "rgb(0, 0, 0)" }]);
+  });
+
+  it("skips any other zero-alpha color, not just the two literal spellings", () => {
+    // Regression: this used to only filter the exact strings "transparent"
+    // and "rgba(0, 0, 0, 0)" — a zero-alpha color with any other RGB
+    // channels or formatting (e.g. a non-black rgba, or hsla) slipped
+    // through as a bogus, effectively-invisible "selection color" swatch.
+    const values = selectionColorValues(
+      fakeElement({
+        color: "rgb(0, 0, 0)",
+        backgroundColor: "rgba(255, 0, 0, 0)",
+        borderColor: "hsla(210, 50%, 50%, 0)",
+        outlineColor: "rgba(0,0,0,0)",
+      }),
+    );
+
+    expect(values).toEqual([{ property: "color", value: "rgb(0, 0, 0)" }]);
+  });
+
+  it("keeps visible colors with non-zero alpha", () => {
+    const values = selectionColorValues(
+      fakeElement({
+        color: "#111111",
+        backgroundColor: "rgba(255, 0, 0, 0.5)",
+        borderColor: "",
+        outlineColor: "",
+      }),
+    );
+
+    expect(values).toEqual([
+      { property: "color", value: "#111111" },
+      { property: "backgroundColor", value: "rgba(255, 0, 0, 0.5)" },
+    ]);
+  });
+
+  it("dedupes equal colors across properties", () => {
+    const values = selectionColorValues(
+      fakeElement({
+        color: "#111111",
+        backgroundColor: "#111111",
+        borderColor: "#111111",
+        outlineColor: "",
+      }),
+    );
+
+    expect(values).toEqual([{ property: "color", value: "#111111" }]);
+  });
+
+  it("keeps unparseable non-color values through (e.g. a Mixed sentinel)", () => {
+    const values = selectionColorValues(
+      fakeElement({
+        color: "Mixed",
+        backgroundColor: "",
+        borderColor: "",
+        outlineColor: "",
+      }),
+    );
+
+    expect(values).toEqual([{ property: "color", value: "Mixed" }]);
+  });
+});
diff --git a/templates/design/app/components/design/EditPanel.fill-layers.test.ts b/templates/design/app/components/design/EditPanel.fill-layers.test.ts
index 1b6a4403d5..a51a488d47 100644
--- a/templates/design/app/components/design/EditPanel.fill-layers.test.ts
+++ b/templates/design/app/components/design/EditPanel.fill-layers.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
 
+import {
+  addFillLayerPatch,
+  removeBaseFillPatch,
+} from "./edit-panel/fill-gradient-helpers";
 import {
   averageGradientOpacity,
   defaultGradientStops,
@@ -188,3 +192,79 @@ describe("splitCssLayers / joinCssLayers round-trip (sanity for the arrays above
     expect(joinCssLayers([])).toBe("none");
   });
 });
+
+describe("addFillLayerPatch", () => {
+  it("reveals the hidden base solid when there is truly no fill at all", () => {
+    const patch = addFillLayerPatch({
+      backgroundColor: "transparent",
+      backgroundLayers: [],
+      backgroundSizeLayers: [],
+      backgroundRepeatLayers: [],
+      backgroundPositionLayers: [],
+    });
+
+    expect(patch).toEqual({ backgroundColor: "#ffffff" });
+  });
+
+  it("adds a new layer instead of un-hiding the base solid when layers already exist", () => {
+    // Regression: after switching solid -> gradient (solidToGradientPatch
+    // clears backgroundColor to "transparent"), clicking "+" again used to
+    // just un-hide the base solid instead of stacking a new layer — the
+    // opposite of "+", and it reintroduced the exact phantom-fill problem
+    // solidToGradientPatch exists to avoid.
+    const patch = addFillLayerPatch({
+      backgroundColor: "transparent",
+      backgroundLayers: ["linear-gradient(90deg, red, blue)"],
+      backgroundSizeLayers: ["auto"],
+      backgroundRepeatLayers: ["no-repeat"],
+      backgroundPositionLayers: ["0% 0%"],
+    });
+
+    expect(patch.backgroundColor).toBeUndefined();
+    const layers = splitCssLayers(patch.backgroundImage ?? "");
+    expect(layers).toHaveLength(2);
+    expect(layers[1]).toBe("linear-gradient(90deg, red, blue)");
+    expect(splitCssLayers(patch.backgroundSize ?? "")).toEqual([
+      "auto",
+      "auto",
+    ]);
+    expect(splitCssLayers(patch.backgroundRepeat ?? "")).toEqual([
+      "no-repeat",
+      "no-repeat",
+    ]);
+    expect(splitCssLayers(patch.backgroundPosition ?? "")).toEqual([
+      "0% 0%",
+      "0% 0%",
+    ]);
+  });
+
+  it("adds a layer on top of a visible base solid, keeping the solid", () => {
+    const patch = addFillLayerPatch({
+      backgroundColor: "#ff0000",
+      backgroundLayers: [],
+      backgroundSizeLayers: [],
+      backgroundRepeatLayers: [],
+      backgroundPositionLayers: [],
+    });
+
+    expect(patch.backgroundColor).toBeUndefined();
+    expect(splitCssLayers(patch.backgroundImage ?? "")).toHaveLength(1);
+  });
+});
+
+describe("removeBaseFillPatch", () => {
+  it("clears only the base color, never backgroundImage", () => {
+    // Regression: this used to also set backgroundImage: "none" whenever
+    // onStylesChange was available, silently deleting every other stacked
+    // gradient/image layer just from clicking the base fill row's remove
+    // button.
+    const patch = removeBaseFillPatch("backgroundColor");
+
+    expect(patch).toEqual({ backgroundColor: "transparent" });
+    expect(patch.backgroundImage).toBeUndefined();
+  });
+
+  it("clears the text color property for text fills", () => {
+    expect(removeBaseFillPatch("color")).toEqual({ color: "transparent" });
+  });
+});
diff --git a/templates/design/app/components/design/EditPanel.gradient.test.ts b/templates/design/app/components/design/EditPanel.gradient.test.ts
index 6ddcb97bc8..1a57316f43 100644
--- a/templates/design/app/components/design/EditPanel.gradient.test.ts
+++ b/templates/design/app/components/design/EditPanel.gradient.test.ts
@@ -43,4 +43,43 @@ describe("EditPanel gradient layer serialization", () => {
     expect(parsed?.stops[0]?.color).toBe("oklch(70% 0.1 200)");
     expect(parsed?.stops[1]?.color).toBe("color-mix(in srgb, red 40%, blue)");
   });
+
+  it("parses bare CSS named colors as gradient stops instead of dropping them", () => {
+    // Regression: readLeadingColor only recognized hex/transparent/function
+    // colors, so a plain named-color stop like "red" (extremely common in
+    // hand-authored or generated CSS) was misread as a gradient *prefix* —
+    // silently dropping that stop and corrupting an otherwise-valid 2-stop
+    // gradient into a broken 1-stop one with a garbage "red" prefix.
+    const parsed = parseGradientLayer("linear-gradient(red, blue)");
+
+    expect(parsed).not.toBeNull();
+    expect(parsed?.prefix).toBeUndefined();
+    expect(parsed?.stops).toHaveLength(2);
+    expect(parsed?.stops[0]?.color).toBe("#ff0000");
+    expect(parsed?.stops[1]?.color).toBe("#0000ff");
+  });
+
+  it("still treats direction/shape keywords as a prefix, not a color", () => {
+    const linear = parseGradientLayer(
+      "linear-gradient(to right, red 0%, blue 100%)",
+    );
+    expect(linear?.prefix).toBe("to right");
+    expect(linear?.stops).toHaveLength(2);
+
+    const radial = parseGradientLayer(
+      "radial-gradient(circle at 50% 50%, red 0%, blue 100%)",
+    );
+    expect(radial?.prefix).toBe("circle at 50% 50%");
+    expect(radial?.stops).toHaveLength(2);
+  });
+
+  it("preserves a named-color angle prefix round-trip through buildGradientLayer", () => {
+    const parsed = parseGradientLayer(
+      "linear-gradient(135deg, red 0%, blue 100%)",
+    );
+    expect(parsed).not.toBeNull();
+    expect(
+      buildGradientLayer(parsed!.type, parsed!.stops, parsed!.prefix),
+    ).toBe("linear-gradient(135deg, #ff0000 0%, #0000ff 100%)");
+  });
 });
diff --git a/templates/design/app/components/design/EditPanel.inspectorHelpers.spec.ts b/templates/design/app/components/design/EditPanel.inspectorHelpers.spec.ts
index e012e2292c..b7dba5fa5d 100644
--- a/templates/design/app/components/design/EditPanel.inspectorHelpers.spec.ts
+++ b/templates/design/app/components/design/EditPanel.inspectorHelpers.spec.ts
@@ -484,6 +484,57 @@ describe("mixedElementFromSelection", () => {
     const merged = mixedElementFromSelection([a, b]);
     expect(merged?.primitiveKind).toBe("text");
   });
+
+  // isParentFlex/isParentGrid/parentFlexDirection (element-classification.ts)
+  // read parentDisplay/parentAutoLayout/parentLayout to decide whether
+  // LayoutContextProperties renders FlexChildControls/GridChildControls at
+  // all. Left to leak through the `...base` spread unchecked, these would
+  // report whichever element was selected LAST, misrendering (and
+  // misapplying align-self/flex-grow edits) for a selection spanning two
+  // different parents.
+  it("clears parentDisplay/parentAutoLayout/parentLayout when the selection's parents disagree", () => {
+    const a = makeElement({
+      parentDisplay: "flex",
+      parentAutoLayout: {
+        display: "flex",
+        sourceId: "parent-a",
+        boundingRect: { x: 0, y: 0, width: 200, height: 100 },
+      },
+      parentLayout: { display: "flex", flexDirection: "row" },
+    });
+    const b = makeElement({
+      parentDisplay: "block",
+      parentAutoLayout: undefined,
+      parentLayout: undefined,
+    });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.parentDisplay).toBeUndefined();
+    expect(merged?.parentAutoLayout).toBeUndefined();
+    expect(merged?.parentLayout).toBeUndefined();
+  });
+
+  it("keeps parentDisplay/parentAutoLayout/parentLayout when every selected element shares the same parent", () => {
+    const parentAutoLayout = {
+      display: "flex",
+      sourceId: "parent-shared",
+      boundingRect: { x: 0, y: 0, width: 200, height: 100 },
+    };
+    const parentLayout = { display: "flex", flexDirection: "column" };
+    const a = makeElement({
+      parentDisplay: "flex",
+      parentAutoLayout,
+      parentLayout,
+    });
+    const b = makeElement({
+      parentDisplay: "flex",
+      parentAutoLayout: { ...parentAutoLayout },
+      parentLayout: { ...parentLayout },
+    });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.parentDisplay).toBe("flex");
+    expect(merged?.parentAutoLayout).toEqual(parentAutoLayout);
+    expect(merged?.parentLayout).toEqual(parentLayout);
+  });
 });
 
 // ---------------------------------------------------------------------------
diff --git a/templates/design/app/components/design/EditPanel.tsx b/templates/design/app/components/design/EditPanel.tsx
index cae2f6bb0c..989a5885e1 100644
--- a/templates/design/app/components/design/EditPanel.tsx
+++ b/templates/design/app/components/design/EditPanel.tsx
@@ -170,7 +170,6 @@ import {
   componentNameForElementInfo,
   cssElementSize,
   displayLabel,
-  elementHasLayoutChildren,
   elementIsComponentSelection,
   horizontalToJustify,
   inferElementSizing,
@@ -198,7 +197,6 @@ import {
 } from "./edit-panel/field-primitives";
 import {
   averageGradientOpacity,
-  buildFillRows,
   buildGradientLayer,
   DEFAULT_EXPORT_SETTINGS,
   defaultGradientLayer,
@@ -321,13 +319,10 @@ import {
   type ExportSettingsValue,
   type FrameSizePreset,
   type FrameSizePresetCategoryKey,
-  imageFillToBackgroundStyles,
   InteractionStatePanel,
   type ActiveInteractionState,
   type DesignFillRow,
-  type DesignFillRowPatch,
   type DesignGradientStop,
-  type DesignGradientStopPatch,
   type DesignGradientType,
   type ImageFillValue,
   type MotionKeyframeCssProperty,
@@ -459,6 +454,8 @@ interface EditPanelProps {
    * and an Edit component action.
    */
   componentNodeId?: string;
+  /** Increment to open the selected component's Swap instance picker. */
+  componentSwapPickerRequest?: number;
   /**
    * Source capabilities for the current design.  Used to gate the Edit
    * component / jump-to-source affordances.  When absent all writes default
@@ -1153,12 +1150,17 @@ function PageProperties({
           backgroundRepeat={styles.backgroundRepeat}
           backgroundPosition={styles.backgroundPosition}
           onBackgroundImageChange={(v) => onStyleChange("backgroundImage", v)}
-          onImageFillChange={(value) =>
-            commitStylePatch(
-              imageFillToBackgroundStyles(value),
-              onStyleChange,
-              onStylesChange,
-            )
+          // Layer-index-aware: ColorInput merges the edited image into the
+          // correct backgroundImage/backgroundSize/backgroundRepeat/
+          // backgroundPosition index and hands back the full four-property
+          // patch here, already preserving every other stacked
+          // gradient/image layer (same pattern as FillProperties' base fill
+          // row — see fill-properties.tsx). The single-layer
+          // `onImageFillChange` this previously used always overwrote the
+          // *whole* background stack via `imageFillToBackgroundStyles`,
+          // silently wiping any other stacked background layer.
+          onImageFillLayerChange={(patch) =>
+            commitStylePatch(patch, onStyleChange, onStylesChange)
           }
           blendMode={styles.backgroundBlendMode || "normal"}
           onBlendModeChange={(v) => onStyleChange("backgroundBlendMode", v)}
@@ -1351,6 +1353,7 @@ export const EditPanel = memo(function EditPanel({
   onComponentPropApplied,
   reviewPanelProps,
   componentNodeId,
+  componentSwapPickerRequest,
   sourceCapabilities = [],
   onCreateComponent,
   selectedElementAlreadyComponent = false,
@@ -1761,6 +1764,7 @@ export const EditPanel = memo(function EditPanel({
                 activeContent={activeContent}
                 activeFileUpdatedAt={activeFileUpdatedAt}
                 nodeId={componentNodeId}
+                swapPickerRequest={componentSwapPickerRequest}
                 onComponentPropApplied={onComponentPropApplied}
                 sourceCapabilities={sourceCapabilities}
               />
@@ -1805,6 +1809,7 @@ export const EditPanel = memo(function EditPanel({
                 <PositionLayoutProperties
                   element={inspectorElement}
                   onStyleChange={onStyleChange}
+                  onStylesChange={onStylesChange}
                   onAlignSelection={onAlignSelection}
                   motionKeyframeContext={motionKeyframeFieldContext}
                   breakpointOverrideContext={breakpointOverrideFieldContext}
diff --git a/templates/design/app/components/design/KeyboardShortcutsPanel.test.tsx b/templates/design/app/components/design/KeyboardShortcutsPanel.test.tsx
new file mode 100644
index 0000000000..ea13fb1126
--- /dev/null
+++ b/templates/design/app/components/design/KeyboardShortcutsPanel.test.tsx
@@ -0,0 +1,73 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const messages: Record<string, string> = {
+  "designEditor.keyboardShortcuts.title": "Keyboard shortcuts",
+  "designEditor.keyboardShortcuts.close": "Close keyboard shortcuts",
+  "designEditor.keyboardShortcuts.keys.or": "or",
+  "designEditor.keyboardShortcuts.keys.command": "Command",
+  "designEditor.keyboardShortcuts.keys.control": "Control",
+  "designEditor.keyboardShortcuts.keys.backslash": "Backslash",
+  "designEditor.keyboardShortcuts.categories.essential": "Essential",
+  "designEditor.keyboardShortcuts.commands.toggleUi": "Show/Hide UI",
+  "designEditor.keyboardShortcuts.commands.undo": "Undo",
+  "designEditor.keyboardShortcuts.commands.redo": "Redo",
+  "designEditor.keyboardShortcuts.descriptions.toggleUi":
+    "Press it now to quickly hide the panes and focus on your work",
+  "designEditor.keyboardShortcuts.descriptions.undo":
+    "Step back through your most recent design change",
+  "designEditor.keyboardShortcuts.descriptions.redo":
+    "Restore the design change you just undid",
+};
+
+vi.mock("@agent-native/core/client", () => ({
+  useT: () => (key: string) =>
+    messages[key] ?? key.split(".").slice(-1)[0] ?? key,
+}));
+
+import { KeyboardShortcutsPanel } from "./KeyboardShortcutsPanel";
+
+afterEach(() => {
+  document.body.replaceChildren();
+});
+
+describe("KeyboardShortcutsPanel Essential tutorial", () => {
+  it("stacks a standalone number above a title, description, and keycaps row", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(<KeyboardShortcutsPanel onClose={vi.fn()} />);
+    });
+
+    const cards = Array.from(
+      container.querySelectorAll<HTMLElement>("[data-essential-shortcut-card]"),
+    );
+    expect(cards).toHaveLength(3);
+    const first = cards[0]!;
+    expect(first.children[0]?.textContent).toBe("1");
+    expect(first.children[1]?.textContent).toContain("Show/Hide UI");
+    expect(
+      first.querySelector("[data-essential-shortcut-description]")?.textContent,
+    ).toBe("Press it now to quickly hide the panes and focus on your work");
+    expect(first.querySelectorAll("kbd")).toHaveLength(2);
+    expect(
+      first
+        .querySelector("[data-shortcut-bindings]")
+        ?.getAttribute("aria-label"),
+    ).toBe(
+      /Mac|iPhone|iPad/.test(navigator.platform)
+        ? "Command Backslash"
+        : "Control Backslash",
+    );
+    expect(first.querySelector("kbd")?.getAttribute("aria-hidden")).toBe(
+      "true",
+    );
+    expect(first.textContent).not.toContain("Keyboard shortcuts");
+
+    await act(async () => root.unmount());
+  });
+});
diff --git a/templates/design/app/components/design/KeyboardShortcutsPanel.tsx b/templates/design/app/components/design/KeyboardShortcutsPanel.tsx
new file mode 100644
index 0000000000..45a7633e40
--- /dev/null
+++ b/templates/design/app/components/design/KeyboardShortcutsPanel.tsx
@@ -0,0 +1,364 @@
+import { useT } from "@agent-native/core/client";
+import {
+  IconArrowUpRight,
+  IconCircle,
+  IconFrame,
+  IconHandStop,
+  IconLine,
+  IconMessage,
+  IconPencil,
+  IconPointer,
+  IconScale,
+  IconScribble,
+  IconSquare,
+  IconTypography,
+  IconX,
+} from "@tabler/icons-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { createCoreCommands } from "@/components/design/code-workbench/commands";
+import {
+  DESIGN_SHORTCUT_CATEGORIES,
+  DESIGN_SHORTCUTS,
+  type DesignShortcutCategory,
+  formatShortcutKeycaps,
+} from "@/components/design/keyboard-shortcuts";
+import { Button } from "@/components/ui/button";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+
+interface KeyboardShortcutsPanelProps {
+  onClose: () => void;
+}
+
+const TOOL_ICON_BY_SHORTCUT: Record<string, typeof IconPointer> = {
+  "move-tool": IconPointer,
+  "frame-tool": IconFrame,
+  "text-tool": IconTypography,
+  "pen-tool": IconPencil,
+  "hand-tool": IconHandStop,
+  "scale-tool": IconScale,
+  "comment-tool": IconMessage,
+  "draw-tool": IconScribble,
+  rectangle: IconSquare,
+  ellipse: IconCircle,
+  line: IconLine,
+  arrow: IconArrowUpRight,
+};
+
+const ESSENTIAL_DESCRIPTION_KEY_BY_SHORTCUT = {
+  "toggle-ui": "designEditor.keyboardShortcuts.descriptions.toggleUi",
+  undo: "designEditor.keyboardShortcuts.descriptions.undo",
+  redo: "designEditor.keyboardShortcuts.descriptions.redo",
+} as const;
+
+const CODE_CATEGORY_BY_COMMAND: Record<string, DesignShortcutCategory> = {
+  "workbench.save": "edit",
+  "workbench.saveAll": "edit",
+  "workbench.quickOpen": "edit",
+  "workbench.commandPalette": "edit",
+  "workbench.search": "edit",
+  "workbench.explorer": "view",
+  "workbench.toggleSidebar": "view",
+  "workbench.nextTab": "selection",
+  "workbench.previousTab": "selection",
+  "editor.gotoSymbol": "selection",
+  "editor.gotoLine": "selection",
+};
+
+const ACCESSIBLE_KEY_NAME_BY_TOKEN: Record<string, string> = {
+  alt: "alt",
+  arrowdown: "arrowDown",
+  arrowleft: "arrowLeft",
+  arrowright: "arrowRight",
+  arrowup: "arrowUp",
+  backspace: "backspace",
+  ctrl: "control",
+  delete: "delete",
+  enter: "enter",
+  shift: "shift",
+  tab: "tab",
+  "?": "questionMark",
+  "\\": "backslash",
+  "=": "equals",
+  "-": "minus",
+  "[": "leftBracket",
+  "]": "rightBracket",
+};
+
+function KeycapGroup({
+  binding,
+  applePlatform,
+}: {
+  binding: string;
+  applePlatform: boolean;
+}) {
+  return (
+    <span
+      data-keycap-group={binding}
+      aria-hidden="true"
+      className="inline-flex items-center gap-0.5 whitespace-nowrap"
+    >
+      {formatShortcutKeycaps(binding, applePlatform).map((keycap, index) => (
+        <kbd
+          key={`${keycap}-${index}`}
+          aria-hidden="true"
+          className="inline-flex min-w-5 items-center justify-center rounded-[3px] border border-neutral-500/70 bg-neutral-700/80 px-1 py-0.5 font-sans text-[10px] font-medium leading-none text-neutral-100 shadow-[0_1px_0_rgba(255,255,255,0.1)]"
+        >
+          {keycap}
+        </kbd>
+      ))}
+    </span>
+  );
+}
+
+function ShortcutBindings({ bindings }: { bindings: readonly string[] }) {
+  const t = useT();
+  const applePlatform =
+    typeof navigator !== "undefined" &&
+    /Mac|iPhone|iPad/.test(navigator.platform);
+  const accessibleBindings = bindings.map((binding) =>
+    binding
+      .split("+")
+      .map((rawToken) => {
+        const token = rawToken.toLowerCase();
+        if (token === "$mod") {
+          return t(
+            `designEditor.keyboardShortcuts.keys.${applePlatform ? "command" : "control"}`,
+          );
+        }
+        if (token === "alt" && applePlatform) {
+          return t("designEditor.keyboardShortcuts.keys.option");
+        }
+        const keyName = ACCESSIBLE_KEY_NAME_BY_TOKEN[token];
+        if (keyName) {
+          return t(`designEditor.keyboardShortcuts.keys.${keyName}`);
+        }
+        return rawToken.length === 1 ? rawToken.toLocaleUpperCase() : rawToken;
+      })
+      .join(" "),
+  );
+
+  return (
+    <span
+      data-shortcut-bindings
+      role="group"
+      aria-label={accessibleBindings.join(
+        ` ${t("designEditor.keyboardShortcuts.keys.or")} `,
+      )}
+      className="flex shrink-0 items-center gap-1.5"
+    >
+      {bindings.map((binding) => (
+        <KeycapGroup
+          key={binding}
+          binding={binding}
+          applePlatform={applePlatform}
+        />
+      ))}
+    </span>
+  );
+}
+
+export function KeyboardShortcutsPanel({
+  onClose,
+}: KeyboardShortcutsPanelProps) {
+  const t = useT();
+  const [category, setCategory] = useState<DesignShortcutCategory>("essential");
+  const initialTabRef = useRef<HTMLButtonElement | null>(null);
+  const codeShortcuts = useMemo(
+    () =>
+      createCoreCommands().flatMap((command) => {
+        const commandCategory = CODE_CATEGORY_BY_COMMAND[command.id];
+        return commandCategory && command.keybindings?.length
+          ? [{ ...command, shortcutCategory: commandCategory }]
+          : [];
+      }),
+    [],
+  );
+
+  useEffect(() => {
+    // Radix Menu restores focus to its trigger in its own close frame. Wait
+    // through that frame before moving focus into the newly-opened dock so
+    // menu invocation and the global shortcut share the same focus contract.
+    let focusFrame = 0;
+    const menuCloseFrame = window.requestAnimationFrame(() => {
+      focusFrame = window.requestAnimationFrame(() => {
+        initialTabRef.current?.focus({ preventScroll: true });
+      });
+    });
+    return () => {
+      window.cancelAnimationFrame(menuCloseFrame);
+      if (focusFrame) window.cancelAnimationFrame(focusFrame);
+    };
+  }, []);
+
+  return (
+    <section
+      data-keyboard-shortcuts-panel
+      role="region"
+      aria-label={t("designEditor.keyboardShortcuts.title")}
+      className="absolute inset-x-0 bottom-0 z-[60] flex h-[241px] flex-col border-t border-neutral-700 bg-neutral-900 text-neutral-100 shadow-[0_-12px_28px_rgba(0,0,0,0.28)]"
+    >
+      <Tabs
+        value={category}
+        onValueChange={(value) => setCategory(value as DesignShortcutCategory)}
+        className="flex min-h-0 flex-1 flex-col"
+      >
+        <div
+          data-shortcuts-tab-row
+          className="flex h-[38px] shrink-0 items-center border-b border-neutral-700"
+        >
+          <div className="min-w-0 flex-1 overflow-x-auto pl-[124px] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
+            <TabsList
+              data-shortcuts-tab-strip
+              className="h-9 w-max justify-start rounded-none bg-transparent p-0"
+            >
+              {DESIGN_SHORTCUT_CATEGORIES.map((categoryId) => (
+                <TabsTrigger
+                  key={categoryId}
+                  value={categoryId}
+                  ref={categoryId === "essential" ? initialTabRef : undefined}
+                  className="h-9 rounded-none border-x-0 border-b-2 border-t-0 border-transparent bg-transparent px-2.5 text-[11px] font-medium text-neutral-400 shadow-none data-[state=active]:border-blue-400 data-[state=active]:bg-transparent data-[state=active]:text-white data-[state=active]:shadow-none"
+                >
+                  {t(`designEditor.keyboardShortcuts.categories.${categoryId}`)}
+                </TabsTrigger>
+              ))}
+            </TabsList>
+          </div>
+          <Button
+            data-keyboard-shortcuts-close
+            type="button"
+            variant="ghost"
+            size="icon"
+            className="ml-2 size-7 shrink-0 text-neutral-300 hover:bg-neutral-700 hover:text-white"
+            aria-label={t("designEditor.keyboardShortcuts.close")}
+            onClick={onClose}
+          >
+            <IconX className="size-4" />
+          </Button>
+        </div>
+
+        {DESIGN_SHORTCUT_CATEGORIES.map((categoryId) => {
+          const designRows = DESIGN_SHORTCUTS.filter((item) =>
+            categoryId === "tools"
+              ? item.category === "tools" || item.category === "shape"
+              : item.category === categoryId,
+          );
+          const codeRows = codeShortcuts.filter(
+            (item) => item.shortcutCategory === categoryId,
+          );
+          return (
+            <TabsContent
+              key={categoryId}
+              value={categoryId}
+              data-shortcuts-tabpanel={categoryId}
+              className="m-0 min-h-0 flex-1 overflow-y-auto px-4 py-2 data-[state=inactive]:hidden"
+            >
+              {categoryId === "essential" ? (
+                <div
+                  data-shortcuts-content-column
+                  className="mx-auto max-w-[400px]"
+                >
+                  <h2
+                    data-essential-shortcuts-heading
+                    className="mb-2 text-[13px] font-semibold text-white"
+                  >
+                    {`${t("designEditor.keyboardShortcuts.categories.essential")} ${t("designEditor.keyboardShortcuts.title").toLocaleLowerCase()}`}
+                  </h2>
+                  <div className="space-y-6">
+                    {[
+                      DESIGN_SHORTCUTS.find((item) => item.id === "toggle-ui"),
+                      DESIGN_SHORTCUTS.find((item) => item.id === "undo"),
+                      DESIGN_SHORTCUTS.find((item) => item.id === "redo"),
+                    ].map((item, index) =>
+                      item ? (
+                        <section
+                          data-essential-shortcut-card
+                          data-shortcut-id={item.id}
+                          key={item.id}
+                          className="relative pt-7"
+                        >
+                          <div className="absolute left-0 top-0">
+                            <span className="flex size-5 items-center justify-center rounded-full bg-neutral-700 text-[10px] font-semibold text-white">
+                              {index + 1}
+                            </span>
+                          </div>
+                          <div className="mt-7 flex min-h-[58px] items-center justify-between gap-6 border-b border-neutral-700 pb-3">
+                            <div className="min-w-0 flex-1">
+                              <div className="text-[11px] font-medium text-neutral-100">
+                                {t(item.labelKey)}
+                              </div>
+                              <p
+                                data-essential-shortcut-description
+                                className="mt-1 text-[10px] leading-4 text-neutral-400"
+                              >
+                                {t(
+                                  ESSENTIAL_DESCRIPTION_KEY_BY_SHORTCUT[
+                                    item.id as keyof typeof ESSENTIAL_DESCRIPTION_KEY_BY_SHORTCUT
+                                  ],
+                                )}
+                              </p>
+                            </div>
+                            <ShortcutBindings bindings={item.bindings} />
+                          </div>
+                        </section>
+                      ) : null,
+                    )}
+                  </div>
+                </div>
+              ) : (
+                <div
+                  data-shortcut-grid={categoryId}
+                  data-shortcuts-content-column
+                  className="mx-auto max-w-[400px]"
+                >
+                  {designRows.map((item) => (
+                    <div
+                      data-shortcut-id={item.id}
+                      key={item.id}
+                      className="flex min-h-8 items-center gap-3 border-b border-neutral-800 py-1"
+                    >
+                      <span className="flex min-w-0 flex-1 items-center gap-2 truncate text-[11px] text-neutral-200">
+                        {(() => {
+                          const ToolIcon = TOOL_ICON_BY_SHORTCUT[item.id];
+                          return ToolIcon ? (
+                            <ToolIcon className="size-3.5 shrink-0 text-neutral-400" />
+                          ) : null;
+                        })()}
+                        <span className="truncate">
+                          {t(item.labelKey)}
+                          {item.context === "screen" ? (
+                            <span className="ml-1.5 rounded bg-neutral-700 px-1 py-0.5 text-[9px] uppercase tracking-wide text-neutral-300">
+                              {t(
+                                "designEditor.keyboardShortcuts.screenContext",
+                              )}
+                            </span>
+                          ) : null}
+                        </span>
+                      </span>
+                      <ShortcutBindings bindings={item.bindings} />
+                    </div>
+                  ))}
+                  {codeRows.map((item) => (
+                    <div
+                      data-code-shortcut-id={item.id}
+                      key={item.id}
+                      className="flex min-h-8 items-center gap-3 border-b border-neutral-800 py-1"
+                    >
+                      <span className="min-w-0 flex-1 truncate text-[11px] text-neutral-200">
+                        {item.title}
+                        <span className="ml-1.5 rounded bg-blue-500/20 px-1 py-0.5 text-[9px] uppercase tracking-wide text-blue-200">
+                          {t("designEditor.keyboardShortcuts.codeContext")}
+                        </span>
+                      </span>
+                      <ShortcutBindings bindings={item.keybindings ?? []} />
+                    </div>
+                  ))}
+                </div>
+              )}
+            </TabsContent>
+          );
+        })}
+      </Tabs>
+    </section>
+  );
+}
diff --git a/templates/design/app/components/design/LayersPanel.test.ts b/templates/design/app/components/design/LayersPanel.test.ts
index e85cfaeac4..99cb7a18cb 100644
--- a/templates/design/app/components/design/LayersPanel.test.ts
+++ b/templates/design/app/components/design/LayersPanel.test.ts
@@ -3,7 +3,9 @@ import { describe, expect, it } from "vitest";
 
 import {
   buildAncestorIdMap,
+  buildLayerNodeMap,
   collectDescendantContainerIds,
+  computeLayerMultiSelectIds,
   dropDescendantsOfSelectedAncestors,
   dropPlacementForEvent,
   findNodeWithAncestors,
@@ -17,10 +19,37 @@ import {
   nextAutoExpandedIds,
   nextExpandedIdsForSubtree,
   shouldResyncLayerSelectionAnchor,
+  shapeLayerUsesLayoutGlyph,
   type FlatLayerRow,
   type LayersPanelNode,
 } from "./LayersPanel";
 
+describe("LayersPanel promoted rectangle glyphs", () => {
+  it("uses the auto-layout glyph after a rectangle becomes a flex container", () => {
+    expect(
+      shapeLayerUsesLayoutGlyph({
+        type: "rectangle",
+        layout: { isFlexContainer: true, flexDirection: "row" },
+      }),
+    ).toBe(true);
+    expect(
+      shapeLayerUsesLayoutGlyph({
+        type: "shape",
+        layout: { isGridContainer: true },
+      }),
+    ).toBe(true);
+  });
+
+  it("keeps an ordinary rectangle on the rectangle glyph", () => {
+    expect(
+      shapeLayerUsesLayoutGlyph({
+        type: "rectangle",
+        layout: { isFlexContainer: false, isGridContainer: false },
+      }),
+    ).toBe(false);
+  });
+});
+
 function row(
   id: string,
   ancestorIds: string[] = [],
@@ -139,6 +168,53 @@ describe("LayersPanel drag payload ordering", () => {
     expect(map.get("b")).toEqual(["a"]);
     expect(map.get("a")).toEqual([]);
   });
+
+  it("keeps locked layers selected but excludes them from a multi-layer drag payload", () => {
+    const tree: LayersPanelNode[] = [
+      { id: "unlocked", name: "Unlocked" },
+      { id: "locked", name: "Locked", locked: true },
+    ];
+    const allRows = flattenRows(tree, new Set(), true);
+
+    expect(
+      getDraggedLayerIdsForRows({
+        selectedIds: ["locked", "unlocked"],
+        nodeId: "unlocked",
+        visibleRows: allRows,
+        ancestorIdMap: buildAncestorIdMap(tree),
+        nodeById: buildLayerNodeMap(tree),
+      }),
+    ).toEqual(["unlocked"]);
+  });
+
+  it("orders selected rows from the full tree even when search/collapse hides one", () => {
+    const tree: LayersPanelNode[] = [
+      { id: "first-dom", name: "First DOM" },
+      { id: "middle-dom", name: "Middle DOM" },
+      { id: "last-dom", name: "Last DOM" },
+    ];
+    const visibleRows = [row("middle-dom")];
+    const allRows = flattenRows(tree, new Set(), true);
+
+    expect(
+      getDraggedLayerIdsForRows({
+        selectedIds: ["first-dom", "last-dom", "middle-dom"],
+        nodeId: "middle-dom",
+        visibleRows: allRows,
+        ancestorIdMap: buildAncestorIdMap(tree),
+        nodeById: buildLayerNodeMap(tree),
+      }),
+    ).toEqual(["last-dom", "middle-dom", "first-dom"]);
+    // Documents the bug: visible-only ordering appended the hidden row in
+    // selection order instead of its deterministic full-tree position.
+    expect(
+      getDraggedLayerIdsForRows({
+        selectedIds: ["first-dom", "last-dom", "middle-dom"],
+        nodeId: "middle-dom",
+        visibleRows,
+      }),
+    ).toEqual(["middle-dom", "first-dom", "last-dom"]);
+  });
 });
 
 describe("LayersPanel auto-expand ancestors of selection (L1)", () => {
@@ -212,6 +288,193 @@ describe("LayersPanel shift-range selection normalization (L14)", () => {
   });
 });
 
+describe("BUG-LAYERS-MULTISELECT — computeLayerMultiSelectIds (Cmd/Ctrl+Click toggle, Shift+Click range)", () => {
+  const VISIBLE_IDS = ["a", "b", "c", "d", "e"];
+  const rows = VISIBLE_IDS.map((id) => row(id));
+
+  it("plain click replaces the selection with just the clicked row", () => {
+    const { nextIds, nextAnchor } = computeLayerMultiSelectIds({
+      id: "b",
+      additive: false,
+      range: false,
+      currentSelectedIds: ["a", "c"],
+      anchor: "a",
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    expect(nextIds).toEqual(["b"]);
+    expect(nextAnchor).toBe("b");
+  });
+
+  it("Cmd/Ctrl+Click (additive, no shift) ADDS an unselected row to the selection", () => {
+    const { nextIds, nextAnchor } = computeLayerMultiSelectIds({
+      id: "c",
+      additive: true,
+      range: false,
+      currentSelectedIds: ["a", "b"],
+      anchor: "a",
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    expect(nextIds).toEqual(["a", "b", "c"]);
+    // Plain additive (non-range) clicks still advance the anchor, matching
+    // Figma: the next Shift+Click pivots from the row you just Cmd-clicked.
+    expect(nextAnchor).toBe("c");
+  });
+
+  it("Cmd/Ctrl+Click (additive, no shift) REMOVES an already-selected row (toggle off)", () => {
+    const { nextIds } = computeLayerMultiSelectIds({
+      id: "b",
+      additive: true,
+      range: false,
+      currentSelectedIds: ["a", "b", "c"],
+      anchor: "a",
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    expect(nextIds).toEqual(["a", "c"]);
+  });
+
+  it("Shift+Click selects the visible range between the anchor and the clicked row (anchor before target)", () => {
+    const { nextIds, nextAnchor } = computeLayerMultiSelectIds({
+      id: "d",
+      additive: false,
+      range: true,
+      currentSelectedIds: ["b"],
+      anchor: "b",
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    expect(nextIds).toEqual(["b", "c", "d"]);
+    // Range clicks never move the anchor — the pivot stays fixed so a
+    // second Shift+Click extends/shrinks from the SAME row.
+    expect(nextAnchor).toBe("b");
+  });
+
+  it("Shift+Click selects the visible range when the clicked row is BEFORE the anchor", () => {
+    const { nextIds, nextAnchor } = computeLayerMultiSelectIds({
+      id: "a",
+      additive: false,
+      range: true,
+      currentSelectedIds: ["d"],
+      anchor: "d",
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    expect(nextIds).toEqual(["a", "b", "c", "d"]);
+    expect(nextAnchor).toBe("d");
+  });
+
+  it("a second Shift+Click from the SAME anchor shrinks the range instead of compounding it", () => {
+    // First Shift+Click: anchor "a" -> clicked "d".
+    const first = computeLayerMultiSelectIds({
+      id: "d",
+      additive: false,
+      range: true,
+      currentSelectedIds: ["a"],
+      anchor: "a",
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    expect(first.nextIds).toEqual(["a", "b", "c", "d"]);
+    expect(first.nextAnchor).toBe("a");
+
+    // Second Shift+Click, still pivoting from "a" (not from "d") — matches
+    // Figma: consecutive range clicks re-slice from the fixed anchor.
+    const second = computeLayerMultiSelectIds({
+      id: "b",
+      additive: false,
+      range: true,
+      currentSelectedIds: first.nextIds,
+      anchor: first.nextAnchor,
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    expect(second.nextIds).toEqual(["a", "b"]);
+    expect(second.nextAnchor).toBe("a");
+  });
+
+  it("Cmd/Ctrl+Shift+Click (additive range) MERGES the new range into the existing selection instead of replacing it", () => {
+    const { nextIds } = computeLayerMultiSelectIds({
+      id: "d",
+      additive: true,
+      range: true,
+      currentSelectedIds: ["a"],
+      anchor: "a",
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    // "a" was already selected and stays; b/c/d get added by the range.
+    expect(nextIds).toEqual(["a", "b", "c", "d"]);
+  });
+
+  it("falls back to the last still-visible selected row when the anchor is stale (deleted/filtered out of view)", () => {
+    const { nextIds, nextAnchor } = computeLayerMultiSelectIds({
+      id: "d",
+      additive: false,
+      range: true,
+      currentSelectedIds: ["stale-anchor", "b"],
+      anchor: "stale-anchor", // no longer in selectableVisibleIds
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    // Re-pivots from "b" (the last still-visible selected row) instead of
+    // collapsing to a single select.
+    expect(nextIds).toEqual(["b", "c", "d"]);
+    expect(nextAnchor).toBe("b");
+  });
+
+  it("Shift+Click with no prior anchor at all falls through to a plain single select", () => {
+    const { nextIds, nextAnchor } = computeLayerMultiSelectIds({
+      id: "c",
+      additive: false,
+      range: true,
+      currentSelectedIds: [],
+      anchor: null,
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+    });
+    expect(nextIds).toEqual(["c"]);
+    // No anchor existed and none was established by this click (matches the
+    // original ref-based behavior: the ref is only ever written on a plain
+    // click or a stale-anchor fallback correction).
+    expect(nextAnchor).toBeNull();
+  });
+
+  it("drops a selected descendant whose ancestor is also swept into a range (normalization still applies to range selections)", () => {
+    const nestedRows = [row("a"), row("b"), row("child-of-b", ["b"])];
+    const nestedVisibleIds = ["a", "b", "child-of-b"];
+    const { nextIds } = computeLayerMultiSelectIds({
+      id: "child-of-b",
+      additive: false,
+      range: true,
+      currentSelectedIds: ["a"],
+      anchor: "a",
+      selectableVisibleIds: nestedVisibleIds,
+      visibleRows: nestedRows,
+    });
+    expect(nextIds).toEqual(["a", "b"]);
+  });
+
+  it("uses anchorFallbackSelectedIds (the panel's own selectedIds prop) over currentSelectedIds for the stale-anchor search", () => {
+    // Regression guard for the pointer-click path: handlePointerSelect passes
+    // a freshly-DOM-read currentSelectedIds that can transiently diverge from
+    // the panel's own selectedIds prop. The stale-anchor fallback must pivot
+    // off the panel's real selection state, not the transient DOM read.
+    const { nextAnchor } = computeLayerMultiSelectIds({
+      id: "d",
+      additive: false,
+      range: true,
+      currentSelectedIds: ["stale-anchor"], // transient DOM-read set
+      anchor: "stale-anchor",
+      selectableVisibleIds: VISIBLE_IDS,
+      visibleRows: rows,
+      anchorFallbackSelectedIds: ["a", "b"], // panel's real selectedIds prop
+    });
+    expect(nextAnchor).toBe("b");
+  });
+});
+
 describe("LayersPanel row order convention (L5)", () => {
   it("flattens sibling groups in REVERSE dom order (top panel row = topmost-rendered / last DOM child)", () => {
     const nodes: LayersPanelNode[] = [
diff --git a/templates/design/app/components/design/LayersPanel.tsx b/templates/design/app/components/design/LayersPanel.tsx
index 27ad3c630e..e661f0126a 100644
--- a/templates/design/app/components/design/LayersPanel.tsx
+++ b/templates/design/app/components/design/LayersPanel.tsx
@@ -733,6 +733,92 @@ export function dropDescendantsOfSelectedAncestors(
   });
 }
 
+// BUG-LAYERS-MULTISELECT — Figma-parity multi-select: Cmd/Ctrl+Click toggles
+// one row's membership in the selection; Shift+Click selects the visible
+// range between the anchor row (the last row selected via a PLAIN click —
+// Shift+Click never moves the anchor, so consecutive range clicks keep
+// pivoting from the same row, matching Figma) and the clicked row; a plain
+// click replaces the selection with just the clicked row. Extracted out of
+// the row click handler (`selectNode` below) as a pure function so the
+// range/toggle computation itself — anchor fallback when the anchor row
+// scrolled out of view/was deleted, additive range-merge, and dropping a
+// selected descendant whose ancestor is also selected — is unit-testable
+// without mounting the panel.
+export function computeLayerMultiSelectIds(args: {
+  id: string;
+  additive: boolean;
+  range: boolean;
+  currentSelectedIds: readonly string[];
+  anchor: string | null;
+  selectableVisibleIds: readonly string[];
+  visibleRows: readonly FlatLayerRow[];
+  // Source for the stale-anchor fallback search below. Defaults to
+  // `currentSelectedIds`. The real panel passes its own `selectedIds` prop
+  // here instead — pointer clicks pass a `currentSelectedIds` freshly
+  // re-read from the DOM (readSelectedIdsFromTree), which can transiently
+  // differ from the panel's own selection state, and the fallback has always
+  // pivoted off the latter.
+  anchorFallbackSelectedIds?: readonly string[];
+}): { nextIds: string[]; nextAnchor: string | null } {
+  const {
+    id,
+    additive,
+    range,
+    currentSelectedIds,
+    anchor,
+    selectableVisibleIds,
+    visibleRows,
+    anchorFallbackSelectedIds = currentSelectedIds,
+  } = args;
+  const currentSelectedIdSet = new Set(currentSelectedIds);
+  let nextIds: string[];
+  // Only advance the anchor on plain clicks; Shift+clicks extend from the
+  // existing anchor so the pivot stays fixed across consecutive range
+  // clicks (returning `anchor` unchanged, including when it was never set).
+  // The one exception is the stale-anchor fallback just below, which DOES
+  // move the anchor even on a range click — it's re-pivoting onto a
+  // still-valid row, not starting a fresh selection.
+  let nextAnchor = range ? anchor : id;
+  if (range && anchor) {
+    let effectiveAnchor = anchor;
+    if (selectableVisibleIds.indexOf(effectiveAnchor) < 0) {
+      // Stale anchor (deleted / filtered / collapsed out of view): pivot from
+      // the last selected layer that is still visible & selectable, matching
+      // Figma's behavior instead of dropping the range to a single select.
+      const fallback = [...anchorFallbackSelectedIds]
+        .reverse()
+        .find((sid) => selectableVisibleIds.includes(sid));
+      if (fallback) {
+        effectiveAnchor = fallback;
+        nextAnchor = fallback;
+      }
+    }
+    const from = selectableVisibleIds.indexOf(effectiveAnchor);
+    const to = selectableVisibleIds.indexOf(id);
+    if (from >= 0 && to >= 0) {
+      const [start, end] = from < to ? [from, to] : [to, from];
+      const rangeIds = selectableVisibleIds.slice(start, end + 1);
+      const merged = additive
+        ? Array.from(new Set([...currentSelectedIds, ...rangeIds]))
+        : rangeIds;
+      // A range that spans an expanded parent and some of its children would
+      // otherwise co-select both. Normalize so a selected descendant whose
+      // ancestor is also selected gets dropped — the ancestor selection
+      // already implies it.
+      nextIds = dropDescendantsOfSelectedAncestors(merged, visibleRows);
+    } else {
+      nextIds = [id];
+    }
+  } else if (additive) {
+    nextIds = currentSelectedIdSet.has(id)
+      ? currentSelectedIds.filter((selectedId) => selectedId !== id)
+      : [...currentSelectedIds, id];
+  } else {
+    nextIds = [id];
+  }
+  return { nextIds, nextAnchor };
+}
+
 export function getDraggedLayerIdsForRows(args: {
   selectedIds: readonly string[];
   nodeId: string;
@@ -745,12 +831,21 @@ export function getDraggedLayerIdsForRows(args: {
   // extract them from the parent being dragged. Optional only for
   // call-site/back-compat convenience; always pass it in the real panel.
   ancestorIdMap?: ReadonlyMap<string, string[]>;
+  // Full-tree node lookup used to keep locked layers out of a multi-layer
+  // drag payload. Figma lets a locked row remain selected alongside unlocked
+  // rows, but dragging one of the unlocked rows must not silently move the
+  // locked selection too. Optional for pure-helper/back-compat callers; the
+  // real panel always passes it from the same full roots used above.
+  nodeById?: ReadonlyMap<string, LayersPanelNode>;
 }): string[] {
   const rawDraggedIds = args.selectedIds.includes(args.nodeId)
     ? getTreeOrderedLayerIds(args.selectedIds, args.visibleRows)
     : [args.nodeId];
-  const draggedIdSet = new Set(rawDraggedIds);
-  return rawDraggedIds.filter((id) => {
+  const movableDraggedIds = rawDraggedIds.filter(
+    (id) => args.nodeById?.get(id)?.locked !== true,
+  );
+  const draggedIdSet = new Set(movableDraggedIds);
+  return movableDraggedIds.filter((id) => {
     const ancestorIds =
       args.ancestorIdMap?.get(id) ??
       args.visibleRows.find((row) => row.node.id === id)?.ancestorIds;
@@ -758,6 +853,21 @@ export function getDraggedLayerIdsForRows(args: {
   });
 }
 
+/** Builds an id-to-node lookup over the full tree. Kept separate from the
+ * ancestor map because drag-start needs both node state (locked) and ancestry,
+ * while other callers only need one or the other. */
+export function buildLayerNodeMap(
+  nodes: readonly LayersPanelNode[],
+): Map<string, LayersPanelNode> {
+  const map = new Map<string, LayersPanelNode>();
+  const visit = (node: LayersPanelNode) => {
+    map.set(node.id, node);
+    node.children?.forEach(visit);
+  };
+  nodes.forEach(visit);
+  return map;
+}
+
 // Row context-menu actions (copy/duplicate/delete/group/reorder) operate on
 // the whole current selection when the right-clicked row is already part of
 // it (matching Figma), or on just that row otherwise (right-clicking an
@@ -1010,57 +1120,25 @@ function LayersPanelImpl(
     ) => {
       const currentSelectedIds =
         options.currentSelectedIds ?? selectedIdsRef.current;
-      const currentSelectedIdSet = new Set(currentSelectedIds);
-      let nextIds: string[];
-      if (options.range && lastSelectionAnchorRef.current) {
-        let anchor = lastSelectionAnchorRef.current;
-        if (selectableVisibleIds.indexOf(anchor) < 0) {
-          // Stale anchor (deleted / filtered / collapsed out of view): pivot from
-          // the last selected layer that is still visible & selectable, matching
-          // Figma's behavior instead of dropping the range to a single select.
-          const fallback = [...selectedIds]
-            .reverse()
-            .find((sid) => selectableVisibleIds.includes(sid));
-          if (fallback) {
-            anchor = fallback;
-            lastSelectionAnchorRef.current = fallback;
-          }
-        }
-        const from = selectableVisibleIds.indexOf(anchor);
-        const to = selectableVisibleIds.indexOf(id);
-        if (from >= 0 && to >= 0) {
-          const [start, end] = from < to ? [from, to] : [to, from];
-          const rangeIds = selectableVisibleIds.slice(start, end + 1);
-          const merged = options.additive
-            ? Array.from(new Set([...currentSelectedIds, ...rangeIds]))
-            : rangeIds;
-          // A range that spans an expanded parent and some of its children
-          // would otherwise co-select both. Normalize so a selected
-          // descendant whose ancestor is also selected gets dropped — the
-          // ancestor selection already implies it.
-          nextIds = dropDescendantsOfSelectedAncestors(
-            merged,
-            visibleRowsRef.current,
-          );
-        } else {
-          nextIds = [id];
-        }
-      } else if (options.additive) {
-        nextIds = currentSelectedIdSet.has(id)
-          ? currentSelectedIds.filter((selectedId) => selectedId !== id)
-          : [...currentSelectedIds, id];
-      } else {
-        nextIds = [id];
-      }
-      // Only advance the anchor on plain clicks; Shift+clicks extend from the
-      // existing anchor so the pivot stays fixed across consecutive range clicks.
-      if (!options.range) {
-        lastSelectionAnchorRef.current = id;
-      }
+      // NOTE: the stale-anchor fallback intentionally searches the PANEL'S
+      // OWN `selectedIds` prop, not `currentSelectedIds` (which pointer
+      // clicks pass in freshly re-read from the DOM via readSelectedIdsFromTree
+      // and can transiently differ) — matches the pre-extraction behavior.
+      const { nextIds, nextAnchor } = computeLayerMultiSelectIds({
+        id,
+        additive: options.additive,
+        range: options.range,
+        currentSelectedIds,
+        anchor: lastSelectionAnchorRef.current,
+        selectableVisibleIds,
+        visibleRows: visibleRowsRef.current,
+        anchorFallbackSelectedIds: selectedIds,
+      });
+      lastSelectionAnchorRef.current = nextAnchor;
       lastPanelSelectionSignatureRef.current = nextIds.join("\0");
       onSelectionChange(nextIds, { id, selectedIds: nextIds, ...options });
     },
-    [onSelectionChange, selectableVisibleIds],
+    [onSelectionChange, selectableVisibleIds, selectedIds],
   );
 
   const commitRename = useCallback(
@@ -1606,6 +1684,7 @@ const LayerRow = memo(function LayerRow({
   onFlipHorizontal,
   onFlipVertical,
 }: LayerRowProps) {
+  const t = useT();
   const { node, depth, hasChildren, canAcceptChildren } = row;
   const isComponentLayer = layerNodeIsComponent(node);
   const selectable = node.selectable !== false;
@@ -1734,12 +1813,20 @@ const LayerRow = memo(function LayerRow({
     // descendant nested inside a currently-collapsed dragged ancestor is
     // still correctly recognized as a descendant and excluded from the drag
     // payload (see L13 / buildAncestorIdMap).
-    const ancestorIdMap = buildAncestorIdMap(rootsRef.current);
+    const roots = rootsRef.current;
+    const ancestorIdMap = buildAncestorIdMap(roots);
+    const nodeById = buildLayerNodeMap(roots);
+    // Search/collapse only changes which rows are painted; it must not change
+    // the structural order of an existing multi-selection's drag payload.
+    // Flatten the complete tree for ordering, while the visible rows remain
+    // the interaction surface that actually started the gesture.
+    const allRows = flattenRows(roots, new Set(), true);
     const draggedIds = getDraggedLayerIdsForRows({
       selectedIds: selectedIdsRef.current,
       nodeId: node.id,
-      visibleRows: visibleRowsRef.current,
+      visibleRows: allRows,
       ancestorIdMap,
+      nodeById,
     });
     event.dataTransfer.effectAllowed = "move";
     event.dataTransfer.setData("application/x-design-layer-id", node.id);
@@ -1747,6 +1834,27 @@ const LayerRow = memo(function LayerRow({
       "application/x-design-layer-ids",
       JSON.stringify(draggedIds),
     );
+    // Figma parity: dragging 2+ selected layers shows a small "N layers"
+    // count badge following the cursor instead of the browser's default
+    // drag image — a screenshot of just the ONE row that received this
+    // native dragstart event, even though every selected row moves together.
+    // setDragImage requires the image element to be attached to the DOM at
+    // the moment it's called, but not after — build an offscreen node here,
+    // wire it up, and detach it on the next frame. Single-layer drags are
+    // unaffected (kept exactly as before: the browser's own row snapshot).
+    if (draggedIds.length > 1) {
+      const ghost = document.createElement("div");
+      ghost.textContent = t("layersPanel.dragGhostCount", {
+        count: draggedIds.length,
+      });
+      ghost.className =
+        "fixed left-[-9999px] top-[-9999px] pointer-events-none select-none whitespace-nowrap rounded-full border border-[var(--design-editor-control-border)] bg-[var(--design-editor-panel-bg)] px-2.5 py-1 text-[11px] font-medium leading-none text-foreground shadow-[0_4px_16px_rgba(0,0,0,0.16),0_0_0_0.5px_rgba(0,0,0,0.08)]";
+      document.body.appendChild(ghost);
+      event.dataTransfer.setDragImage(ghost, -12, -12);
+      requestAnimationFrame(() => {
+        ghost.remove();
+      });
+    }
     // Store drag state at module level so handleDragOver can read it.
     // dataTransfer.getData() returns "" during dragover per the HTML spec.
     activeDragState = { sourceId: node.id, draggedIds };
@@ -2435,7 +2543,11 @@ function LayerGlyph({
     case "board-element":
     case "shape":
     case "rectangle":
-      return <RectangleLayerGlyph className={common} />;
+      return shapeLayerUsesLayoutGlyph(node) ? (
+        <LayoutLayerGlyph node={node} className={common} />
+      ) : (
+        <RectangleLayerGlyph className={common} />
+      );
     case "vector":
       return <VectorLayerGlyph className={common} />;
     case "line":
@@ -2462,6 +2574,21 @@ function LayerGlyph({
   }
 }
 
+/**
+ * A canvas rectangle starts as a shape, but nest-on-drop can promote it to a
+ * flex/grid container. Once promoted, show the same auto-layout glyph as a
+ * frame so the Layers tree reflects the layer's real layout behavior instead
+ * of continuing to advertise it as a leaf rectangle.
+ */
+export function shapeLayerUsesLayoutGlyph(
+  node: Pick<LayersPanelNode, "type" | "layout">,
+): boolean {
+  return (
+    ["board-element", "shape", "rectangle"].includes(node.type ?? "") &&
+    Boolean(node.layout?.isFlexContainer || node.layout?.isGridContainer)
+  );
+}
+
 function layerNodeTagName(
   node: Pick<LayersPanelNode, "tagName" | "detail">,
 ): string | null {
diff --git a/templates/design/app/components/design/LocalhostWriteConsentDialog.tsx b/templates/design/app/components/design/LocalhostWriteConsentDialog.tsx
index 65e13203f1..3525b51f55 100644
--- a/templates/design/app/components/design/LocalhostWriteConsentDialog.tsx
+++ b/templates/design/app/components/design/LocalhostWriteConsentDialog.tsx
@@ -21,7 +21,6 @@ export interface LocalhostWriteConsentPayload {
   /** Pending callback to invoke after user grants consent. */
   onGranted: (grant: {
     grantId: string;
-    bridgeToken: string;
     rootPath: string;
     grantedUntil: string;
   }) => void;
@@ -58,7 +57,6 @@ export function LocalhostWriteConsentDialog({
     try {
       const result = await callAction<{
         grantId: string;
-        bridgeToken: string;
         rootPath: string;
         grantedUntil: string;
       }>("grant-localhost-write-consent", {
diff --git a/templates/design/app/components/design/MotionDock.test.tsx b/templates/design/app/components/design/MotionDock.test.tsx
index d208f732ff..23080218d4 100644
--- a/templates/design/app/components/design/MotionDock.test.tsx
+++ b/templates/design/app/components/design/MotionDock.test.tsx
@@ -5,7 +5,12 @@ import { describe, expect, it } from "vitest";
 
 import { TooltipProvider } from "@/components/ui/tooltip";
 
-import { MotionDock, type MotionDockTrack } from "./MotionDock";
+import {
+  formatCurveAxisValue,
+  MotionDock,
+  motionFieldKeyRequiresBlurGuard,
+  type MotionDockTrack,
+} from "./MotionDock";
 
 // Minimal catalog covering only the keys MotionDock reads — see the same
 // convention/rationale note in BreakpointBar.test.tsx. Full catalog coverage
@@ -186,3 +191,55 @@ describe("MotionDock — timeline body anatomy", () => {
     expect(markup).toContain('aria-label="Keyframe at 1500ms"');
   });
 });
+
+describe("motionFieldKeyRequiresBlurGuard (Enter/Escape double-commit guard)", () => {
+  // Regression: the current-time and duration toolbar fields call their
+  // commit function directly on Enter, then `.blur()` the input so it
+  // visually defocuses. That synchronous `.blur()` re-fires the SAME
+  // still-stale commit callback via onBlur in the same tick (React hasn't
+  // re-rendered between the two calls), double-invoking onPlayheadChange /
+  // onDurationChange and re-sending the preview postMessage. The fields set
+  // a `skipNextBlurCommitRef` flag before calling `.blur()`, keyed off this
+  // guard, so the immediately-following onBlur is a no-op instead of a
+  // second commit.
+  it("requires the blur guard for Enter (the commit-then-blur key)", () => {
+    expect(motionFieldKeyRequiresBlurGuard("Enter")).toBe(true);
+  });
+
+  it("requires the blur guard for Escape (the revert-then-blur key)", () => {
+    expect(motionFieldKeyRequiresBlurGuard("Escape")).toBe(true);
+  });
+
+  it("does not guard keys that never trigger an explicit .blur() call", () => {
+    expect(motionFieldKeyRequiresBlurGuard("Tab")).toBe(false);
+    expect(motionFieldKeyRequiresBlurGuard("a")).toBe(false);
+    expect(motionFieldKeyRequiresBlurGuard("ArrowLeft")).toBe(false);
+  });
+});
+
+describe("formatCurveAxisValue (bezier control-point field display)", () => {
+  // Regression: the custom-bezier x1/y1/x2/y2 number fields used to bind
+  // `value` directly to `formatCurveAxisValue(fieldValue)` with no local
+  // draft state. Typing "0" then "." called onChange(parseFloat("0.")) — a
+  // finite 0 — which re-rendered the field back to the committed "0" and
+  // silently dropped the "." the instant it was typed, so a decimal (or a
+  // leading "-" for a negative control point) could never be entered. The
+  // fix gives each field its own draft string that only resyncs from the
+  // committed value on blur/external change, not on every keystroke; this
+  // covers the formatting half of that contract (2-decimal rounding, used
+  // both to seed the initial draft and to reformat on blur).
+  it("rounds to 2 decimal places", () => {
+    expect(formatCurveAxisValue(0.4234)).toBe("0.42");
+    expect(formatCurveAxisValue(1.005)).toBe("1");
+  });
+
+  it("formats whole numbers without a trailing decimal", () => {
+    expect(formatCurveAxisValue(1)).toBe("1");
+    expect(formatCurveAxisValue(0)).toBe("0");
+  });
+
+  it("preserves sign for overshoot (back-curve) control points", () => {
+    expect(formatCurveAxisValue(-0.56)).toBe("-0.56");
+    expect(formatCurveAxisValue(1.56)).toBe("1.56");
+  });
+});
diff --git a/templates/design/app/components/design/MotionDock.tsx b/templates/design/app/components/design/MotionDock.tsx
index 8dabd71cd3..8500fbd25a 100644
--- a/templates/design/app/components/design/MotionDock.tsx
+++ b/templates/design/app/components/design/MotionDock.tsx
@@ -139,6 +139,21 @@ function formatMsTick(ms: number): string {
   return `${s}s`;
 }
 
+/**
+ * Whether committing on this key should also suppress the blur handler's own
+ * commit. Enter/Escape both trigger an explicit `.blur()` call right after
+ * committing so the field visually defocuses; without this guard, that
+ * synchronous blur re-invokes the (still stale, same-render) commit callback
+ * a second time in the same tick — a harmless-looking no-op for identical
+ * values, but it double-fires side effects like `onPlayheadChange` /
+ * `onDurationChange` and the preview postMessage. Mirrors
+ * `propInputKeyRequiresBlurGuard` in edit-panel/panel-primitives.tsx (the
+ * same bug class, fixed there for style-property fields).
+ */
+export function motionFieldKeyRequiresBlurGuard(key: string): boolean {
+  return key === "Enter" || key === "Escape";
+}
+
 /** Human label for an ease value: preset name when recognised, else raw. */
 function easeLabel(
   ease: MotionEase | undefined,
@@ -330,6 +345,12 @@ export function MotionDock({
 
   // Current-time field draft (null = displaying the live playhead).
   const [timeDraft, setTimeDraft] = useState<string | null>(null);
+  // See motionFieldKeyRequiresBlurGuard: set right before an Enter-triggered
+  // `.blur()` so the blur handler that fires in the same synchronous tick
+  // skips its own commit instead of double-invoking commitTimeDraft.
+  const skipNextTimeBlurCommitRef = useRef(false);
+  // Same guard for the duration field's Enter -> blur -> onBlur-commit path.
+  const skipNextDurationBlurCommitRef = useRef(false);
   /** Internal high-frequency playhead update — does NOT notify the parent. */
   const setPlayheadLocal = useCallback(
     (next: number) => {
@@ -750,6 +771,16 @@ export function MotionDock({
     timeDraft,
   ]);
 
+  // ── Duration field ────────────────────────────────────────────────────────
+  const commitDurationDraft = useCallback(() => {
+    const ms = parseInt(durationInput, 10);
+    if (!isNaN(ms) && ms >= 50) {
+      onDurationChange?.(ms);
+    } else {
+      setDurationInput(String(durationMs));
+    }
+  }, [durationInput, durationMs, onDurationChange]);
+
   // ── Space plays/pauses while the dock has focus (Figma parity) ───────────
   const handleDockKeyDown = useCallback(
     (e: ReactKeyboardEvent<HTMLDivElement>) => {
@@ -947,11 +978,32 @@ export function MotionDock({
                   setTimeDraft(String(Math.round(playhead * durationMs)))
                 }
                 onChange={(e) => setTimeDraft(e.target.value)}
-                onBlur={commitTimeDraft}
+                onBlur={() => {
+                  if (skipNextTimeBlurCommitRef.current) {
+                    skipNextTimeBlurCommitRef.current = false;
+                    return;
+                  }
+                  commitTimeDraft();
+                }}
                 onKeyDown={(e) => {
                   if (e.key === "Enter") {
                     e.preventDefault();
                     commitTimeDraft();
+                    // Without this, the blur triggered below re-enters
+                    // commitTimeDraft() a second time in the same
+                    // synchronous tick (see motionFieldKeyRequiresBlurGuard).
+                    skipNextTimeBlurCommitRef.current =
+                      motionFieldKeyRequiresBlurGuard(e.key);
+                    (e.target as HTMLInputElement).blur();
+                    return;
+                  }
+                  if (e.key === "Escape") {
+                    e.preventDefault();
+                    // Cancel the in-progress edit — revert to displaying the
+                    // live playhead instead of committing the draft.
+                    setTimeDraft(null);
+                    skipNextTimeBlurCommitRef.current =
+                      motionFieldKeyRequiresBlurGuard(e.key);
                     (e.target as HTMLInputElement).blur();
                   }
                 }}
@@ -973,11 +1025,31 @@ export function MotionDock({
                 value={durationInput}
                 onChange={(e) => setDurationInput(e.target.value)}
                 onBlur={() => {
-                  const ms = parseInt(durationInput, 10);
-                  if (!isNaN(ms) && ms >= 50) {
-                    onDurationChange?.(ms);
-                  } else {
+                  if (skipNextDurationBlurCommitRef.current) {
+                    skipNextDurationBlurCommitRef.current = false;
+                    return;
+                  }
+                  commitDurationDraft();
+                }}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") {
+                    e.preventDefault();
+                    commitDurationDraft();
+                    // Same double-commit guard as the current-time field —
+                    // see motionFieldKeyRequiresBlurGuard.
+                    skipNextDurationBlurCommitRef.current =
+                      motionFieldKeyRequiresBlurGuard(e.key);
+                    (e.target as HTMLInputElement).blur();
+                    return;
+                  }
+                  if (e.key === "Escape") {
+                    e.preventDefault();
+                    // Cancel the in-progress edit — revert to the last
+                    // committed duration instead of persisting the draft.
                     setDurationInput(String(durationMs));
+                    skipNextDurationBlurCommitRef.current =
+                      motionFieldKeyRequiresBlurGuard(e.key);
+                    (e.target as HTMLInputElement).blur();
                   }
                 }}
                 className="h-5 w-16 px-1 !text-[11px] md:!text-[11px]"
@@ -2106,6 +2178,68 @@ interface CurveEditorProps {
   onChange: (value: [number, number, number, number]) => void;
 }
 
+/** Format a bezier control-point axis value for display (2 decimal places). */
+export function formatCurveAxisValue(n: number): string {
+  return String(Math.round(n * 100) / 100);
+}
+
+interface CurveNumberFieldProps {
+  label: string;
+  value: number;
+  onChange: (n: number) => void;
+}
+
+/**
+ * One x1/y1/x2/y2 control-point number field in the bezier CurveEditor.
+ * Keeps its own draft string instead of being fully controlled by
+ * `formatCurveAxisValue(value)` so a user can type an in-progress value
+ * ("-", "0.", "1.5") without the field snapping back to the last-committed,
+ * rounded value on every keystroke. A prior version bound `value` directly to
+ * the rounded prop: typing "0" then "." called onChange(0) (parseFloat("0.")
+ * is a finite 0), which re-rendered the field back to "0" and silently
+ * dropped the "." the instant it was typed — decimals (and a bare "-" before
+ * a negative number) could never be entered. Mirrors the `focusedRef` resync
+ * guard in edit-panel/panel-primitives.tsx's LengthField (same "mid-edit prop
+ * stomp" bug class fixed there for style-property fields).
+ */
+function CurveNumberField({ label, value, onChange }: CurveNumberFieldProps) {
+  const [draft, setDraft] = useState(() => formatCurveAxisValue(value));
+  const focusedRef = useRef(false);
+
+  useEffect(() => {
+    if (!focusedRef.current) setDraft(formatCurveAxisValue(value));
+  }, [value]);
+
+  return (
+    <label className="flex flex-col items-stretch gap-0.5">
+      <span className="text-center text-[9px] text-muted-foreground">
+        {label}
+      </span>
+      <Input
+        type="number"
+        step={0.01}
+        value={draft}
+        onFocus={() => {
+          focusedRef.current = true;
+        }}
+        onChange={(e) => {
+          setDraft(e.target.value);
+          const n = parseFloat(e.target.value);
+          if (Number.isFinite(n)) onChange(n);
+        }}
+        onBlur={() => {
+          focusedRef.current = false;
+          // Snap back to the canonical rounded string — clears any
+          // unparsed/partial trailing input ("-", "1.") left over from typing.
+          setDraft(formatCurveAxisValue(value));
+        }}
+        className="h-5 px-1 !text-[10px] md:!text-[10px]"
+        aria-label={label}
+      />
+    </label>
+  );
+}
+
 function CurveEditor({ value, onChange }: CurveEditorProps) {
   const t = useT();
   const [x1, y1, x2, y2] = value;
@@ -2151,22 +2285,11 @@ function CurveEditor({ value, onChange }: CurveEditorProps) {
     fieldValue: number,
     apply: (n: number) => [number, number, number, number],
   ) => (
-    <label className="flex flex-col items-stretch gap-0.5">
-      <span className="text-center text-[9px] text-muted-foreground">
-        {label}
-      </span>
-      <Input
-        type="number"
-        step={0.01}
-        value={String(Math.round(fieldValue * 100) / 100)}
-        onChange={(e) => {
-          const n = parseFloat(e.target.value);
-          if (Number.isFinite(n)) onChange(apply(n));
-        }}
-        className="h-5 px-1 !text-[10px] md:!text-[10px]"
-        aria-label={label}
-      />
-    </label>
+    <CurveNumberField
+      label={label}
+      value={fieldValue}
+      onChange={(n) => onChange(apply(n))}
+    />
   );
 
   return (
diff --git a/templates/design/app/components/design/MultiScreenCanvas.gestures.test.tsx b/templates/design/app/components/design/MultiScreenCanvas.gestures.test.tsx
index 4437e49fb1..21fdcd5705 100644
--- a/templates/design/app/components/design/MultiScreenCanvas.gestures.test.tsx
+++ b/templates/design/app/components/design/MultiScreenCanvas.gestures.test.tsx
@@ -5,6 +5,7 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { findCanvasIframeForScreen } from "./multi-screen/iframe-targeting";
+import { SURFACE_PADDING } from "./multi-screen/overview-layout";
 import type { MultiScreenCanvasTool } from "./multi-screen/types";
 import { MultiScreenCanvas } from "./MultiScreenCanvas";
 
@@ -52,6 +53,25 @@ function dispatchMouse(
   );
 }
 
+function dispatchMouseAlt(
+  target: EventTarget,
+  type: "mousedown" | "mousemove" | "mouseup",
+  clientX: number,
+  clientY: number,
+) {
+  target.dispatchEvent(
+    new MouseEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      button: 0,
+      buttons: type === "mouseup" ? 0 : 1,
+      clientX,
+      clientY,
+      altKey: true,
+    }),
+  );
+}
+
 async function nextAnimationFrame() {
   await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
 }
@@ -177,6 +197,131 @@ describe("MultiScreenCanvas gesture cancellation and drag thresholds", () => {
     expect(selectionBox!.style.height).toBe(before.height);
   });
 
+  it("resizes a draft's DOM imperatively and restores it when Escape cancels the drag", async () => {
+    const surface = await renderHarness("rect");
+    const draft = await createSelectedDraft(surface);
+    const selectionBox = container.querySelector<HTMLElement>(
+      "[data-frame-selection-box]",
+    );
+    const resizeHandle = selectionBox?.querySelector<HTMLElement>(
+      '[data-resize-handle="se"]',
+    );
+    expect(selectionBox).not.toBeNull();
+    expect(resizeHandle).not.toBeNull();
+    const before = {
+      draftWidth: draft.style.width,
+      draftHeight: draft.style.height,
+      boxWidth: selectionBox!.style.width,
+      boxHeight: selectionBox!.style.height,
+    };
+
+    // PERF9: beginDraftResize now writes the live geometry straight to the
+    // draft's own DOM node + selection box via updateDraftPrimitivesRefOnly
+    // (mirroring beginResize's frame path), instead of committing full React
+    // state (setDraftPrimitives) on every native mousemove. Confirm those DOM
+    // writes actually happen mid-gesture (not just at the eventual commit).
+    await act(async () => {
+      dispatchMouse(resizeHandle!, "mousedown", 400, 400);
+      dispatchMouse(window, "mousemove", 450, 450);
+      await nextAnimationFrame();
+    });
+    expect(draft.style.width).not.toBe(before.draftWidth);
+    expect(draft.style.height).not.toBe(before.draftHeight);
+    expect(selectionBox!.style.width).not.toBe(before.boxWidth);
+    expect(selectionBox!.style.height).not.toBe(before.boxHeight);
+
+    // Escape must roll back every DOM node the live resize mutated
+    // imperatively, not just the (already-reverted) React draft state —
+    // otherwise the shape stays visually stuck at its last dragged size.
+    await act(async () => {
+      window.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "Escape",
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    });
+
+    expect(draft.style.width).toBe(before.draftWidth);
+    expect(draft.style.height).toBe(before.draftHeight);
+    expect(selectionBox!.style.width).toBe(before.boxWidth);
+    expect(selectionBox!.style.height).toBe(before.boxHeight);
+  });
+
+  it("does not deselect an already-selected frame for shift-marquee jitter below the drag threshold", async () => {
+    await renderSelectedFrame();
+    const surface = container.querySelector<HTMLElement>('[tabindex="-1"]');
+    expect(surface).not.toBeNull();
+    expect(
+      container.querySelector("[data-frame-selection-box]"),
+    ).not.toBeNull();
+
+    // MultiScreenCanvas auto-fits a lone screen into the mocked 800x600
+    // surface on mount (see the "lineup fit" effect keyed on screens.length),
+    // so pan/zoom aren't simply {0,0}/100 here. Read the actual world-layer
+    // transform it committed instead of assuming a 1:1 mapping, so this test
+    // targets the frame's real screen-space edge regardless of that fit math.
+    const worldLayer = surface!.firstElementChild as HTMLElement;
+    const transformMatch = worldLayer.style.transform.match(
+      /translate\(([-\d.]+)px,\s*([-\d.]+)px\)\s*scale\(([\d.]+)\)/,
+    );
+    expect(transformMatch).not.toBeNull();
+    const [, panXStr, panYStr, scaleStr] = transformMatch!;
+    const panX = Number.parseFloat(panXStr);
+    const panY = Number.parseFloat(panYStr);
+    const scale = Number.parseFloat(scaleStr);
+    // Mirrors getCanvasPoint/screenToCanvasPoint's inverse: clientX = surface
+    // rect.left (mocked to 0) + panX + (SURFACE_PADDING + canvasX) * scale.
+    const clientPointForCanvas = (canvasX: number, canvasY: number) => ({
+      clientX: panX + (SURFACE_PADDING + canvasX) * scale,
+      clientY: panY + (SURFACE_PADDING + canvasY) * scale,
+    });
+
+    // The frame spans canvas x:[0,320]. Start a shift+mousedown just to the
+    // right of it (on empty canvas, so beginMarquee fires, not the frame's
+    // own drag), then jitter 2 canvas px left — comfortably below
+    // DRAG_THRESHOLD (3 CLIENT px, and even smaller once scaled down here) —
+    // which crosses back over the frame's right edge. Before the fix, every
+    // mousemove (even sub-threshold ones) ran xorMarqueeSelection against the
+    // live rect, so this exact jitter toggled the already-selected frame OUT
+    // of the selection.
+    const origin = clientPointForCanvas(321, 300);
+    const jittered = clientPointForCanvas(319, 300);
+    const dispatchShiftMouse = (
+      target: EventTarget,
+      type: "mousedown" | "mousemove" | "mouseup",
+      clientX: number,
+      clientY: number,
+    ) =>
+      target.dispatchEvent(
+        new MouseEvent(type, {
+          bubbles: true,
+          cancelable: true,
+          button: 0,
+          buttons: type === "mouseup" ? 0 : 1,
+          clientX,
+          clientY,
+          shiftKey: true,
+        }),
+      );
+
+    await act(async () => {
+      dispatchShiftMouse(surface!, "mousedown", origin.clientX, origin.clientY);
+      dispatchShiftMouse(
+        window,
+        "mousemove",
+        jittered.clientX,
+        jittered.clientY,
+      );
+      dispatchShiftMouse(window, "mouseup", jittered.clientX, jittered.clientY);
+    });
+
+    expect(
+      container.querySelector("[data-frame-selection-box]"),
+    ).not.toBeNull();
+  });
+
   it("restores direct-DOM draft movement when Escape cancels the drag", async () => {
     const surface = await renderHarness("rect");
     const draft = await createSelectedDraft(surface);
@@ -230,6 +375,153 @@ describe("MultiScreenCanvas gesture cancellation and drag thresholds", () => {
     expect(frame.style.top).toBe(before.top);
   });
 
+  it("rotates a frame's DOM imperatively and restores it when Escape cancels the drag", async () => {
+    const { frame } = await renderSelectedFrame();
+    const selectionBox = container.querySelector<HTMLElement>(
+      "[data-frame-selection-box]",
+    );
+    const rotateHandle = selectionBox?.querySelector<HTMLElement>(
+      "[data-rotate-handle]",
+    );
+    expect(selectionBox).not.toBeNull();
+    expect(rotateHandle).not.toBeNull();
+    const before = {
+      frameTransform: frame.style.transform,
+      boxTransform: selectionBox!.style.transform,
+    };
+
+    // PERF9: rotate now writes the live transform straight to the frame
+    // shell + selection box via updateFrameGeometryRefOnly (mirroring
+    // beginFrameDrag), instead of committing full React state on every
+    // native mousemove. A rotate gesture starts at the handle's own
+    // position (outside the frame, near its corner) and needs to move past
+    // the drag threshold from there.
+    await act(async () => {
+      dispatchMouse(rotateHandle!, "mousedown", 500, 100);
+      dispatchMouse(window, "mousemove", 560, 100);
+      await nextAnimationFrame();
+    });
+    expect(frame.style.transform).not.toBe(before.frameTransform);
+    expect(selectionBox!.style.transform).not.toBe(before.boxTransform);
+
+    // Escape must roll back the imperatively-mutated transform on both
+    // nodes, not just the (already-reverted) React geometry state.
+    await act(async () => {
+      window.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "Escape",
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    });
+
+    expect(frame.style.transform).toBe(before.frameTransform);
+    expect(selectionBox!.style.transform).toBe(before.boxTransform);
+  });
+
+  it("resizes a frame's DOM imperatively and restores it when Escape cancels the drag", async () => {
+    const { frame } = await renderSelectedFrame();
+    const selectionBox = container.querySelector<HTMLElement>(
+      "[data-frame-selection-box]",
+    );
+    const resizeHandle = selectionBox?.querySelector<HTMLElement>(
+      '[data-resize-handle="se"]',
+    );
+    expect(selectionBox).not.toBeNull();
+    expect(resizeHandle).not.toBeNull();
+    const screenCard = frame.querySelector<HTMLElement>("[data-screen-card]");
+    expect(screenCard).not.toBeNull();
+    const before = {
+      frameLeft: frame.style.left,
+      frameWidth: frame.style.width,
+      cardWidth: screenCard!.style.width,
+      cardHeight: screenCard!.style.height,
+      boxWidth: selectionBox!.style.width,
+      boxHeight: selectionBox!.style.height,
+    };
+
+    // PERF9: resize now writes the live geometry straight to the frame
+    // shell + screen-card + selection box via updateFrameGeometryRefOnly
+    // (mirroring beginFrameDrag), instead of committing full React state on
+    // every native mousemove. Confirm those DOM writes actually happen mid-
+    // gesture (not just at the eventual React commit).
+    await act(async () => {
+      dispatchMouse(resizeHandle!, "mousedown", 400, 400);
+      dispatchMouse(window, "mousemove", 450, 450);
+      await nextAnimationFrame();
+    });
+    expect(frame.style.width).not.toBe(before.frameWidth);
+    expect(screenCard!.style.width).not.toBe(before.cardWidth);
+    expect(screenCard!.style.height).not.toBe(before.cardHeight);
+    expect(selectionBox!.style.width).not.toBe(before.boxWidth);
+    expect(selectionBox!.style.height).not.toBe(before.boxHeight);
+
+    // Escape must roll back every DOM node the live resize mutated
+    // imperatively, not just the (already-reverted) React geometry state —
+    // otherwise the frame stays visually stuck at its last dragged size.
+    await act(async () => {
+      window.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "Escape",
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    });
+
+    expect(frame.style.left).toBe(before.frameLeft);
+    expect(frame.style.width).toBe(before.frameWidth);
+    expect(screenCard!.style.width).toBe(before.cardWidth);
+    expect(screenCard!.style.height).toBe(before.cardHeight);
+    expect(selectionBox!.style.width).toBe(before.boxWidth);
+    expect(selectionBox!.style.height).toBe(before.boxHeight);
+  });
+
+  it("moves the alt-drag duplicate ghost imperatively on every tick and unmounts it on release", async () => {
+    const { label } = await renderSelectedFrame();
+
+    // PERF9: beginDuplicateGesture now writes the ghost's left/top straight
+    // to its own DOM node (data-duplicate-preview-ghost) every native
+    // mousemove tick, instead of calling setDuplicatePreview (a full
+    // re-render) unconditionally each time — see duplicatePreviewElRef.
+    // canDuplicate/moved never flip in this harness (no onDuplicate prop is
+    // passed), which is exactly the steady-state case the fix targets: the
+    // ghost must still track the pointer on every tick even though nothing
+    // conditional ever changes.
+    await act(async () => {
+      dispatchMouseAlt(label, "mousedown", 320, 100);
+    });
+    const ghost = container.querySelector<HTMLElement>(
+      "[data-duplicate-preview-ghost]",
+    );
+    expect(ghost).not.toBeNull();
+    const afterMount = { left: ghost!.style.left, top: ghost!.style.top };
+
+    await act(async () => {
+      dispatchMouseAlt(window, "mousemove", 400, 160);
+      await nextAnimationFrame();
+    });
+    const afterFirstMove = { left: ghost!.style.left, top: ghost!.style.top };
+    expect(afterFirstMove.left).not.toBe(afterMount.left);
+    expect(afterFirstMove.top).not.toBe(afterMount.top);
+
+    await act(async () => {
+      dispatchMouseAlt(window, "mousemove", 430, 190);
+      await nextAnimationFrame();
+    });
+    const afterSecondMove = { left: ghost!.style.left, top: ghost!.style.top };
+    expect(afterSecondMove.left).not.toBe(afterFirstMove.left);
+    expect(afterSecondMove.top).not.toBe(afterFirstMove.top);
+
+    await act(async () => {
+      dispatchMouseAlt(window, "mouseup", 430, 190);
+    });
+    expect(
+      container.querySelector("[data-duplicate-preview-ghost]"),
+    ).toBeNull();
+  });
+
   it("restores the camera origin when Escape cancels a mouse pan", async () => {
     const surface = await renderHarness("hand");
     const world = surface.querySelector<HTMLElement>(
@@ -257,6 +549,143 @@ describe("MultiScreenCanvas gesture cancellation and drag thresholds", () => {
 
     expect(world!.style.transform).toBe(originTransform);
   });
+
+  it("keeps locked screens visible but blocks canvas selection and dragging", async () => {
+    const onPick = vi.fn();
+    const onGeometryChange = vi.fn();
+    const onGeometryCommit = vi.fn();
+    await act(async () => {
+      root.render(
+        <MultiScreenCanvas
+          screens={[
+            {
+              id: "locked-screen",
+              filename: "locked.html",
+              content: "<!doctype html><html><body></body></html>",
+            },
+          ]}
+          zoom={100}
+          selectedScreenIds={["locked-screen"]}
+          lockedScreenIds={["locked-screen"]}
+          geometryById={{
+            "locked-screen": { x: 40, y: 50, width: 320, height: 640 },
+          }}
+          renderScreenContent={() => <div data-test-live-screen-content />}
+          onPick={onPick}
+          onGeometryChange={onGeometryChange}
+          onGeometryCommit={onGeometryCommit}
+        />,
+      );
+    });
+
+    const frame = container.querySelector<HTMLElement>(
+      '[data-frame-id="locked-screen"]',
+    );
+    const label = frame?.querySelector<HTMLElement>("[data-frame-label]");
+    expect(frame).not.toBeNull();
+    expect(label).not.toBeNull();
+    expect(container.querySelector("[data-frame-selection-box]")).toBeNull();
+    expect(
+      frame?.querySelector<HTMLElement>("[data-screen-content]")?.style
+        .pointerEvents,
+    ).toBe("none");
+    onGeometryChange.mockClear();
+    onGeometryCommit.mockClear();
+
+    await act(async () => {
+      label!.click();
+      dispatchMouse(label!, "mousedown", 300, 120);
+      dispatchMouse(window, "mousemove", 380, 180);
+      await nextAnimationFrame();
+      dispatchMouse(window, "mouseup", 380, 180);
+    });
+
+    expect(onPick).not.toHaveBeenCalled();
+    expect(onGeometryChange).not.toHaveBeenCalled();
+    expect(onGeometryCommit).not.toHaveBeenCalled();
+  });
+
+  it("does not render hidden screens and restores their persisted geometry when shown", async () => {
+    const screens = [
+      {
+        id: "visible-screen",
+        filename: "visible.html",
+        content: "<!doctype html><html><body></body></html>",
+      },
+      {
+        id: "hidden-screen",
+        filename: "hidden.html",
+        content: "<!doctype html><html><body></body></html>",
+      },
+    ];
+    const geometryById = {
+      "visible-screen": { x: 0, y: 0, width: 320, height: 640 },
+      "hidden-screen": { x: 480, y: 90, width: 360, height: 720 },
+    };
+
+    await act(async () => {
+      root.render(
+        <MultiScreenCanvas
+          screens={screens}
+          zoom={100}
+          hiddenScreenIds={["hidden-screen"]}
+          geometryById={geometryById}
+          onPick={() => {}}
+        />,
+      );
+    });
+    expect(
+      container.querySelector('[data-frame-id="visible-screen"]'),
+    ).not.toBeNull();
+    expect(
+      container.querySelector('[data-frame-id="hidden-screen"]'),
+    ).toBeNull();
+
+    await act(async () => {
+      root.render(
+        <MultiScreenCanvas
+          screens={screens}
+          zoom={100}
+          hiddenScreenIds={[]}
+          geometryById={geometryById}
+          onPick={() => {}}
+        />,
+      );
+    });
+    const restored = container.querySelector<HTMLElement>(
+      '[data-frame-id="hidden-screen"]',
+    );
+    expect(restored).not.toBeNull();
+    expect(restored!.style.left).toContain("720px");
+    expect(restored!.style.top).toContain("302px");
+    expect(restored!.style.width).toBe("360px");
+  });
+
+  it("select-all excludes hidden and locked screens", async () => {
+    const onScreenSelectionChange = vi.fn();
+    const screens = ["visible", "locked", "hidden"].map((id) => ({
+      id,
+      filename: `${id}.html`,
+      content: "<!doctype html><html><body></body></html>",
+    }));
+    const render = (selectAllRequest: number) => (
+      <MultiScreenCanvas
+        screens={screens}
+        zoom={100}
+        selectAllRequest={selectAllRequest}
+        hiddenScreenIds={["hidden"]}
+        lockedScreenIds={["locked"]}
+        onPick={() => {}}
+        onScreenSelectionChange={onScreenSelectionChange}
+      />
+    );
+
+    await act(async () => root.render(render(0)));
+    onScreenSelectionChange.mockClear();
+    await act(async () => root.render(render(1)));
+
+    expect(onScreenSelectionChange).toHaveBeenLastCalledWith(["visible"]);
+  });
 });
 
 describe("canvas iframe identity", () => {
@@ -275,6 +704,353 @@ describe("canvas iframe identity", () => {
     expect(board).toBe(root.querySelector("[data-board-surface-layer] iframe"));
     expect(screen?.getAttribute("data-screen-iframe-id")).toBe("screen-a");
   });
+
+  it("renders negative and positive board coordinates inside a bounded paint window", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const rectSpy = vi
+      .spyOn(HTMLElement.prototype, "getBoundingClientRect")
+      .mockReturnValue({
+        x: 0,
+        y: 0,
+        top: 0,
+        right: 800,
+        bottom: 600,
+        left: 0,
+        width: 800,
+        height: 600,
+        toJSON: () => ({}),
+      });
+    const root = createRoot(container);
+
+    try {
+      await act(async () => {
+        root.render(
+          <MultiScreenCanvas
+            screens={[
+              {
+                id: "screen-a",
+                filename: "screen-a.html",
+                content: "<!doctype html><html><body></body></html>",
+              },
+            ]}
+            zoom={100}
+            geometryById={{
+              "screen-a": { x: 100, y: 80, width: 320, height: 640 },
+            }}
+            boardFileId="board"
+            boardFileContent={`<!doctype html><html><body>
+              <div data-agent-native-node-id="negative" data-an-primitive="rectangle" style="position:absolute;left:-165px;top:-90px;width:84px;height:76px"></div>
+              <div data-agent-native-node-id="positive" data-an-primitive="rectangle" style="position:absolute;left:329px;top:210px;width:100px;height:60px"></div>
+            </body></html>`}
+            boardFrameGeometry={{
+              x: -65536,
+              y: -65536,
+              width: 131072,
+              height: 131072,
+            }}
+            boardEditMode
+            onPick={() => {}}
+          />,
+        );
+      });
+
+      const boardLayer = container.querySelector<HTMLElement>(
+        "[data-board-surface-layer]",
+      );
+      const iframe = boardLayer?.querySelector<HTMLIFrameElement>(
+        "iframe[data-design-preview-iframe]",
+      );
+      expect(boardLayer).not.toBeNull();
+      expect(iframe).not.toBeNull();
+      expect(boardLayer!.style.left).toBe("-3856px");
+      expect(boardLayer!.style.top).toBe("-3856px");
+      expect(boardLayer!.style.width).toBe("8192px");
+      expect(boardLayer!.style.height).toBe("8192px");
+      expect(iframe!.srcdoc).toContain(
+        "body > [data-agent-native-node-id]{translate:4096px 4096px;}",
+      );
+    } finally {
+      await act(async () => root.unmount());
+      rectSpy.mockRestore();
+      container.remove();
+    }
+  });
+
+  it("re-windows the board after a distant pan without replacing its iframe", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const rectSpy = vi
+      .spyOn(HTMLElement.prototype, "getBoundingClientRect")
+      .mockReturnValue({
+        x: 0,
+        y: 0,
+        top: 0,
+        right: 800,
+        bottom: 600,
+        left: 0,
+        width: 800,
+        height: 600,
+        toJSON: () => ({}),
+      });
+    const root = createRoot(container);
+
+    try {
+      await act(async () => {
+        root.render(
+          <MultiScreenCanvas
+            screens={[
+              {
+                id: "screen-a",
+                filename: "screen-a.html",
+                content: "<!doctype html><html><body></body></html>",
+              },
+            ]}
+            zoom={100}
+            activeTool="hand"
+            geometryById={{
+              "screen-a": { x: 100, y: 80, width: 320, height: 640 },
+            }}
+            boardFileId="board"
+            boardFileContent={`<!doctype html><html><body>
+              <div data-agent-native-node-id="negative" data-an-primitive="rectangle" style="position:absolute;left:-165px;top:-90px;width:84px;height:76px"></div>
+            </body></html>`}
+            boardFrameGeometry={{
+              x: -65536,
+              y: -65536,
+              width: 131072,
+              height: 131072,
+            }}
+            boardEditMode
+            onPick={() => {}}
+          />,
+        );
+      });
+
+      const surface = container.querySelector<HTMLElement>('[tabindex="-1"]');
+      const boardLayer = container.querySelector<HTMLElement>(
+        "[data-board-surface-layer]",
+      );
+      const iframe = boardLayer?.querySelector<HTMLIFrameElement>(
+        "iframe[data-design-preview-iframe]",
+      );
+      expect(surface).not.toBeNull();
+      expect(boardLayer).not.toBeNull();
+      expect(iframe).not.toBeNull();
+      const initialLayerLeft = boardLayer!.style.left;
+      const initialSrcdoc = iframe!.srcdoc;
+
+      await act(async () => {
+        dispatchMouse(surface!, "mousedown", 400, 300);
+        dispatchMouse(window, "mousemove", -26_000, 300);
+        await nextAnimationFrame();
+        dispatchMouse(window, "mouseup", -26_000, 300);
+        await nextAnimationFrame();
+      });
+
+      const rewindowedLayer = container.querySelector<HTMLElement>(
+        "[data-board-surface-layer]",
+      );
+      const rewindowedIframe =
+        rewindowedLayer?.querySelector<HTMLIFrameElement>(
+          "iframe[data-design-preview-iframe]",
+        );
+      expect(rewindowedLayer!.style.left).not.toBe(initialLayerLeft);
+      expect(rewindowedIframe).toBe(iframe);
+      expect(rewindowedIframe!.srcdoc).toBe(initialSrcdoc);
+    } finally {
+      await act(async () => root.unmount());
+      rectSpy.mockRestore();
+      container.remove();
+    }
+  });
+
+  it("keeps edge primitives visible and re-focuses the same live iframe when selected at 2% zoom", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const rectSpy = vi
+      .spyOn(HTMLElement.prototype, "getBoundingClientRect")
+      .mockReturnValue({
+        x: 0,
+        y: 0,
+        top: 0,
+        right: 800,
+        bottom: 600,
+        left: 0,
+        width: 800,
+        height: 600,
+        toJSON: () => ({}),
+      });
+    const root = createRoot(container);
+
+    try {
+      await act(async () => {
+        root.render(
+          <MultiScreenCanvas
+            screens={[]}
+            zoom={2}
+            activeTool="move"
+            boardFileId="board"
+            boardFileContent={`<!doctype html><html><body>
+              <script>window.shouldNeverRunInStaticPreview = true</script>
+              <div data-agent-native-node-id="left-edge" data-an-primitive="rectangle" style="position:absolute;left:100px;top:100px;width:100px;height:100px;background:#ef4444"></div>
+              <div data-agent-native-node-id="right-edge" data-an-primitive="text" style="position:absolute;left:35000px;top:100px;color:#3b82f6">Edge label</div>
+            </body></html>`}
+            boardFrameGeometry={{
+              x: -65536,
+              y: -65536,
+              width: 131072,
+              height: 131072,
+            }}
+            boardEditMode
+            onPick={() => {}}
+          />,
+        );
+      });
+
+      const surface = container.querySelector<HTMLElement>('[tabindex="-1"]');
+      const staticPreview = container.querySelector<HTMLElement>(
+        "[data-board-static-preview]",
+      );
+      const staticIframe = staticPreview?.querySelector<HTMLIFrameElement>(
+        "iframe[data-board-static-preview-iframe]",
+      );
+      const activeLayer = container.querySelector<HTMLElement>(
+        "[data-board-surface-layer]",
+      );
+      const activeIframe = activeLayer?.querySelector<HTMLIFrameElement>(
+        "iframe[data-design-preview-iframe]",
+      );
+      expect(surface).not.toBeNull();
+      expect(staticPreview).not.toBeNull();
+      expect(staticIframe).not.toBeNull();
+      expect(activeIframe).not.toBeNull();
+      expect(staticIframe!.getAttribute("sandbox")).toBe("");
+      expect(staticIframe!.getAttribute("sandbox")).not.toContain(
+        "allow-scripts",
+      );
+      expect(staticIframe!.srcdoc).toContain("left-edge");
+      expect(staticIframe!.srcdoc).toContain("right-edge");
+      expect(staticIframe!.srcdoc).not.toContain("<script");
+
+      const initialActiveIframe = activeIframe!;
+      const initialActiveSrcdoc = initialActiveIframe.srcdoc;
+      const initialActiveLeft = activeLayer!.style.left;
+      const postMessage = vi.spyOn(
+        initialActiveIframe.contentWindow!,
+        "postMessage",
+      );
+
+      // pan=0 and zoom=2: screenX=(SURFACE_PADDING+boardX)*0.02.
+      // right-edge is visible near the viewport's right edge but outside the
+      // centered 24,576-world-pixel live iframe.
+      await act(async () => {
+        dispatchMouse(surface!, "mousedown", 706, 8);
+        await nextAnimationFrame();
+        await nextAnimationFrame();
+      });
+
+      const focusedLayer = container.querySelector<HTMLElement>(
+        "[data-board-surface-layer]",
+      );
+      const focusedIframe = focusedLayer?.querySelector<HTMLIFrameElement>(
+        "iframe[data-design-preview-iframe]",
+      );
+      expect(focusedLayer!.style.left).not.toBe(initialActiveLeft);
+      expect(focusedIframe).toBe(initialActiveIframe);
+      expect(focusedIframe!.srcdoc).toBe(initialActiveSrcdoc);
+      expect(postMessage).toHaveBeenCalledWith(
+        {
+          type: "select-element",
+          selector: '[data-agent-native-node-id="right-edge"]',
+          selectorCandidates: ['[data-agent-native-node-id="right-edge"]'],
+        },
+        "*",
+      );
+    } finally {
+      await act(async () => root.unmount());
+      rectSpy.mockRestore();
+      container.remove();
+    }
+  });
+
+  it("cancels a pending static-board handoff when the tool changes before the live post", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const rectSpy = vi
+      .spyOn(HTMLElement.prototype, "getBoundingClientRect")
+      .mockReturnValue({
+        x: 0,
+        y: 0,
+        top: 0,
+        right: 800,
+        bottom: 600,
+        left: 0,
+        width: 800,
+        height: 600,
+        toJSON: () => ({}),
+      });
+    const root = createRoot(container);
+    const boardProps = {
+      screens: [],
+      zoom: 2,
+      boardFileId: "board",
+      boardFileContent: `<!doctype html><html><body>
+        <div data-agent-native-node-id="left-edge" data-an-primitive="rectangle" style="position:absolute;left:100px;top:100px;width:100px;height:100px"></div>
+        <div data-agent-native-node-id="right-edge" data-an-primitive="text" style="position:absolute;left:35000px;top:100px">Edge label</div>
+      </body></html>`,
+      boardFrameGeometry: {
+        x: -65536,
+        y: -65536,
+        width: 131072,
+        height: 131072,
+      },
+    };
+
+    try {
+      await act(async () => {
+        root.render(
+          <MultiScreenCanvas
+            {...boardProps}
+            activeTool="move"
+            boardEditMode
+            onPick={() => {}}
+          />,
+        );
+      });
+      const surface = container.querySelector<HTMLElement>('[tabindex="-1"]')!;
+      const activeIframe = container.querySelector<HTMLIFrameElement>(
+        "[data-board-surface-layer] iframe[data-design-preview-iframe]",
+      )!;
+      const postMessage = vi.spyOn(activeIframe.contentWindow!, "postMessage");
+
+      await act(async () => {
+        dispatchMouse(surface, "mousedown", 706, 8);
+        // Invalidate the pending handoff before its live-bridge frame runs.
+        root.render(
+          <MultiScreenCanvas
+            {...boardProps}
+            activeTool="hand"
+            boardEditMode
+            onPick={() => {}}
+          />,
+        );
+      });
+      await act(async () => {
+        await nextAnimationFrame();
+        await nextAnimationFrame();
+      });
+
+      expect(postMessage).not.toHaveBeenCalledWith(
+        expect.objectContaining({ type: "select-element" }),
+        "*",
+      );
+    } finally {
+      await act(async () => root.unmount());
+      rectSpy.mockRestore();
+      container.remove();
+    }
+  });
 });
 
 describe("cold-open iframe culling", () => {
diff --git a/templates/design/app/components/design/MultiScreenCanvas.primitives.test.ts b/templates/design/app/components/design/MultiScreenCanvas.primitives.test.ts
index 0b6ea7e6c8..a19a752d48 100644
--- a/templates/design/app/components/design/MultiScreenCanvas.primitives.test.ts
+++ b/templates/design/app/components/design/MultiScreenCanvas.primitives.test.ts
@@ -10,7 +10,9 @@ import { computeAltHoverMeasurement } from "./multi-screen/alt-hover-measurement
 import {
   getBoardContentKey,
   getBoardContentLayerSignature,
+  getBoardSurfaceContentBounds,
   getBoardSurfaceRenderContent,
+  getBoardSurfaceStaticPreviewContent,
   hasBoardSurfaceContent,
 } from "./multi-screen/board-surface-html";
 import {
@@ -44,13 +46,20 @@ import {
   isBreakpointSelectionTarget,
 } from "./multi-screen/iframe-targeting";
 import {
+  BOARD_SURFACE_RENDER_MAX_SIZE,
+  boardPointToBoardSurfaceLocalPoint,
+  boardSurfaceLocalPointToBoardPoint,
+  getBoardSurfaceRenderGeometry,
   getBoardSurfaceLayerStyle,
+  getBoardSurfaceStaticPreviewViewport,
+  shouldRenderBoardSurfaceStaticPreview,
   SURFACE_PADDING,
 } from "./multi-screen/overview-layout";
 import {
   __clearPrimitiveParseCachesForTests,
   __getPrimitiveParseCacheSizesForTests,
   getPrimitiveDropTargetForPoint,
+  isPrimitiveContainer,
   parsePrimitivesFromScreen,
   primitiveLocalToBoardRect,
   primitiveParseCache,
@@ -132,6 +141,167 @@ describe("board surface pointer capture", () => {
     expect(style.pointerEvents).toBe("auto");
   });
 
+  it("bounds negative and positive board nodes in persisted canvas coordinates", () => {
+    const bounds = getBoardSurfaceContentBounds(`<!doctype html><body>
+      <div data-agent-native-node-id="negative" data-an-primitive="rectangle" style="position:absolute;left:-165px;top:-90px;width:84px;height:76px"></div>
+      <div data-agent-native-node-id="positive" data-an-primitive="rectangle" style="position:absolute;left:329px;top:210px;width:100px;height:60px"></div>
+    </body>`);
+
+    expect(bounds).toEqual({ x: -165, y: -90, width: 594, height: 360 });
+  });
+
+  it("includes nested overflow and ignores an instrumented document body", () => {
+    expect(
+      getBoardSurfaceContentBounds(
+        '<html><body data-agent-native-node-id="body"></body></html>',
+      ),
+    ).toBeNull();
+
+    const bounds =
+      getBoardSurfaceContentBounds(`<!doctype html><body data-agent-native-node-id="body">
+      <div data-agent-native-node-id="parent" data-an-primitive="frame" style="position:absolute;left:300px;top:100px;width:100px;height:100px">
+        <div data-agent-native-node-id="overflow" data-an-primitive="rectangle" style="position:absolute;left:140px;top:120px;width:80px;height:60px"></div>
+      </div>
+    </body>`);
+    expect(bounds).toEqual({ x: 300, y: 100, width: 220, height: 180 });
+  });
+
+  it("uses a browser-safe chunked paint window without changing logical board coordinates", () => {
+    const logical = makeGeom(-65536, -65536, 131072, 131072);
+    const negativeBounds = makeGeom(-165, -90, 84, 76);
+    const screens = [makeGeom(100, 80, 320, 640)];
+    const geometry = getBoardSurfaceRenderGeometry({
+      logicalGeometry: logical,
+      contentBounds: negativeBounds,
+      screenGeometries: screens,
+    });
+
+    expect(geometry).toEqual({
+      x: -4096,
+      y: -4096,
+      width: 8192,
+      height: 8192,
+    });
+    expect(geometry.width).toBeLessThanOrEqual(BOARD_SURFACE_RENDER_MAX_SIZE);
+    expect(geometry.height).toBeLessThanOrEqual(BOARD_SURFACE_RENDER_MAX_SIZE);
+    // The iframe-local coordinate round-trip lands at the exact persisted
+    // negative board coordinate; no fixed +/-65536 projection is involved.
+    const iframeLocalX = negativeBounds.x - geometry.x;
+    const iframeLocalY = negativeBounds.y - geometry.y;
+    expect(geometry.x + iframeLocalX).toBe(negativeBounds.x);
+    expect(geometry.y + iframeLocalY).toBe(negativeBounds.y);
+  });
+
+  it("keeps the render origin stable for nearby edits inside the same chunk", () => {
+    const logical = makeGeom(-65536, -65536, 131072, 131072);
+    const before = getBoardSurfaceRenderGeometry({
+      logicalGeometry: logical,
+      contentBounds: makeGeom(-165, -90, 84, 76),
+      screenGeometries: [makeGeom(100, 80, 320, 640)],
+    });
+    const after = getBoardSurfaceRenderGeometry({
+      logicalGeometry: logical,
+      contentBounds: makeGeom(329, 210, 100, 60),
+      screenGeometries: [makeGeom(100, 80, 320, 640)],
+    });
+
+    expect(after).toEqual(before);
+  });
+
+  it("keeps a low-zoom viewport browser-bounded while following its center", () => {
+    const logical = makeGeom(-65536, -65536, 131072, 131072);
+    // At the canvas minimum zoom (2%), a 1440x900 viewport spans 72,000 x
+    // 45,000 board pixels. One iframe intentionally remains capped below
+    // that span; it follows the live viewport center instead of regressing to
+    // the origin or allocating the old 131,072px document.
+    const lowZoomViewport = makeGeom(18_000, -12_000, 72_000, 45_000);
+    const geometry = getBoardSurfaceRenderGeometry({
+      logicalGeometry: logical,
+      contentBounds: makeGeom(-165, -90, 84, 76),
+      screenGeometries: [lowZoomViewport],
+      focus: {
+        x: lowZoomViewport.x + lowZoomViewport.width / 2,
+        y: lowZoomViewport.y + lowZoomViewport.height / 2,
+      },
+    });
+
+    expect(geometry.width).toBe(BOARD_SURFACE_RENDER_MAX_SIZE);
+    expect(geometry.height).toBe(BOARD_SURFACE_RENDER_MAX_SIZE);
+    expect(geometry.x).toBe(40_960);
+    expect(geometry.y).toBe(-4096);
+    expect(geometry.x + geometry.width / 2).toBeCloseTo(53_248, 0);
+    expect(geometry.y + geometry.height / 2).toBeCloseTo(8192, 0);
+  });
+
+  it("covers a 2% viewport with one uniformly compressed inert board preview", () => {
+    const logical = makeGeom(-65536, -65536, 131072, 131072);
+    const active = makeGeom(-12288, -12288, 24576, 24576);
+    const viewport = makeGeom(-36000, -22500, 72000, 45000);
+    const staticViewport = getBoardSurfaceStaticPreviewViewport(logical);
+
+    expect(
+      shouldRenderBoardSurfaceStaticPreview({
+        zoom: 2,
+        viewportGeometry: viewport,
+        renderGeometry: active,
+      }),
+    ).toBe(true);
+    expect(staticViewport).toEqual({ width: 4096, height: 4096 });
+
+    const content = getBoardSurfaceStaticPreviewContent({
+      html: `<!doctype html><html><head>
+        <meta http-equiv="refresh" content="0;url=https://example.test">
+        <base href="https://example.test/">
+        <link rel="stylesheet" href="https://example.test/app.css">
+        <style>@import "https://example.test/import.css";.remote{background-image:url(https://example.test/bg.png);animation:pulse 1s infinite;transition:all 1s}</style>
+        <script>window.duplicateRuntime = true</script>
+      </head><body onload="start()">
+        <iframe src="https://example.test/embed"></iframe>
+        <object data="https://example.test/runtime"></object>
+        <embed src="https://example.test/plugin">
+        <audio autoplay src="https://example.test/audio.mp3"></audio>
+        <video autoplay src="https://example.test/video.mp4"></video>
+        <img src="https://example.test/image.png" srcset="https://example.test/image@2x.png 2x" style="background:url(https://example.test/inline.png)">
+        <svg><image href="https://example.test/vector.png"></image><use xlink:href="https://example.test/icons.svg#star"></use></svg>
+        <div data-agent-native-node-id="left" style="position:absolute;left:-50000px;top:0;width:100px;height:100px"></div>
+        <div data-agent-native-node-id="right" style="position:absolute;left:50000px;top:0;width:100px;height:100px"></div>
+      </body></html>`,
+      logicalGeometry: logical,
+      viewport: staticViewport,
+    });
+
+    expect(content).toContain("transform:scale(0.03125)!important");
+    expect(content).toContain("translate:65536px 65536px!important");
+    expect(content).toContain('data-agent-native-node-id="left"');
+    expect(content).toContain('data-agent-native-node-id="right"');
+    expect(content).not.toMatch(/<script|onload=|<iframe|<object|<embed/i);
+    expect(content).not.toMatch(/<audio|<video|autoplay|http-equiv="refresh"/i);
+    expect(content).not.toMatch(/<link|<meta|<base|@import|url\(/i);
+    expect(content).not.toContain("https://example.test");
+    expect(content).toContain("animation:none!important");
+    expect(content).toContain("transition:none!important");
+  });
+
+  it("round-trips board drag and hit-test points through the finite iframe origin", () => {
+    const renderGeometry = makeGeom(-4096, -4096, 8192, 8192);
+    for (const boardPoint of [
+      { x: -165, y: -90 },
+      { x: 329, y: 210 },
+    ]) {
+      const localPoint = boardPointToBoardSurfaceLocalPoint(
+        boardPoint,
+        renderGeometry,
+      );
+      expect(localPoint.x).toBeGreaterThanOrEqual(0);
+      expect(localPoint.y).toBeGreaterThanOrEqual(0);
+      expect(localPoint.x).toBeLessThan(renderGeometry.width);
+      expect(localPoint.y).toBeLessThan(renderGeometry.height);
+      expect(
+        boardSurfaceLocalPointToBoardPoint(localPoint, renderGeometry),
+      ).toEqual(boardPoint);
+    }
+  });
+
   it("treats empty board documents as having no surface content", () => {
     expect(
       hasBoardSurfaceContent(
@@ -640,6 +810,33 @@ describe("parsePrimitivesFromScreen cache key", () => {
 // the full content string and return the memoized result directly.
 // ---------------------------------------------------------------------------
 describe("parsePrimitivesFromScreen identity cache", () => {
+  it("treats a plain canvas frame as a child-drop container before Auto layout", () => {
+    expect(
+      isPrimitiveContainer({
+        tagName: "div",
+        primitiveKind: "frame",
+        display: "",
+        borderRadius: "",
+      }),
+    ).toBe(true);
+    expect(
+      isPrimitiveContainer({
+        tagName: "div",
+        primitiveKind: "text",
+        display: "inline-block",
+        borderRadius: "",
+      }),
+    ).toBe(false);
+    expect(
+      isPrimitiveContainer({
+        tagName: "div",
+        primitiveKind: "ellipse",
+        display: "",
+        borderRadius: "50%",
+      }),
+    ).toBe(false);
+  });
+
   it("returns the same result reference for repeated calls with unchanged content", () => {
     const screen: ScreenStub = {
       id: "identity-screen",
diff --git a/templates/design/app/components/design/MultiScreenCanvas.tsx b/templates/design/app/components/design/MultiScreenCanvas.tsx
index f5cb043922..0b3255a2e2 100644
--- a/templates/design/app/components/design/MultiScreenCanvas.tsx
+++ b/templates/design/app/components/design/MultiScreenCanvas.tsx
@@ -15,7 +15,7 @@ import {
   getResizeCursorForHandle,
   resizeFrameGroupFromDelta,
   resizeFrameGroupToBounds,
-  resizeRotatedFrameFromDelta,
+  resizeRotatedFrameFromDeltaWithSnap,
   rotateFrameGroupAroundCenter,
   rotatedRectIntersects,
   screenToCanvasPoint,
@@ -152,6 +152,7 @@ const EMPTY_SELECTED_LAYER_SELECTOR_GROUPS_BY_SCREEN: Record<
   string,
   string[][]
 > = {};
+const EMPTY_SCREEN_IDS: readonly string[] = [];
 // Shared with canvas-math.ts (DEFAULT_CANVAS_MIN_ZOOM/DEFAULT_CANVAS_MAX_ZOOM)
 // so this surface's zoom clamp lives in one place instead of being
 // redeclared locally and drifting from the shared constant.
@@ -165,7 +166,9 @@ import {
   BOARD_SURFACE_BACKGROUND,
   getBoardContentKey,
   getBoardContentLayerSignature,
+  getBoardSurfaceContentBounds,
   getBoardSurfaceRenderContent,
+  getBoardSurfaceStaticPreviewContent,
   hasBoardSurfaceContent,
 } from "./multi-screen/board-surface-html";
 import {
@@ -197,9 +200,14 @@ import {
   isBreakpointSelectionTarget,
 } from "./multi-screen/iframe-targeting";
 import {
+  boardPointToBoardSurfaceLocalPoint,
+  boardSurfaceLocalPointToBoardPoint,
+  getBoardSurfaceRenderGeometry,
   getBoardSurfaceLayerStyle,
+  getBoardSurfaceStaticPreviewViewport,
   isLineupShrinkOnlyChange,
   OVERVIEW_FRAME_WIDTH,
+  shouldRenderBoardSurfaceStaticPreview,
   shouldSuppressLineupRecenter,
   SURFACE_PADDING,
   type LineupRecenterDuplicateArm,
@@ -280,6 +288,7 @@ import {
   findTopFrameEntryAtPoint,
   frameGeometryWithOverrides,
   frameStyleLeftTop,
+  geometryContainsPoint,
   getBreakpointFrameGeometry,
   getFrameCenter,
   getInitialFrameGeometry,
@@ -302,17 +311,84 @@ import {
 } from "./multi-screen/gradient-overlay-geometry";
 import {
   getPrimitiveDropTargetForPoint,
+  getPrimitiveLowZoomHitRect,
+  parsePrimitivesFromScreen,
   resolveNodeScreenId,
   type PrimitiveDropTarget,
 } from "./multi-screen/primitive-drop-target";
 import type { AlignmentGuide, CanvasFrameEntry } from "./multi-screen/types";
 import { vectorEditCanvasToLocalPoint } from "./multi-screen/vector-edit-geometry";
 
+/**
+ * Imperatively writes a draft primitive's full visual state onto its cached
+ * DOM node — the outer box (left/top/width/height/rotation, matching
+ * DraftPrimitiveLayer's own inline style) plus, for kinds whose rendered
+ * content depends on geometry rather than plain CSS 100%-sizing (path/line/
+ * arrow's <path d>+viewBox, polygon/star's <polygon points>+viewBox), the
+ * inner SVG content too. Used by beginDraftResize's live mousemove tick (PERF9:
+ * ref-only writes instead of setDraftPrimitives per tick) and by
+ * cancelActiveDrag's Escape-cancel restore, so both paths stay in sync with
+ * exactly what DraftPrimitiveLayer/DraftPrimitiveContent would have rendered.
+ * rect/ellipse/text/frame kinds need no extra work here: their content divs
+ * are `size-full` and already track the outer box via normal CSS layout.
+ */
+function applyDraftPrimitiveToDom(
+  element: HTMLElement,
+  draft: DraftPrimitive,
+): void {
+  const { geometry } = draft;
+  const { left, top } = frameStyleLeftTop(geometry);
+  element.style.left = `${left}px`;
+  element.style.top = `${top}px`;
+  element.style.width = `${geometry.width}px`;
+  element.style.height = `${geometry.height}px`;
+  element.style.transform = geometry.rotation
+    ? `rotate(${geometry.rotation}deg)`
+    : "";
+
+  if (
+    draft.kind === "path" ||
+    draft.kind === "line" ||
+    draft.kind === "arrow"
+  ) {
+    const svgEl = element.querySelector("svg");
+    const pathEl = element.querySelector("path");
+    svgEl?.setAttribute(
+      "viewBox",
+      `${geometry.x} ${geometry.y} ${geometry.width} ${geometry.height}`,
+    );
+    if (pathEl) {
+      const pathData =
+        draft.pathData ??
+        (draft.penPath
+          ? serializePenPath(draft.penPath)
+          : pointsToPath(draft.points ?? []));
+      pathEl.setAttribute("d", pathData);
+      if (draft.strokeWidth !== undefined) {
+        pathEl.setAttribute("stroke-width", String(draft.strokeWidth));
+      }
+    }
+  } else if (draft.kind === "polygon" || draft.kind === "star") {
+    const svgEl = element.querySelector("svg");
+    const polygonEl = element.querySelector("polygon");
+    svgEl?.setAttribute(
+      "viewBox",
+      `0 0 ${Math.max(1, geometry.width)} ${Math.max(1, geometry.height)}`,
+    );
+    polygonEl?.setAttribute(
+      "points",
+      polygonPointsForBox(draft.kind, geometry.width, geometry.height),
+    );
+  }
+}
+
 export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   screens,
   zoom,
   activeId,
   selectedScreenIds,
+  hiddenScreenIds = EMPTY_SCREEN_IDS,
+  lockedScreenIds = EMPTY_SCREEN_IDS,
   fullViewScreenIds,
   activeScreenHasHoveredChild = false,
   hoveredChildScreenId,
@@ -431,9 +507,179 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   // error, not just a stale-closure risk). Kept in sync by the effect right
   // below the other prop/state-mirroring refs (see onGeometryChangeRef etc.).
   const effectiveToolRef = useRef<MultiScreenCanvasTool>("move");
-  const [selectedIds, setSelectedIds] = useState<string[]>(
-    selectedScreenIds ?? [],
+  const hiddenScreenIdSet = useMemo(
+    () => new Set(hiddenScreenIds),
+    [hiddenScreenIds],
+  );
+  const lockedScreenIdSet = useMemo(
+    () => new Set(lockedScreenIds),
+    [lockedScreenIds],
+  );
+  const renderedScreens = useMemo(
+    () => screens.filter((screen) => !hiddenScreenIdSet.has(screen.id)),
+    [hiddenScreenIdSet, screens],
+  );
+  const selectableScreens = useMemo(
+    () => renderedScreens.filter((screen) => !lockedScreenIdSet.has(screen.id)),
+    [lockedScreenIdSet, renderedScreens],
+  );
+  const [selectedIds, setSelectedIds] = useState<string[]>(() =>
+    (selectedScreenIds ?? []).filter((id) =>
+      selectableScreens.some((screen) => screen.id === id),
+    ),
+  );
+  const screenIndexById = useMemo(
+    () => new Map(screens.map((screen, index) => [screen.id, index] as const)),
+    [screens],
+  );
+  const [boardSurfaceFocusPoint, setBoardSurfaceFocusPoint] =
+    useState<Point | null>(null);
+  const pendingStaticBoardSelectionRef = useRef<{
+    nodeId: string;
+    point: Point;
+  } | null>(null);
+  const cancelPendingStaticBoardSelection = useCallback(() => {
+    pendingStaticBoardSelectionRef.current = null;
+    setBoardSurfaceFocusPoint(null);
+  }, []);
+  const boardSurfaceContentBounds = useMemo(
+    () => getBoardSurfaceContentBounds(boardFileContent),
+    [boardFileContent],
+  );
+  const boardViewportGeometry = useMemo((): FrameGeometry | undefined => {
+    if (surfaceSize.width <= 0 || surfaceSize.height <= 0) return undefined;
+    const scale = Math.max(0.0001, canvasZoom / 100);
+    return {
+      x: -pan.x / scale - SURFACE_PADDING,
+      y: -pan.y / scale - SURFACE_PADDING,
+      width: surfaceSize.width / scale,
+      height: surfaceSize.height / scale,
+    };
+  }, [canvasZoom, pan.x, pan.y, surfaceSize.height, surfaceSize.width]);
+  const boardSurfaceRenderGeometry = useMemo(() => {
+    if (!boardFrameGeometry) return undefined;
+    const focusGeometry = boardSurfaceFocusPoint
+      ? {
+          x: boardSurfaceFocusPoint.x,
+          y: boardSurfaceFocusPoint.y,
+          width: 1,
+          height: 1,
+        }
+      : (boardViewportGeometry ?? boardSurfaceContentBounds);
+    return getBoardSurfaceRenderGeometry({
+      logicalGeometry: boardFrameGeometry,
+      contentBounds: boardSurfaceContentBounds,
+      screenGeometries: [
+        ...Object.values(frameGeometry),
+        ...(boardViewportGeometry ? [boardViewportGeometry] : []),
+      ],
+      focus: focusGeometry ? getFrameCenter(focusGeometry) : undefined,
+    });
+  }, [
+    boardFrameGeometry,
+    boardSurfaceContentBounds,
+    boardSurfaceFocusPoint,
+    boardViewportGeometry,
+    frameGeometry,
+  ]);
+  const boardStaticPreviewViewport = useMemo(
+    () =>
+      boardFrameGeometry
+        ? getBoardSurfaceStaticPreviewViewport(boardFrameGeometry)
+        : null,
+    [boardFrameGeometry],
   );
+  const boardStaticPreviewContent = useMemo(() => {
+    if (
+      !boardFrameGeometry ||
+      !boardStaticPreviewViewport ||
+      !boardFileContent
+    ) {
+      return null;
+    }
+    return getBoardSurfaceStaticPreviewContent({
+      html: boardFileContent,
+      logicalGeometry: boardFrameGeometry,
+      viewport: boardStaticPreviewViewport,
+    });
+  }, [boardFileContent, boardFrameGeometry, boardStaticPreviewViewport]);
+  const showBoardStaticPreview = Boolean(
+    boardFrameGeometry &&
+    boardSurfaceRenderGeometry &&
+    boardStaticPreviewContent &&
+    shouldRenderBoardSurfaceStaticPreview({
+      zoom: canvasZoom,
+      viewportGeometry: boardViewportGeometry,
+      renderGeometry: boardSurfaceRenderGeometry,
+    }),
+  );
+  const boardStaticPrimitives = useMemo(() => {
+    if (!boardFileId || !boardFileContent) return [];
+    return parsePrimitivesFromScreen({
+      id: boardFileId,
+      filename: "__board__.html",
+      content: boardFileContent,
+    });
+  }, [boardFileContent, boardFileId]);
+  useEffect(() => {
+    cancelPendingStaticBoardSelection();
+  }, [cancelPendingStaticBoardSelection, canvasZoom, pan.x, pan.y]);
+  useEffect(() => {
+    cancelPendingStaticBoardSelection();
+  }, [
+    activeTool,
+    boardFileContent,
+    boardFileId,
+    boardFrameGeometry?.height,
+    boardFrameGeometry?.width,
+    boardFrameGeometry?.x,
+    boardFrameGeometry?.y,
+    cancelPendingStaticBoardSelection,
+    localActiveTool,
+  ]);
+  useEffect(() => {
+    if (!showBoardStaticPreview) cancelPendingStaticBoardSelection();
+  }, [cancelPendingStaticBoardSelection, showBoardStaticPreview]);
+  useEffect(() => {
+    const pending = pendingStaticBoardSelectionRef.current;
+    if (
+      !pending ||
+      !boardFileId ||
+      !boardSurfaceRenderGeometry ||
+      !geometryContainsPoint(boardSurfaceRenderGeometry, pending.point)
+    ) {
+      return;
+    }
+    const selector = `[data-agent-native-node-id="${CSS.escape(pending.nodeId)}"]`;
+    let secondFrame: number | null = null;
+    const firstFrame = window.requestAnimationFrame(() => {
+      secondFrame = window.requestAnimationFrame(() => {
+        if (pendingStaticBoardSelectionRef.current !== pending) return;
+        const iframe = findCanvasIframeForScreen(
+          surfaceRef.current,
+          boardFileId,
+          boardFileId,
+        );
+        const targetWindow = iframe?.contentWindow;
+        if (!targetWindow) return;
+        targetWindow.postMessage(
+          {
+            type: "select-element",
+            selector,
+            selectorCandidates: [selector],
+          },
+          "*",
+        );
+        if (pendingStaticBoardSelectionRef.current === pending) {
+          pendingStaticBoardSelectionRef.current = null;
+        }
+      });
+    });
+    return () => {
+      window.cancelAnimationFrame(firstFrame);
+      if (secondFrame !== null) window.cancelAnimationFrame(secondFrame);
+    };
+  }, [boardFileId, boardSurfaceRenderGeometry]);
   const selectedIdsRef = useRef(selectedIds);
   const dragState = useRef<DragState | null>(null);
   const dragCleanup = useRef<(() => void) | null>(null);
@@ -508,6 +754,12 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   );
   const [duplicatePreview, setDuplicatePreview] =
     useState<DuplicatePreview | null>(null);
+  // PERF9: DOM node backing the alt-drag duplicate ghost, cached so
+  // beginDuplicateGesture's live mousemove tick can write left/top directly
+  // instead of calling setDuplicatePreview (a full re-render) every frame —
+  // same "mutate the DOM now, commit React state only when something
+  // conditional actually changes" discipline as the frame/draft drag paths.
+  const duplicatePreviewElRef = useRef<HTMLDivElement | null>(null);
   const [transformBadge, setTransformBadge] = useState<TransformBadge | null>(
     null,
   );
@@ -965,7 +1217,12 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     // to the first selected/first-on-board screen in that case. Mirror the
     // same fallback chain so the anchor matches whichever frame actually
     // drove the zoom-scale recompute.
-    const referenceId = activeId ?? selectedIds[0] ?? screens[0]?.id;
+    const referenceId =
+      (activeId && renderedScreens.some((screen) => screen.id === activeId)
+        ? activeId
+        : undefined) ??
+      selectedIds[0] ??
+      renderedScreens[0]?.id;
     const rect = surfaceRef.current?.getBoundingClientRect();
     // Prefer the `geometryById` prop over `frameGeometryRef` here: a screen
     // just created by the frame tool has its geometry committed straight
@@ -1018,10 +1275,10 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     // P18: an externally-driven zoom change (toolbar/keyboard) also moves
     // the canvas-space mapping the pen ghost preview was computed from.
     recomputePenPointerForViewChangeRef.current();
-  }, [zoom, activeId]);
+  }, [zoom, activeId, renderedScreens, selectedIds]);
 
   useEffect(() => {
-    const currentIds = new Set(screens.map((screen) => screen.id));
+    const selectableIds = new Set(selectableScreens.map((screen) => screen.id));
     // B5-9: see resolveFrameGeometrySync's doc comment — this used to notify
     // the parent (onGeometryChange -> queueFrameGeometrySave) with a brand
     // new screen's disposable getInitialFrameGeometry() fallback before its
@@ -1046,13 +1303,14 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       }
     }
     updateSelectedIds((current) => {
-      const next = current.filter((id) => currentIds.has(id));
+      const next = current.filter((id) => selectableIds.has(id));
       return next.length === current.length ? current : next;
     });
   }, [
     geometryById,
     getResolvedMetadata,
     screens,
+    selectableScreens,
     updateFrameGeometry,
     updateFrameGeometryRefOnly,
     updateSelectedIds,
@@ -1087,11 +1345,15 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
   useEffect(() => {
     if (!selectedScreenIds) return;
+    const selectableIds = new Set(selectableScreens.map((screen) => screen.id));
+    const nextSelection = selectedScreenIds.filter((id) =>
+      selectableIds.has(id),
+    );
     // Remember the selection we're pushing in from the parent so the report
     // effects above can recognise (and not echo back) the resulting change.
-    propSyncedSelectionRef.current = selectedScreenIds;
-    updateSelectedIds(() => selectedScreenIds);
-  }, [screens, selectedScreenIds, updateSelectedIds]);
+    propSyncedSelectionRef.current = nextSelection;
+    updateSelectedIds(() => nextSelection);
+  }, [selectableScreens, selectedScreenIds, updateSelectedIds]);
 
   useEffect(() => {
     if (
@@ -1102,8 +1364,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     }
     handledSelectAllRequestRef.current = selectAllRequest;
     updateSelectedDraftIds(() => []);
-    updateSelectedIds(() => screens.map((screen) => screen.id));
-  }, [screens, selectAllRequest, updateSelectedDraftIds, updateSelectedIds]);
+    updateSelectedIds(() => selectableScreens.map((screen) => screen.id));
+  }, [
+    selectAllRequest,
+    selectableScreens,
+    updateSelectedDraftIds,
+    updateSelectedIds,
+  ]);
 
   useEffect(() => {
     if (
@@ -1158,14 +1425,14 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       }
       return;
     }
-    if (!surfaceRef.current || screens.length === 0) return;
+    if (!surfaceRef.current || renderedScreens.length === 0) return;
     const rect = surfaceRef.current.getBoundingClientRect();
     const scale = zoomRef.current / 100;
-    const frames = screens.map((screen, index) => {
+    const frames = renderedScreens.map((screen) => {
       const metadata = getResolvedMetadata(screen);
       const currentGeometry =
         frameGeometryRef.current[screen.id] ??
-        getInitialFrameGeometry(index, metadata);
+        getInitialFrameGeometry(screenIndexById.get(screen.id) ?? 0, metadata);
       return getPreviewDeviceFrameGeometry({
         currentGeometry,
         metadata,
@@ -1174,7 +1441,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     });
     const bounds = getFrameGroupBounds(
       frames.map((geometry, index) => ({
-        id: screens[index]?.id ?? String(index),
+        id: renderedScreens[index]?.id ?? String(index),
         geometry,
       })),
     );
@@ -1194,7 +1461,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     // Leave a Figma-like board gutter beside the last frame for quick drops/draws,
     // and fit tall single frames so lower canvas interactions remain reachable.
     const widthFitScale =
-      screens.length > 1 && totalWidth > 0
+      renderedScreens.length > 1 && totalWidth > 0
         ? Math.max(0.1, (rect.width - 180) / totalWidth)
         : scale;
     const heightFitScale =
@@ -1273,16 +1540,27 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
   const getCurrentFrameEntries = useCallback(
     () =>
-      screens.map((screen, index) => {
+      renderedScreens.map((screen) => {
         const metadata = getResolvedMetadata(screen);
         return {
           id: screen.id,
           geometry:
             frameGeometryRef.current[screen.id] ??
-            getInitialFrameGeometry(index, metadata),
+            getInitialFrameGeometry(
+              screenIndexById.get(screen.id) ?? 0,
+              metadata,
+            ),
         };
       }),
-    [getResolvedMetadata, screens],
+    [getResolvedMetadata, renderedScreens, screenIndexById],
+  );
+
+  const getSelectableFrameEntries = useCallback(
+    () =>
+      getCurrentFrameEntries().filter(
+        (entry) => !lockedScreenIdSet.has(entry.id),
+      ),
+    [getCurrentFrameEntries, lockedScreenIdSet],
   );
 
   const getCurrentDraftEntries = useCallback(
@@ -1301,7 +1579,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
   const getFrameEntryAtPoint = useCallback(
     (point: Point) =>
-      findTopFrameEntryAtPoint(getCurrentFrameEntries(), point, {
+      findTopFrameEntryAtPoint(getSelectableFrameEntries(), point, {
         // Screen wrappers give this same id a large z-index boost. Geometry
         // hit testing must mirror it or drops/draws on overlapping frames can
         // persist into a visually obscured sibling.
@@ -1313,7 +1591,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             ? activeId
             : screensRef.current[0]?.id),
       }),
-    [activeId, getCurrentFrameEntries],
+    [activeId, getSelectableFrameEntries],
   );
 
   // Mirrors getFrameEntryAtPoint above, but hit-tests draft primitives
@@ -1453,8 +1731,10 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       const iframeId = targetScreen
         ? getActiveScreenIframeId(targetScreen)
         : targetId;
-      const targetIframe = surfaceRef.current?.querySelector<HTMLIFrameElement>(
-        `[data-screen-iframe-id="${CSS.escape(iframeId)}"]`,
+      const targetIframe = findCanvasIframeForScreen(
+        surfaceRef.current,
+        iframeId,
+        boardFileId,
       );
       targetIframe?.contentWindow?.postMessage(
         { type: "agent-native:hit-test-preview-clear" },
@@ -1525,21 +1805,44 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       const targetScreen = screensRef.current.find(
         (s) => s.id === candidate.id,
       );
-      if (!targetScreen) return Promise.resolve({});
-      const targetGeometry = candidate.geometry;
-      const targetIframeId = CSS.escape(getActiveScreenIframeId(targetScreen));
-      const targetIframe = surfaceRef.current?.querySelector<HTMLIFrameElement>(
-        `[data-screen-iframe-id="${targetIframeId}"]`,
-      );
+      const targetIsBoard = candidate.id === boardFileId;
+      if (!targetScreen && !targetIsBoard) return Promise.resolve({});
+      if (targetIsBoard && !boardSurfaceRenderGeometry) {
+        return Promise.resolve({});
+      }
+      const targetIframe = targetIsBoard
+        ? findCanvasIframeForScreen(
+            surfaceRef.current,
+            candidate.id,
+            boardFileId,
+          )
+        : surfaceRef.current?.querySelector<HTMLIFrameElement>(
+            `[data-screen-iframe-id="${CSS.escape(
+              getActiveScreenIframeId(targetScreen!),
+            )}"]`,
+          );
       const targetContentWindow = targetIframe?.contentWindow;
       if (!targetContentWindow) return Promise.resolve({});
-      const { width: targetViewportWidth, height: targetViewportHeight } =
-        getTargetViewportMetadata(targetScreen, targetIframe);
-      const localPoint = boardPointToScreenLocalPoint(
-        boardPoint,
-        targetGeometry,
-        { width: targetViewportWidth, height: targetViewportHeight },
-      );
+      const localPoint =
+        targetIsBoard && boardSurfaceRenderGeometry
+          ? boardPointToBoardSurfaceLocalPoint(
+              boardPoint,
+              boardSurfaceRenderGeometry,
+            )
+          : (() => {
+              const {
+                width: targetViewportWidth,
+                height: targetViewportHeight,
+              } = getTargetViewportMetadata(targetScreen!, targetIframe);
+              return boardPointToScreenLocalPoint(
+                boardPoint,
+                candidate.geometry,
+                {
+                  width: targetViewportWidth,
+                  height: targetViewportHeight,
+                },
+              );
+            })();
 
       const correlationId = `hit-${Date.now()}-${Math.random()
         .toString(36)
@@ -1652,14 +1955,20 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         const targetScreen = screensRef.current.find(
           (s) => s.id === candidate.id,
         );
-        const targetIframeId = targetScreen
-          ? CSS.escape(getActiveScreenIframeId(targetScreen))
-          : null;
-        const targetIframe = targetIframeId
+        const targetIsBoard = candidate.id === boardFileId;
+        const targetIframe = targetScreen
           ? surfaceRef.current?.querySelector<HTMLIFrameElement>(
-              `[data-screen-iframe-id="${targetIframeId}"]`,
+              `[data-screen-iframe-id="${CSS.escape(
+                getActiveScreenIframeId(targetScreen),
+              )}"]`,
             )
-          : null;
+          : targetIsBoard
+            ? findCanvasIframeForScreen(
+                surfaceRef.current,
+                candidate.id,
+                boardFileId,
+              )
+            : null;
         const guide = targetScreen
           ? getCrossScreenDropGuideForHitTest({
               hit,
@@ -1669,7 +1978,20 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
                 targetIframe,
               ),
             })
-          : null;
+          : targetIsBoard && boardSurfaceRenderGeometry
+            ? getCrossScreenDropGuideForHitTest({
+                hit,
+                targetGeometry: boardSurfaceRenderGeometry,
+                targetMetadata: {
+                  width:
+                    targetIframe?.clientWidth ||
+                    boardSurfaceRenderGeometry.width,
+                  height:
+                    targetIframe?.clientHeight ||
+                    boardSurfaceRenderGeometry.height,
+                },
+              })
+            : null;
         setCrossScreenDropGuide(guide);
       });
     };
@@ -1706,6 +2028,20 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
               : { boardX: boardPoint.x, boardY: boardPoint.y },
         );
         requestCrossScreenDropGuide(nextTarget, boardPoint);
+      } else if (
+        sourceScreenId !== boardFileId &&
+        boardFileId &&
+        boardFrameGeometry &&
+        geometryContainsPoint(boardFrameGeometry, boardPoint)
+      ) {
+        const nextTarget = { id: boardFileId, geometry: boardFrameGeometry };
+        if (crossScreenTargetRef.current?.id !== boardFileId) {
+          clearCrossScreenPreviewGuide();
+        }
+        crossScreenTargetRef.current = nextTarget;
+        setCrossScreenTarget(nextTarget);
+        setCrossScreenGhost({ boardX: boardPoint.x, boardY: boardPoint.y });
+        requestCrossScreenDropGuide(nextTarget, boardPoint);
       } else {
         clearCrossScreenPreviewGuide();
         crossScreenTargetRef.current = null;
@@ -1741,16 +2077,45 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       if (!targetCandidate) return;
 
       if (targetCandidate.id === boardFileId) {
-        onCrossScreenElementDropRef.current?.({
-          sourceSelector: payload.selector,
-          sourceNodeId: payload.sourceId,
-          sourceScreenId,
-          targetScreenId: targetCandidate.id,
-          targetCanvasPoint: lastBoardPoint,
-          targetLocalPoint: lastBoardPoint,
-          sourcePointerOffset: payload.sourcePointerOffset,
-          styleSnapshot: payload.styleSnapshot,
-        });
+        void runHitTest(targetCandidate, lastBoardPoint).then(
+          ({
+            anchorNodeId,
+            pendingNodeId,
+            anchorSelector,
+            placement,
+            dropMode,
+            anchorRect,
+          }) => {
+            const hasAnchor = Boolean(
+              anchorNodeId || pendingNodeId || anchorSelector,
+            );
+            onCrossScreenElementDropRef.current?.({
+              sourceSelector: payload.selector,
+              sourceNodeId: payload.sourceId,
+              sourceScreenId,
+              targetScreenId: targetCandidate.id,
+              targetAnchorNodeId: anchorNodeId,
+              targetAnchorPendingNodeId: pendingNodeId,
+              targetAnchorSelector: anchorSelector,
+              targetAnchorPlacement: placement,
+              targetDropMode: dropMode,
+              targetAnchorRect: anchorRect,
+              targetCanvasPoint: lastBoardPoint,
+              // Anchor rects come from the finite board iframe and are local
+              // to its render window. Use the same local space for nested
+              // placement; root-level board drops keep persisted board coords.
+              targetLocalPoint:
+                hasAnchor && boardSurfaceRenderGeometry
+                  ? boardPointToBoardSurfaceLocalPoint(
+                      lastBoardPoint,
+                      boardSurfaceRenderGeometry,
+                    )
+                  : lastBoardPoint,
+              sourcePointerOffset: payload.sourcePointerOffset,
+              styleSnapshot: payload.styleSnapshot,
+            });
+          },
+        );
         return;
       }
 
@@ -2048,11 +2413,17 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         let boardX: number;
         let boardY: number;
 
-        if (sourceScreenId === boardFileId && boardFrameGeometry) {
+        if (sourceScreenId === boardFileId && boardSurfaceRenderGeometry) {
           // The board iframe is pixel-exact: 1 iframe pixel == 1 canvas unit.
-          // iframeX/iframeY are already in canvas space (no scale needed).
-          boardX = boardFrameGeometry.x + iframeX;
-          boardY = boardFrameGeometry.y + iframeY;
+          // Its finite paint window can start anywhere within the much larger
+          // logical board, so add the render origin (not the logical board's
+          // fixed -65536 origin) to recover persisted canvas coordinates.
+          const boardPoint = boardSurfaceLocalPointToBoardPoint(
+            { x: iframeX, y: iframeY },
+            boardSurfaceRenderGeometry,
+          );
+          boardX = boardPoint.x;
+          boardY = boardPoint.y;
         } else {
           const sourceScreen = screensRef.current.find(
             (s) => s.id === sourceScreenId,
@@ -2107,6 +2478,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     activeId,
     boardFileId,
     boardFrameGeometry,
+    boardSurfaceRenderGeometry,
     getFrameEntryAtPoint,
     getCanvasPoint,
     getResolvedMetadata,
@@ -2305,7 +2677,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
    *  to collect every screen. */
   const collectLayerMarqueeCandidates = useCallback(
     async (screenIds?: Set<string>) => {
-      const frameEntries = getCurrentFrameEntries().filter(
+      const frameEntries = getSelectableFrameEntries().filter(
         (entry) => !screenIds || screenIds.has(entry.id),
       );
       const frameCandidates = await Promise.all(
@@ -2340,7 +2712,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       );
       const boardCandidates =
         boardFileId &&
-        boardFrameGeometry &&
+        boardSurfaceRenderGeometry &&
         (!screenIds || screenIds.has(boardFileId))
           ? await (async () => {
               const infos = await requestSelectableElementInfos(boardFileId);
@@ -2354,13 +2726,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
                     width: info.boundingRect.width,
                     height: info.boundingRect.height,
                   },
-                  boardFrameGeometry,
+                  boardSurfaceRenderGeometry,
                   {
-                    width: boardFrameGeometry.width,
-                    height: boardFrameGeometry.height,
+                    width: boardSurfaceRenderGeometry.width,
+                    height: boardSurfaceRenderGeometry.height,
                   },
                 ),
-                frameGeometry: boardFrameGeometry,
+                frameGeometry: boardSurfaceRenderGeometry,
               }));
             })()
           : [];
@@ -2368,8 +2740,8 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     },
     [
       boardFileId,
-      boardFrameGeometry,
-      getCurrentFrameEntries,
+      boardSurfaceRenderGeometry,
+      getSelectableFrameEntries,
       getResolvedMetadata,
       requestSelectableElementInfos,
     ],
@@ -2576,6 +2948,52 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         const position = frameStyleLeftTop(geometry, labelHeight);
         element.style.left = `${position.left}px`;
         element.style.top = `${position.top}px`;
+        if (kind !== "frame") {
+          // A draft resize (unlike a plain draft move) can also leave width/
+          // height/rotation, and for path/line/arrow/polygon/star kinds the
+          // inner SVG viewBox + path/polygon content, imperatively mutated
+          // mid-gesture (see applyDraftPrimitiveToDom, used by
+          // beginDraftResize's own live mousemove tick). Restoring it here
+          // unconditionally is a harmless no-op for a plain draft move (whose
+          // origin geometry never had a different width/height/rotation to
+          // begin with) and fixes an Escape mid-draft-resize leaving the
+          // shape's box/content visually stuck at its last dragged size.
+          if ("kind" in origin) {
+            applyDraftPrimitiveToDom(element, origin);
+          }
+          return;
+        }
+        // Resize/rotate (unlike plain move) can also leave width/height/
+        // rotation imperatively mutated mid-gesture — restore those here too
+        // so an Escape mid-resize/rotate doesn't leave the frame visually
+        // stuck at its last dragged size/angle even though the geometry
+        // state itself was already rolled back above.
+        element.style.width = `${geometry.width}px`;
+        element.style.transform = geometry.rotation
+          ? `rotate(${geometry.rotation}deg)`
+          : "";
+        element.style.transformOrigin = `${geometry.width / 2}px ${
+          labelHeight + geometry.height / 2
+        }px`;
+        const cardEl = element.querySelector<HTMLElement>("[data-screen-card]");
+        if (cardEl) {
+          cardEl.style.width = `${geometry.width}px`;
+          cardEl.style.height = `${geometry.height}px`;
+        }
+        const iframeEl = element.querySelector<HTMLIFrameElement>(
+          `[data-screen-iframe-id="${CSS.escape(targetId)}"]`,
+        );
+        const screen = screensRef.current.find((s) => s.id === targetId);
+        if (iframeEl && screen) {
+          const viewport = getScreenPreviewViewport(
+            getResolvedMetadata(screen),
+            geometry,
+          );
+          iframeEl.style.width = `${viewport.viewportWidth}px`;
+          iframeEl.style.height = `${viewport.viewportHeight}px`;
+          iframeEl.style.transform =
+            viewport.scale === 1 ? "" : `scale(${viewport.scale})`;
+        }
       });
 
       const selectionBox = surfaceRef.current?.querySelector<HTMLElement>(
@@ -2602,6 +3020,17 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       const position = frameStyleLeftTop(bounds);
       selectionBox.style.left = `${position.left}px`;
       selectionBox.style.top = `${position.top}px`;
+      // Plain move never touches the selection box's width/height/rotation
+      // (only left/top), but resize/rotate/group-rotate do — restore those
+      // too so Escape can't leave the box's chrome a stale dragged size.
+      selectionBox.style.width = `${bounds.width}px`;
+      selectionBox.style.height = `${bounds.height}px`;
+      const boxRotation =
+        originGeometries.length === 1 ? (originGeometries[0].rotation ?? 0) : 0;
+      selectionBox.style.transform = boxRotation
+        ? `rotate(${boxRotation}deg)`
+        : "";
+      selectionBox.style.transformOrigin = `${bounds.width / 2}px ${bounds.height / 2}px`;
     };
 
     if (state) {
@@ -2611,33 +3040,36 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         state.type === "resize" ||
         state.type === "group-rotate"
       ) {
-        if (state.type === "move") {
-          // Move drags mutate left/top directly while React deliberately keeps
-          // its pre-drag props. A state rollback to those same values does not
-          // make React rewrite the externally-mutated styles, so Escape must
-          // restore the frame + selection-box DOM positions explicitly.
-          restoreImperativeMoveDom(
-            state.originFrames,
-            state.targetIds,
-            "frame",
-          );
-        }
+        // Move/resize/group-rotate all mutate the frame(s)' DOM directly
+        // (left/top for move; also width/height/rotation for resize and
+        // group-rotate — see restoreImperativeMoveDom's comment) while React
+        // deliberately keeps its pre-drag props. A state rollback to those
+        // same values does not make React rewrite the externally-mutated
+        // styles, so Escape must restore the frame + selection-box DOM
+        // state explicitly for every one of these gesture types, not just
+        // move.
+        restoreImperativeMoveDom(state.originFrames, state.targetIds, "frame");
         updateFrameGeometry((current) =>
           frameGeometryWithOverrides(current, state.originFrames),
         );
       } else if (state.type === "rotate") {
+        // Single-frame rotate also mutates the frame's transform directly —
+        // see the matching comment above.
+        restoreImperativeMoveDom(
+          { [state.frameId]: state.originFrame },
+          [state.frameId],
+          "frame",
+        );
         updateFrameGeometry((current) => ({
           ...current,
           [state.frameId]: { ...state.originFrame },
         }));
       } else if (state.type === "draft-move" || state.type === "draft-resize") {
-        if (state.type === "draft-move") {
-          restoreImperativeMoveDom(
-            state.originDrafts,
-            state.targetIds,
-            "draft",
-          );
-        }
+        // Both draft-move (left/top only) and draft-resize (also width/
+        // height/rotation + inner SVG content, see restoreImperativeMoveDom's
+        // draft-kind branch) mutate the draft's DOM node directly mid-gesture
+        // — restore it here the same way move/resize/rotate do for frames.
+        restoreImperativeMoveDom(state.originDrafts, state.targetIds, "draft");
         updateDraftPrimitives((current) =>
           current.map((draft) => {
             const origin = state.originDrafts[draft.id];
@@ -2689,6 +3121,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     return false;
   }, [
     finishDrag,
+    getResolvedMetadata,
     updateDraftPrimitives,
     updateFrameGeometry,
     updateSelectedDraftIds,
@@ -2725,6 +3158,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     (e: React.MouseEvent) => {
       e.preventDefault();
       e.stopPropagation();
+      cancelPendingStaticBoardSelection();
       dragState.current = {
         type: "pan",
         originClient: { x: e.clientX, y: e.clientY },
@@ -2760,7 +3194,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
       installDragListeners(handleMouseMove, handlePanEnd);
     },
-    [finishDrag, installDragListeners],
+    [cancelPendingStaticBoardSelection, finishDrag, installDragListeners],
   );
 
   const beginMarquee = useCallback(
@@ -2875,10 +3309,22 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         ) {
           state.hasMoved = true;
         }
+
+        // Never commit a live marquee rect/selection before the drag
+        // threshold is crossed — matches every other gesture in this file
+        // (move/resize/rotate/draft-move/draft-resize all gate on hasMoved
+        // here). Without this, a shift-click that jitters a couple px near an
+        // already-selected frame's edge runs xorMarqueeSelection against a
+        // near-zero-size rect and can toggle that frame OUT of the selection
+        // — a corruption that mouseup's shouldClearSelectionOnEmptyCanvasClick
+        // never rolls back for the additive (shift) case, since it only
+        // restores selection when the gesture is non-additive.
+        if (!state.hasMoved) return;
+
         setMarquee(rect);
 
         const chromeScale = chromeScaleFromZoom(zoomRef.current);
-        const hitIds = getCurrentFrameEntries()
+        const hitIds = getSelectableFrameEntries()
           .filter((entry) =>
             rotatedRectIntersects(
               rect,
@@ -2940,7 +3386,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       finishDrag,
       getCanvasPoint,
       getCurrentDraftEntries,
-      getCurrentFrameEntries,
+      getSelectableFrameEntries,
       installDragListeners,
       onLayerMarqueeSelectionChange,
       updateSelectedDraftIds,
@@ -3160,6 +3606,12 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         undefined,
         { nextTool: "pen" },
       );
+      // Keep the Pen tool armed after Enter/Escape/closing a path, matching
+      // Figma. The parent selection callback also receives nextTool="pen",
+      // but board primitives intentionally bypass that generic callback and
+      // asynchronous selection reconciliation can otherwise paint Move for a
+      // frame. Drive the controlled tool explicitly at the commit boundary.
+      onActiveToolChange?.("pen");
       clearActivePenPath();
     },
     [clearActivePenPath, commitDraftPrimitive, onActiveToolChange, toolProps],
@@ -4025,13 +4477,16 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
                 current.filter((draftId) => !persistedDraftIds.has(draftId)),
               );
               // Reparent each persisted node into the container primitive.
+              // When the drop resolved to a before/after auto-layout slot
+              // (see findAutoLayoutInsertionAnchor), anchor against that
+              // sibling instead of always appending inside the container.
               persisted.forEach((entry) => {
                 onPrimitiveReparentRef.current?.({
                   sourceNodeId: entry.nodeId,
                   sourceScreenId: entry.frameId,
-                  targetNodeId: dropTarget.nodeId,
+                  targetNodeId: dropTarget.anchorNodeId ?? dropTarget.nodeId,
                   targetScreenId: dropTarget.screenId,
-                  placement: "inside",
+                  placement: dropTarget.placement ?? "inside",
                 });
               });
               const lastPersisted = persisted[persisted.length - 1];
@@ -4165,6 +4620,23 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       setIsDragging(true);
       setDragCursor(getResizeCursor(handle));
 
+      // PERF9: cache each resized draft's DOM node (and the selection-box
+      // overlay tracking it) once, up front — mirrors beginDraftDrag/
+      // beginFrameDrag/beginResize's imperative "mutate now, commit once"
+      // discipline. This used to call updateDraftPrimitives (setDraftPrimitives)
+      // on every mousemove tick, forcing a full MultiScreenCanvas re-render
+      // per rAF frame during a drag.
+      const resizedDraftEls = new Map<string, HTMLElement>();
+      targetIds.forEach((targetId) => {
+        const el = surfaceRef.current?.querySelector<HTMLElement>(
+          `[data-draft-id="${CSS.escape(targetId)}"]`,
+        );
+        if (el) resizedDraftEls.set(targetId, el);
+      });
+      const selectionBoxEl = surfaceRef.current?.querySelector<HTMLElement>(
+        "[data-frame-selection-box]",
+      );
+
       const handleMouseMove = (ev: MouseEvent) => {
         const state = dragState.current;
         if (!state || state.type !== "draft-resize") return;
@@ -4182,7 +4654,11 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         }
 
         // A resize handle click (or normal 1-2px hand jitter) must not resize
-        // the draft. Frame resize already enforces this same threshold.
+        // the draft. Frame resize already enforces this same threshold. Draft
+        // resizes use direct DOM mutation now (see below), so applying even a
+        // 1px delta here would leave a phantom visual nudge React never
+        // learns it needs to overwrite on mouseup — same rationale as
+        // beginDraftDrag's matching guard.
         if (!state.hasMoved) return;
 
         const originEntries = state.targetIds.map((targetId) => ({
@@ -4229,7 +4705,10 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         // drag-start and must see whichever tool is active on THIS tick.
         const scaleK = effectiveToolRef.current === "scale";
 
-        updateDraftPrimitives((current) =>
+        // PERF9: ref-only geometry write (no setDraftPrimitives) + direct DOM
+        // mutation via applyDraftPrimitiveToDom, same "imperative now, commit
+        // once" discipline as beginDraftDrag/beginFrameDrag/beginResize above.
+        updateDraftPrimitivesRefOnly((current) =>
           current.map((draft) => {
             const origin = state.originDrafts[draft.id];
             const geometry = resizedById[draft.id];
@@ -4237,6 +4716,54 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             return applyDraftGeometry(origin, geometry, scaleK);
           }),
         );
+        state.targetIds.forEach((targetId) => {
+          const draft = draftPrimitivesRef.current.find(
+            (candidate) => candidate.id === targetId,
+          );
+          const el = resizedDraftEls.get(targetId);
+          if (draft && el) applyDraftPrimitiveToDom(el, draft);
+        });
+        if (selectionBoxEl) {
+          const targetGeometries = state.targetIds
+            .map(
+              (targetId) =>
+                draftPrimitivesRef.current.find(
+                  (candidate) => candidate.id === targetId,
+                )?.geometry,
+            )
+            .filter((geometry): geometry is FrameGeometry => Boolean(geometry));
+          const bounds =
+            targetGeometries.length === 1
+              ? targetGeometries[0]
+              : (() => {
+                  const groupBounds = getFrameGroupBounds(
+                    targetGeometries.map((geometry) => ({ id: "", geometry })),
+                  );
+                  return groupBounds
+                    ? {
+                        x: groupBounds.left,
+                        y: groupBounds.top,
+                        width: groupBounds.width,
+                        height: groupBounds.height,
+                      }
+                    : null;
+                })();
+          if (bounds) {
+            const { left, top } = frameStyleLeftTop(bounds);
+            selectionBoxEl.style.left = `${left}px`;
+            selectionBoxEl.style.top = `${top}px`;
+            selectionBoxEl.style.width = `${bounds.width}px`;
+            selectionBoxEl.style.height = `${bounds.height}px`;
+            const rotation =
+              targetGeometries.length === 1
+                ? (targetGeometries[0].rotation ?? 0)
+                : 0;
+            selectionBoxEl.style.transform = rotation
+              ? `rotate(${rotation}deg)`
+              : "";
+            selectionBoxEl.style.transformOrigin = `${bounds.width / 2}px ${bounds.height / 2}px`;
+          }
+        }
         setAlignmentGuides(snap.guides);
         showTransformFeedback(
           `${Math.round(snap.frame.width)} x ${Math.round(snap.frame.height)}`,
@@ -4245,7 +4772,19 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         );
       };
 
-      installDragListeners(handleMouseMove, finishDrag);
+      const handleMouseUp = () => {
+        const state = dragState.current;
+        if (state?.type === "draft-resize" && state.hasMoved) {
+          // PERF9: the live resize above only wrote draftPrimitivesRef (no
+          // setDraftPrimitives per tick) — reconcile React state with the
+          // ref's final values here, exactly once, mirroring beginDraftDrag's
+          // matching handleMouseUp comment.
+          updateDraftPrimitives(() => draftPrimitivesRef.current);
+        }
+        finishDrag();
+      };
+
+      installDragListeners(handleMouseMove, handleMouseUp);
     },
     [
       finishDrag,
@@ -4253,6 +4792,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       installDragListeners,
       showTransformFeedback,
       updateDraftPrimitives,
+      updateDraftPrimitivesRefOnly,
       updateSelectedDraftIds,
       updateSelectedIds,
     ],
@@ -4285,7 +4825,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
   const beginFrameDrag = useCallback(
     (id: string, e: React.MouseEvent) => {
-      if (e.button !== 0 || e.shiftKey) return;
+      if (e.button !== 0 || e.shiftKey || lockedScreenIdSet.has(id)) return;
       e.preventDefault();
       e.stopPropagation();
       // Frame mousedowns stop propagation, so they never reach handleMouseDown.
@@ -4326,6 +4866,24 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       // Figma parity: object drags keep the default arrow cursor, never a
       // grabbing hand — see the matching comment in beginDraftDrag above.
 
+      // The surface itself never moves mid-gesture, so its bounding rect is
+      // invariant for the whole drag. Cache it once instead of letting the
+      // allCommitted/getCanvasPoint branch below call getBoundingClientRect
+      // on every tick — that read would force a synchronous layout reflow
+      // right after this same tick's direct style writes (a classic
+      // write-then-read thrash), scoped to primitive/layer drags specifically
+      // (the only path that reaches that branch).
+      const cachedSurfaceRect = surfaceRef.current?.getBoundingClientRect();
+      const getCanvasPointFromCachedRect = (clientX: number, clientY: number) =>
+        cachedSurfaceRect
+          ? screenToCanvasPoint(
+              { x: clientX, y: clientY },
+              { ...panRef.current, zoom: zoomRef.current },
+              { x: cachedSurfaceRect.left, y: cachedSurfaceRect.top },
+              SURFACE_PADDING,
+            )
+          : getCanvasPoint(clientX, clientY);
+
       // PERF9: cache each dragged screen's DOM node (and the selection-box
       // overlay tracking it) once, up front, instead of querying the DOM on
       // every rAF tick. onStartFrameDrag only ever fires with screen.id
@@ -4520,7 +5078,10 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           (targetId) => !currentFrameIds.includes(targetId),
         );
         if (allCommitted) {
-          const canvasPoint = getCanvasPoint(ev.clientX, ev.clientY);
+          const canvasPoint = getCanvasPointFromCachedRect(
+            ev.clientX,
+            ev.clientY,
+          );
           updatePrimitiveDropTarget(
             findPrimitiveDropTarget(canvasPoint, state.primaryId),
           );
@@ -4549,12 +5110,15 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           if (allCommitted && dropTarget) {
             const sourceScreenId = resolvePrimitiveScreenId(state.primaryId);
             if (sourceScreenId) {
+              // When the drop resolved to a before/after auto-layout slot
+              // (see findAutoLayoutInsertionAnchor), anchor against that
+              // sibling instead of always appending inside the container.
               onPrimitiveReparentRef.current?.({
                 sourceNodeId: state.primaryId,
                 sourceScreenId,
-                targetNodeId: dropTarget.nodeId,
+                targetNodeId: dropTarget.anchorNodeId ?? dropTarget.nodeId,
                 targetScreenId: dropTarget.screenId,
-                placement: "inside",
+                placement: dropTarget.placement ?? "inside",
               });
               suppressNextPick.current = true;
               finishDrag();
@@ -4591,6 +5155,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       getCanvasPoint,
       getCurrentFrameEntries,
       installDragListeners,
+      lockedScreenIdSet,
       onPick,
       resolvePrimitiveScreenId,
       showTransformFeedback,
@@ -4604,7 +5169,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
   const beginResize = useCallback(
     (id: string, handle: ResizeHandle, e: React.MouseEvent) => {
-      if (e.button !== 0) return;
+      if (e.button !== 0 || lockedScreenIdSet.has(id)) return;
       e.preventDefault();
       e.stopPropagation();
       suppressNextPick.current = true;
@@ -4650,6 +5215,131 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           : getResizeCursor(handle),
       );
 
+      // PERF9: mirror beginFrameDrag's imperative-DOM discipline for resize
+      // (previously missing here — every tick called the state-committing
+      // updateFrameGeometry, forcing a full MultiScreenCanvas re-render on
+      // every native mousemove, unthrottled by rAF). Cache each resized
+      // screen's DOM nodes up front, write geometry directly to them per
+      // tick via updateFrameGeometryRefOnly (ref-only, no setFrameGeometry),
+      // and reconcile React state with one real commit in handleMouseUp.
+      const frameLabelHeight =
+        FRAME_LABEL_HEIGHT * chromeScaleFromZoom(zoomRef.current);
+      const resizedFrameEls = new Map<string, HTMLElement>();
+      const resizedScreenCardEls = new Map<string, HTMLElement>();
+      const resizedContentIframeEls = new Map<string, HTMLIFrameElement>();
+      const resizedMetadataById = new Map<
+        string,
+        { width: number; height: number }
+      >();
+      originEntries.forEach((entry) => {
+        const frameEl = surfaceRef.current?.querySelector<HTMLElement>(
+          `[data-frame-id="${CSS.escape(entry.id)}"]`,
+        );
+        if (frameEl) {
+          resizedFrameEls.set(entry.id, frameEl);
+          const cardEl =
+            frameEl.querySelector<HTMLElement>("[data-screen-card]");
+          if (cardEl) resizedScreenCardEls.set(entry.id, cardEl);
+          // Only the plain preview iframe (no custom screenContent, e.g. a
+          // fusion/localhost DesignCanvas) carries this attribute at this
+          // render layer — its own iframe is 100%-sized and follows the
+          // screen-card resize above via CSS with no extra write needed.
+          const iframeEl = frameEl.querySelector<HTMLIFrameElement>(
+            `[data-screen-iframe-id="${CSS.escape(entry.id)}"]`,
+          );
+          if (iframeEl) resizedContentIframeEls.set(entry.id, iframeEl);
+        }
+        const screen = screensRef.current.find((s) => s.id === entry.id);
+        if (screen) {
+          resizedMetadataById.set(entry.id, getResolvedMetadata(screen));
+        }
+      });
+      const resizeSelectionBoxEl =
+        surfaceRef.current?.querySelector<HTMLElement>(
+          "[data-frame-selection-box]",
+        );
+
+      const applyResizedGeometryToDom = (
+        ids: string[],
+        geometryById: FrameGeometryById,
+      ) => {
+        ids.forEach((targetId) => {
+          const geometry = geometryById[targetId];
+          if (!geometry) return;
+          const frameEl = resizedFrameEls.get(targetId);
+          if (frameEl) {
+            const { left, top } = frameStyleLeftTop(geometry, frameLabelHeight);
+            frameEl.style.left = `${left}px`;
+            frameEl.style.top = `${top}px`;
+            frameEl.style.width = `${geometry.width}px`;
+            frameEl.style.transform = geometry.rotation
+              ? `rotate(${geometry.rotation}deg)`
+              : "";
+            frameEl.style.transformOrigin = `${geometry.width / 2}px ${
+              frameLabelHeight + geometry.height / 2
+            }px`;
+          }
+          const cardEl = resizedScreenCardEls.get(targetId);
+          if (cardEl) {
+            cardEl.style.width = `${geometry.width}px`;
+            cardEl.style.height = `${geometry.height}px`;
+          }
+          const iframeEl = resizedContentIframeEls.get(targetId);
+          const metadata = resizedMetadataById.get(targetId);
+          if (iframeEl && metadata) {
+            const viewport = getScreenPreviewViewport(metadata, geometry);
+            iframeEl.style.width = `${viewport.viewportWidth}px`;
+            iframeEl.style.height = `${viewport.viewportHeight}px`;
+            iframeEl.style.transform =
+              viewport.scale === 1 ? "" : `scale(${viewport.scale})`;
+          }
+        });
+
+        // Keep the selection outline + resize/rotate handles glued to the
+        // live geometry — see the matching comment in beginFrameDrag's move
+        // handler for why SelectionBox's own geometry prop can't do this on
+        // its own during a ref-only tick.
+        if (resizeSelectionBoxEl) {
+          const targetGeometries = ids
+            .map((targetId) => geometryById[targetId])
+            .filter((geometry): geometry is FrameGeometry => Boolean(geometry));
+          const bounds =
+            targetGeometries.length === 1
+              ? targetGeometries[0]
+              : (() => {
+                  const groupBounds = getFrameGroupBounds(
+                    targetGeometries.map((geometry) => ({
+                      id: "",
+                      geometry,
+                    })),
+                  );
+                  return groupBounds
+                    ? {
+                        x: groupBounds.left,
+                        y: groupBounds.top,
+                        width: groupBounds.width,
+                        height: groupBounds.height,
+                      }
+                    : null;
+                })();
+          if (bounds) {
+            const { left, top } = frameStyleLeftTop(bounds);
+            resizeSelectionBoxEl.style.left = `${left}px`;
+            resizeSelectionBoxEl.style.top = `${top}px`;
+            resizeSelectionBoxEl.style.width = `${bounds.width}px`;
+            resizeSelectionBoxEl.style.height = `${bounds.height}px`;
+            const rotation =
+              targetGeometries.length === 1
+                ? (targetGeometries[0].rotation ?? 0)
+                : 0;
+            resizeSelectionBoxEl.style.transform = rotation
+              ? `rotate(${rotation}deg)`
+              : "";
+            resizeSelectionBoxEl.style.transformOrigin = `${bounds.width / 2}px ${bounds.height / 2}px`;
+          }
+        }
+      };
+
       const handleMouseMove = (ev: MouseEvent) => {
         const state = dragState.current;
         if (!state || state.type !== "resize") return;
@@ -4704,26 +5394,52 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             : null;
 
         if (singleRotatedFrame) {
-          const resizedGeometry = resizeRotatedFrameFromDelta(
-            singleRotatedFrame.geometry,
-            state.handle,
-            dx,
-            dy,
-            {
-              preserveAspectRatio: lockAspectRatio,
-              resizeFromCenter: ev.altKey,
-              minWidth: 1,
-              minHeight: 1,
-            },
-          );
-          updateFrameGeometry((current) => ({
-            ...current,
-            [singleRotatedFrame.id]: {
-              ...state.originFrames[singleRotatedFrame.id],
-              ...resizedGeometry,
-            },
-          }));
-          setAlignmentGuides([]);
+          // Rotation-aware resize snapping (WORK ITEM 2): snap against the
+          // same stationary siblings the unrotated group-resize path below
+          // uses. See resizeRotatedFrameFromDeltaWithSnap's doc comment for
+          // the documented approximation (snaps the frame's own unrotated
+          // local bounds, not a full rotated-edge projection).
+          const { frame: resizedGeometry, guides: rotatedSnapGuides } =
+            resizeRotatedFrameFromDeltaWithSnap(
+              singleRotatedFrame.geometry,
+              state.handle,
+              dx,
+              dy,
+              getCurrentFrameEntries().filter(
+                (entry) => !state.targetIds.includes(entry.id),
+              ),
+              {
+                thresholdScreenPx: DEFAULT_SNAP_THRESHOLD_SCREEN_PX,
+                zoom: zoomRef.current,
+                bypass: ev.metaKey || ev.ctrlKey,
+                preserveAspectRatio: lockAspectRatio,
+              },
+              {
+                preserveAspectRatio: lockAspectRatio,
+                resizeFromCenter: ev.altKey,
+                minWidth: 1,
+                minHeight: 1,
+              },
+            );
+          let nextGeometryById: FrameGeometryById | null = null;
+          updateFrameGeometryRefOnly((current) => {
+            const next = {
+              ...current,
+              [singleRotatedFrame.id]: {
+                ...state.originFrames[singleRotatedFrame.id],
+                ...resizedGeometry,
+              },
+            };
+            nextGeometryById = next;
+            return next;
+          });
+          if (nextGeometryById) {
+            applyResizedGeometryToDom(
+              [singleRotatedFrame.id],
+              nextGeometryById,
+            );
+          }
+          setAlignmentGuides(rotatedSnapGuides);
           showTransformFeedback(
             `${Math.round(resizedGeometry.width)} x ${Math.round(resizedGeometry.height)}`,
             ev.clientX,
@@ -4767,7 +5483,8 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           state.originBounds,
           snap.frame,
         );
-        updateFrameGeometry((current) => {
+        let nextGeometryById: FrameGeometryById | null = null;
+        updateFrameGeometryRefOnly((current) => {
           const next = { ...current };
           resizedEntries.forEach((entry) => {
             next[entry.id] = {
@@ -4775,8 +5492,12 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
               ...entry.geometry,
             };
           });
+          nextGeometryById = next;
           return next;
         });
+        if (nextGeometryById) {
+          applyResizedGeometryToDom(state.targetIds, nextGeometryById);
+        }
         setAlignmentGuides(snap.guides);
         showTransformFeedback(
           `${Math.round(snap.frame.width)} x ${Math.round(snap.frame.height)}`,
@@ -4794,7 +5515,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           );
         }
         if (state?.type === "resize" && state.hasMoved) {
+          // PERF9: the live resize above only wrote frameGeometryRef (ref-only,
+          // no setFrameGeometry per tick) — reconcile React state with the
+          // ref's final values here, exactly once, mirroring beginFrameDrag's
+          // matching handleMouseUp comment.
           const after = cloneFrameGeometryById(frameGeometryRef.current);
+          setFrameGeometry(after);
+          onGeometryChangeRef.current?.(after);
           onGeometryCommitRef.current?.(
             frameGeometryWithOverrides(after, state.originFrames),
             after,
@@ -4809,10 +5536,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       activeId,
       finishDrag,
       getCurrentFrameEntries,
+      getResolvedMetadata,
       installDragListeners,
+      lockedScreenIdSet,
       onPick,
       showTransformFeedback,
       updateFrameGeometry,
+      updateFrameGeometryRefOnly,
       updateSelectedIds,
     ],
   );
@@ -4828,7 +5558,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
   const beginRotate = useCallback(
     (id: string, e: React.MouseEvent) => {
-      if (e.button !== 0) return;
+      if (e.button !== 0 || lockedScreenIdSet.has(id)) return;
       e.preventDefault();
       e.stopPropagation();
       suppressNextPick.current = true;
@@ -4863,6 +5593,18 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         rotateCursorDataUri(quantizeAngleTo8Buckets(originPointerAngle)),
       );
 
+      // PERF9: same imperative-DOM discipline as beginFrameDrag/beginResize.
+      // Rotation never changes width/height, so only the frame shell's own
+      // transform (plus the glued selection box) needs a live write per
+      // tick — no screen-card/iframe involvement like resize needs.
+      const rotateFrameEl = surfaceRef.current?.querySelector<HTMLElement>(
+        `[data-frame-id="${CSS.escape(id)}"]`,
+      );
+      const rotateSelectionBoxEl =
+        surfaceRef.current?.querySelector<HTMLElement>(
+          "[data-frame-selection-box]",
+        );
+
       const handleMouseMove = (ev: MouseEvent) => {
         const state = dragState.current;
         if (!state || state.type !== "rotate") return;
@@ -4885,13 +5627,19 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         const raw =
           state.originRotation + pointerAngle - state.originPointerAngle;
         const rotation = ev.shiftKey ? Math.round(raw / 15) * 15 : raw;
-        updateFrameGeometry((current) => ({
+        const roundedRotation = Math.round(rotation * 10) / 10;
+        updateFrameGeometryRefOnly((current) => ({
           ...current,
           [state.frameId]: {
             ...state.originFrame,
-            rotation: Math.round(rotation * 10) / 10,
+            rotation: roundedRotation,
           },
         }));
+        const rotateTransform = `rotate(${roundedRotation}deg)`;
+        if (rotateFrameEl) rotateFrameEl.style.transform = rotateTransform;
+        if (rotateSelectionBoxEl) {
+          rotateSelectionBoxEl.style.transform = rotateTransform;
+        }
         setDragCursor(
           rotateCursorDataUri(quantizeAngleTo8Buckets(pointerAngle)),
         );
@@ -4912,7 +5660,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           }));
         }
         if (state?.type === "rotate" && state.hasMoved) {
+          // PERF9: the live rotate above only wrote frameGeometryRef
+          // (ref-only, no setFrameGeometry per tick) — reconcile React state
+          // with the ref's final values here, exactly once, mirroring
+          // beginFrameDrag's matching handleMouseUp comment.
           const after = cloneFrameGeometryById(frameGeometryRef.current);
+          setFrameGeometry(after);
+          onGeometryChangeRef.current?.(after);
           onGeometryCommitRef.current?.(
             frameGeometryWithOverrides(after, {
               [state.frameId]: state.originFrame,
@@ -4932,9 +5686,11 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       getCanvasPoint,
       getCurrentFrameEntries,
       installDragListeners,
+      lockedScreenIdSet,
       onPick,
       showTransformFeedback,
       updateFrameGeometry,
+      updateFrameGeometryRefOnly,
       updateSelectedIds,
     ],
   );
@@ -4979,6 +5735,29 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         rotateCursorDataUri(quantizeAngleTo8Buckets(originPointerAngle)),
       );
 
+      // PERF9: same imperative-DOM discipline as beginRotate/beginResize.
+      // Unlike single rotate, orbiting around a shared center also changes
+      // each member's x/y, so every frame shell needs a live left/top write,
+      // not just transform. The individual PassiveSelectionBox outlines are
+      // intentionally left to the next real render (they briefly lag behind
+      // during the gesture, self-correcting at mouseup) — group rotate is a
+      // rarer gesture and threading a live update through each of those too
+      // is a larger change than this fix covers; the shared GroupSelectionBox
+      // (the interactive handle the user is actually dragging) is kept glued.
+      const groupRotateFrameEls = new Map<string, HTMLElement>();
+      originEntries.forEach((entry) => {
+        const frameEl = surfaceRef.current?.querySelector<HTMLElement>(
+          `[data-frame-id="${CSS.escape(entry.id)}"]`,
+        );
+        if (frameEl) groupRotateFrameEls.set(entry.id, frameEl);
+      });
+      const groupRotateSelectionBoxEl =
+        surfaceRef.current?.querySelector<HTMLElement>(
+          "[data-frame-selection-box]",
+        );
+      const groupFrameLabelHeight =
+        FRAME_LABEL_HEIGHT * chromeScaleFromZoom(zoomRef.current);
+
       const handleMouseMove = (ev: MouseEvent) => {
         const state = dragState.current;
         if (!state || state.type !== "group-rotate") return;
@@ -5012,7 +5791,8 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           state.groupCenter,
           delta,
         );
-        updateFrameGeometry((current) => {
+        let nextGeometryById: FrameGeometryById | null = null;
+        updateFrameGeometryRefOnly((current) => {
           const next = { ...current };
           rotated.forEach((entry) => {
             next[entry.id] = {
@@ -5020,8 +5800,38 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
               ...entry.geometry,
             };
           });
+          nextGeometryById = next;
           return next;
         });
+        if (nextGeometryById) {
+          rotated.forEach((entry) => {
+            const geometry = nextGeometryById![entry.id];
+            const frameEl = groupRotateFrameEls.get(entry.id);
+            if (!geometry || !frameEl) return;
+            const { left, top } = frameStyleLeftTop(
+              geometry,
+              groupFrameLabelHeight,
+            );
+            frameEl.style.left = `${left}px`;
+            frameEl.style.top = `${top}px`;
+            frameEl.style.transform = geometry.rotation
+              ? `rotate(${geometry.rotation}deg)`
+              : "";
+          });
+          if (groupRotateSelectionBoxEl) {
+            const groupBoundsNow = getFrameGroupBounds(rotated);
+            if (groupBoundsNow) {
+              const { left, top } = frameStyleLeftTop({
+                x: groupBoundsNow.left,
+                y: groupBoundsNow.top,
+              });
+              groupRotateSelectionBoxEl.style.left = `${left}px`;
+              groupRotateSelectionBoxEl.style.top = `${top}px`;
+              groupRotateSelectionBoxEl.style.width = `${groupBoundsNow.width}px`;
+              groupRotateSelectionBoxEl.style.height = `${groupBoundsNow.height}px`;
+            }
+          }
+        }
         showTransformFeedback(
           `${Math.round(delta)}deg`,
           ev.clientX,
@@ -5038,7 +5848,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           );
         }
         if (state?.type === "group-rotate" && state.hasMoved) {
+          // PERF9: the live group-rotate above only wrote frameGeometryRef
+          // (ref-only, no setFrameGeometry per tick) — reconcile React state
+          // with the ref's final values here, exactly once, mirroring
+          // beginFrameDrag's matching handleMouseUp comment.
           const after = cloneFrameGeometryById(frameGeometryRef.current);
+          setFrameGeometry(after);
+          onGeometryChangeRef.current?.(after);
           onGeometryCommitRef.current?.(
             frameGeometryWithOverrides(after, state.originFrames),
             after,
@@ -5057,12 +5873,14 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       installDragListeners,
       showTransformFeedback,
       updateFrameGeometry,
+      updateFrameGeometryRefOnly,
     ],
   );
 
   const handleFrameClick = useCallback(
     (id: string, e: React.MouseEvent<HTMLElement>) => {
       e.stopPropagation();
+      if (lockedScreenIdSet.has(id)) return;
       if (suppressNextPick.current) {
         suppressNextPick.current = false;
         return;
@@ -5091,24 +5909,42 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       updateSelectedIds(() => [id]);
       onPick(id);
     },
-    [activeId, onPick, updateSelectedDraftIds, updateSelectedIds],
+    [
+      activeId,
+      lockedScreenIdSet,
+      onPick,
+      updateSelectedDraftIds,
+      updateSelectedIds,
+    ],
   );
 
   const handleFrameDoubleClick = useCallback(
     (id: string, e: React.MouseEvent<HTMLElement>) => {
       e.preventDefault();
       e.stopPropagation();
+      if (lockedScreenIdSet.has(id)) {
+        onEdit?.(id);
+        return;
+      }
       updateSelectedDraftIds(() => []);
       updateSelectedIds(() => [id]);
       onPick(id);
       onEdit?.(id);
     },
-    [onEdit, onPick, updateSelectedDraftIds, updateSelectedIds],
+    [
+      lockedScreenIdSet,
+      onEdit,
+      onPick,
+      updateSelectedDraftIds,
+      updateSelectedIds,
+    ],
   );
 
   const beginDuplicateGesture = useCallback(
     (screen: ScreenFile, display: string, e: React.MouseEvent<HTMLElement>) => {
-      if (e.button !== 0 || !e.altKey) return;
+      if (e.button !== 0 || !e.altKey || lockedScreenIdSet.has(screen.id)) {
+        return;
+      }
       e.preventDefault();
       e.stopPropagation();
       duplicateCleanup.current?.();
@@ -5155,25 +5991,60 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       // duplicate on mouseup.
       setDragCursor(e.altKey ? "copy" : null);
 
+      // PERF: track the last committed canDuplicate/moved/cursor values in
+      // plain closure locals (not state) so the mousemove tick below can tell
+      // whether anything conditional actually changed without reading back
+      // through React state (which the imperative writes below intentionally
+      // stop keeping fresh every tick — see duplicatePreviewElRef).
+      let lastCanDuplicate = !!onDuplicate;
+      let lastMoved = false;
+      let lastCursor: string | null = e.altKey ? "copy" : null;
+
       const handleMouseMove = (ev: MouseEvent) => {
         const dx = ev.clientX - origin.x;
         const dy = ev.clientY - origin.y;
         const moved = Math.hypot(dx, dy) >= DUPLICATE_DRAG_THRESHOLD;
         const rect = surfaceRef.current?.getBoundingClientRect();
-        setDuplicatePreview({
-          display,
-          x: rect ? ev.clientX - rect.left + 16 : ev.clientX,
-          y: rect ? ev.clientY - rect.top + 16 : ev.clientY,
-          width: previewWidth,
-          height: previewHeight,
-          // Live alt state, not just capability: if the user releases alt
-          // mid-drag the preview should visibly fall back to its "not armed"
-          // dashed/preview styling, matching that mouseup will then cancel
-          // the duplicate instead of creating one (see handleMouseUp below).
-          canDuplicate: !!onDuplicate && ev.altKey,
-          moved,
-        });
-        setDragCursor(ev.altKey ? "copy" : null);
+        const x = rect ? ev.clientX - rect.left + 16 : ev.clientX;
+        const y = rect ? ev.clientY - rect.top + 16 : ev.clientY;
+        // Live alt state, not just capability: if the user releases alt
+        // mid-drag the preview should visibly fall back to its "not armed"
+        // dashed/preview styling, matching that mouseup will then cancel
+        // the duplicate instead of creating one (see handleMouseUp below).
+        const canDuplicate = !!onDuplicate && ev.altKey;
+
+        // PERF9: the ghost's position is a direct DOM write every tick
+        // instead of a setDuplicatePreview (full re-render) — same
+        // "imperative now, commit state only when something conditional
+        // changes" discipline as the frame/draft drag paths above. Falls
+        // back to setDuplicatePreview itself if the node hasn't mounted yet
+        // (e.g. the very first tick right after mousedown, before React has
+        // committed the initial preview).
+        const el = duplicatePreviewElRef.current;
+        if (el) {
+          el.style.left = `${x}px`;
+          el.style.top = `${y}px`;
+        }
+
+        if (!el || canDuplicate !== lastCanDuplicate || moved !== lastMoved) {
+          lastCanDuplicate = canDuplicate;
+          lastMoved = moved;
+          setDuplicatePreview({
+            display,
+            x,
+            y,
+            width: previewWidth,
+            height: previewHeight,
+            canDuplicate,
+            moved,
+          });
+        }
+
+        const cursor = ev.altKey ? "copy" : null;
+        if (cursor !== lastCursor) {
+          lastCursor = cursor;
+          setDragCursor(cursor);
+        }
       };
 
       const cleanupDuplicateGesture = () => {
@@ -5247,6 +6118,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       finishDrag,
       getCurrentFrameEntries,
       installDragListeners,
+      lockedScreenIdSet,
       onDuplicate,
       onPick,
     ],
@@ -5330,6 +6202,39 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         beginDraftCreation(creationTool, e);
         return;
       }
+      if (
+        e.button === 0 &&
+        tool === "move" &&
+        !onFrame &&
+        showBoardStaticPreview &&
+        boardSurfaceRenderGeometry
+      ) {
+        const point = getCanvasPoint(e.clientX, e.clientY);
+        if (!geometryContainsPoint(boardSurfaceRenderGeometry, point)) {
+          const hit = [...boardStaticPrimitives]
+            .reverse()
+            .find((primitive) =>
+              geometryContainsPoint(
+                getPrimitiveLowZoomHitRect(primitive, zoomRef.current),
+                point,
+              ),
+            );
+          if (hit) {
+            e.preventDefault();
+            e.stopPropagation();
+            pendingStaticBoardSelectionRef.current = {
+              nodeId: hit.nodeId,
+              point,
+            };
+            // Re-window the one live Alpine iframe around the clicked static
+            // primitive. DesignCanvas updates its content offset in place, so
+            // the iframe node/srcdoc/runtime survive; the effect above selects
+            // the same node through that live bridge after the offset settles.
+            setBoardSurfaceFocusPoint(point);
+            return;
+          }
+        }
+      }
       if (e.button === 0 && !onFrame) {
         beginMarquee(e);
       }
@@ -5342,10 +6247,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       beginPenNodeCreation,
       beginVectorAnchorDrag,
       beginVectorHandleDrag,
+      boardStaticPrimitives,
+      boardSurfaceRenderGeometry,
       claimKeyboardFocus,
       getCanvasPoint,
       localActiveTool,
       setAltHoverMeasurement,
+      showBoardStaticPreview,
       toggleVectorNodeType,
       vectorEdit,
     ],
@@ -5576,6 +6484,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   // it's an acceptable trade for keeping gesture start/end render-free.
   const markWheelGestureActive = useCallback(() => {
     if (wheelGestureActiveRef.current) return;
+    cancelPendingStaticBoardSelection();
     wheelGestureActiveRef.current = true;
     setWheelCameraGestureActive(true);
     const surface = surfaceRef.current;
@@ -5594,7 +6503,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         element.style.pointerEvents = "none";
       });
     wheelGestureMutedElementsRef.current = muted;
-  }, []);
+  }, [cancelPendingStaticBoardSelection]);
 
   const flushPendingWheelGesture = useCallback(() => {
     wheelGestureFrameRef.current = null;
@@ -6164,11 +7073,12 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
   const canvasFrames = useMemo(() => {
     const cache = canvasFrameEntryCacheRef.current;
     const nextIds = new Set<string>();
-    const next = screens.map((screen, index) => {
+    const next = renderedScreens.map((screen) => {
       nextIds.add(screen.id);
       const metadata = getResolvedMetadata(screen);
       const geometry =
-        frameGeometry[screen.id] ?? getInitialFrameGeometry(index, metadata);
+        frameGeometry[screen.id] ??
+        getInitialFrameGeometry(screenIndexById.get(screen.id) ?? 0, metadata);
       const prior = cache.get(screen.id);
       if (
         prior &&
@@ -6192,7 +7102,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     }
     pruneResolvedMetadataCache(resolvedMetadataCacheRef.current, nextIds);
     return next;
-  }, [frameGeometry, getResolvedMetadata, screens]);
+  }, [frameGeometry, getResolvedMetadata, renderedScreens, screenIndexById]);
   // Interaction-protected screens are never eligible for LRU eviction. Active
   // screen/frame selection are the primary signals; layer selection, native
   // file-drop targeting, gradient editing, and in-flight frame transforms are
@@ -6441,6 +7351,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
 
       <div
         ref={worldRef}
+        data-multi-screen-canvas-world
         className="pointer-events-none absolute"
         style={{
           left: 0,
@@ -6456,11 +7367,51 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
           transformOrigin: "top left",
         }}
       >
+        {showBoardStaticPreview &&
+        boardFrameGeometry &&
+        boardStaticPreviewViewport &&
+        boardStaticPreviewContent ? (
+          <div
+            data-board-static-preview
+            aria-hidden="true"
+            style={{
+              position: "absolute",
+              left: SURFACE_PADDING + boardFrameGeometry.x,
+              top: SURFACE_PADDING + boardFrameGeometry.y,
+              width: boardFrameGeometry.width,
+              height: boardFrameGeometry.height,
+              overflow: "hidden",
+              pointerEvents: "none",
+              background: "transparent",
+              zIndex: 0,
+            }}
+          >
+            <iframe
+              data-board-static-preview-iframe
+              aria-hidden="true"
+              tabIndex={-1}
+              sandbox=""
+              referrerPolicy="no-referrer"
+              srcDoc={boardStaticPreviewContent}
+              style={{
+                display: "block",
+                width: boardStaticPreviewViewport.width,
+                height: boardStaticPreviewViewport.height,
+                border: 0,
+                pointerEvents: "none",
+                transform: `scale(${boardFrameGeometry.width / boardStaticPreviewViewport.width}, ${boardFrameGeometry.height / boardStaticPreviewViewport.height})`,
+                transformOrigin: "top left",
+                background: "transparent",
+              }}
+            />
+          </div>
+        ) : null}
+
         {boardFileId &&
           boardFileContent !== undefined &&
           hasBoardSurfaceContent(boardFileContent) &&
           (() => {
-            const boardGeo = boardFrameGeometry ?? {
+            const boardGeo = boardSurfaceRenderGeometry ?? {
               x: 0,
               y: 0,
               width: 8192,
@@ -6569,6 +7520,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
               screen={screen}
               metadata={metadata}
               geometry={geometry}
+              locked={lockedScreenIdSet.has(screen.id)}
               screenContent={screenContentById.get(screen.id)}
               cullTier={screenCullTierById.get(screen.id) ?? "visible"}
               isActive={screen.id === activeId}
@@ -6904,33 +7856,57 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
       ) : null}
 
       {primitiveDropTarget ? (
-        <span
-          data-primitive-drop-target
-          className="pointer-events-none absolute z-40 rounded-sm"
-          style={{
-            // Surface position = pan + (SURFACE_PADDING + canvasCoord) * scale
-            left:
-              pan.x +
-              (SURFACE_PADDING + primitiveDropTarget.boardRect.x) * scale,
-            top:
-              pan.y +
-              (SURFACE_PADDING + primitiveDropTarget.boardRect.y) * scale,
-            width: Math.max(1, primitiveDropTarget.boardRect.width * scale),
-            height: Math.max(1, primitiveDropTarget.boardRect.height * scale),
-            transform: primitiveDropTarget.boardRect.rotation
-              ? `rotate(${primitiveDropTarget.boardRect.rotation}deg)`
-              : undefined,
-            // Match the in-screen inside-guide style: 2px accent border + 14%
-            // accent fill. Uses the same CSS variable as the DesignCanvas guide.
-            border: "2px solid var(--design-editor-accent-color)",
-            background:
-              "color-mix(in srgb, var(--design-editor-accent-color) 14%, transparent)",
-          }}
-        />
+        primitiveDropTarget.placement === "before" ||
+        primitiveDropTarget.placement === "after" ? (
+          // Auto-layout flow-insert: reuse the exact same insertion-LINE
+          // renderer the cross-screen hit-test guide uses (see
+          // getCrossScreenDropGuideStyle) so both drop paths draw an
+          // identical Figma-style indicator between siblings.
+          <span
+            data-primitive-drop-target
+            data-primitive-drop-placement={primitiveDropTarget.placement}
+            className="pointer-events-none absolute z-40 rounded-sm"
+            style={getCrossScreenDropGuideStyle({
+              guide: {
+                placement: primitiveDropTarget.placement,
+                axis: primitiveDropTarget.axis ?? "y",
+                boardRect: primitiveDropTarget.boardRect,
+              },
+              pan,
+              scale,
+            })}
+          />
+        ) : (
+          <span
+            data-primitive-drop-target
+            className="pointer-events-none absolute z-40 rounded-sm"
+            style={{
+              // Surface position = pan + (SURFACE_PADDING + canvasCoord) * scale
+              left:
+                pan.x +
+                (SURFACE_PADDING + primitiveDropTarget.boardRect.x) * scale,
+              top:
+                pan.y +
+                (SURFACE_PADDING + primitiveDropTarget.boardRect.y) * scale,
+              width: Math.max(1, primitiveDropTarget.boardRect.width * scale),
+              height: Math.max(1, primitiveDropTarget.boardRect.height * scale),
+              transform: primitiveDropTarget.boardRect.rotation
+                ? `rotate(${primitiveDropTarget.boardRect.rotation}deg)`
+                : undefined,
+              // Match the in-screen inside-guide style: 2px accent border + 14%
+              // accent fill. Uses the same CSS variable as the DesignCanvas guide.
+              border: "2px solid var(--design-editor-accent-color)",
+              background:
+                "color-mix(in srgb, var(--design-editor-accent-color) 14%, transparent)",
+            }}
+          />
+        )
       ) : null}
 
       {duplicatePreview ? (
         <div
+          ref={duplicatePreviewElRef}
+          data-duplicate-preview-ghost
           className={cn(
             "pointer-events-none absolute z-20 rounded-lg border bg-background/90 shadow-2xl backdrop-blur-sm transition-colors",
             duplicatePreview.canDuplicate
@@ -6938,6 +7914,11 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
               : "border-dashed border-muted-foreground/45",
           )}
           style={{
+            // PERF9: left/top stay driven by state (matches the last value
+            // beginDuplicateGesture's mousemove tick imperatively wrote, kept
+            // in sync — see setDuplicatePreview's canDuplicate/moved-gated
+            // calls below), but the DOM node's own style.left/top is what
+            // actually moves every tick, not this re-render.
             left: duplicatePreview.x,
             top: duplicatePreview.y,
             width: duplicatePreview.width * Math.min(scale, 1),
@@ -7805,6 +8786,7 @@ interface ScreenProps {
   screen: ScreenFile;
   metadata: ResolvedScreenMetadata;
   geometry: FrameGeometry;
+  locked: boolean;
   isActive: boolean;
   isSelected: boolean;
   isTopScreen: boolean;
@@ -7870,6 +8852,7 @@ const Screen = memo(function Screen({
   screen,
   metadata,
   geometry,
+  locked,
   isActive,
   isSelected,
   isTopScreen,
@@ -7919,6 +8902,7 @@ const Screen = memo(function Screen({
   const [directlyHovered, setDirectlyHovered] = useState(false);
   const frameDirectlyHovered =
     (directlyHovered || isDirectlyHovered) &&
+    !locked &&
     !creationToolActive &&
     !canvasGestureActive;
   const childHoverActive =
@@ -7949,6 +8933,7 @@ const Screen = memo(function Screen({
     !suppressFrameChromeForChild;
   const screenContentInteractive =
     Boolean(screenContent) &&
+    !locked &&
     !penActive &&
     !creationToolActive &&
     !canvasGestureActive;
diff --git a/templates/design/app/components/design/QuestionFlow.test.tsx b/templates/design/app/components/design/QuestionFlow.test.tsx
new file mode 100644
index 0000000000..ea726f7ceb
--- /dev/null
+++ b/templates/design/app/components/design/QuestionFlow.test.tsx
@@ -0,0 +1,180 @@
+// @vitest-environment happy-dom
+
+import { AgentNativeI18nProvider } from "@agent-native/core/client";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+
+import { QuestionFlow } from "./QuestionFlow";
+
+// Minimal catalog covering only the keys QuestionFlow reads. Full catalog
+// coverage across all locales is verified by `guard:i18n-catalogs`, not here.
+const CATALOG_MESSAGES = {
+  questionFlow: {
+    defaultTitle: "Quick questions before I design",
+    continue: "Continue",
+    skip: "Decide for me",
+    textPlaceholder: "Type your answer...",
+    other: "Other",
+    otherDescription: "Tell me exactly what you mean.",
+    customPlaceholder: "Type a custom answer...",
+    recommended: "Recommended",
+    selectedCount: "{{count}} selected",
+    selectUseful: "Select what's useful",
+    exploreLabel: "Explore a few options",
+    exploreDescription: "Show me a few distinct directions.",
+    decideLabel: "Decide for me",
+    decideDescription: "Use your judgment.",
+    dragFiles: "Drag files here or",
+    browse: "browse",
+    removeFile: "Remove {{name}}",
+  },
+};
+
+const DEFAULT_QUESTIONS: React.ComponentProps<
+  typeof QuestionFlow
+>["questions"] = [
+  {
+    id: "form_factor",
+    type: "text-options",
+    question: "What form factor?",
+    options: [
+      { label: "Mobile", value: "mobile" },
+      { label: "Desktop", value: "desktop" },
+    ],
+    allowOther: false,
+    includeExplore: false,
+    includeDecide: false,
+  },
+];
+
+async function renderQuestionFlow(
+  props: Omit<React.ComponentProps<typeof QuestionFlow>, "questions"> & {
+    questions?: React.ComponentProps<typeof QuestionFlow>["questions"];
+  },
+) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  const renderQuestions = async (
+    questions: React.ComponentProps<typeof QuestionFlow>["questions"],
+  ) => {
+    await act(async () => {
+      root.render(
+        <AgentNativeI18nProvider catalog={{ messages: CATALOG_MESSAGES }}>
+          <QuestionFlow questions={questions} {...props} />
+        </AgentNativeI18nProvider>,
+      );
+    });
+  };
+  await renderQuestions(props.questions ?? DEFAULT_QUESTIONS);
+  const findButton = (label: string) =>
+    Array.from(container.querySelectorAll("button")).find((button) =>
+      button.textContent?.toLowerCase().includes(label.toLowerCase()),
+    );
+  return {
+    container,
+    findButton,
+    renderQuestions,
+    async cleanup() {
+      await act(async () => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+describe("QuestionFlow double-submit guard", () => {
+  it("only calls onSubmit once when Continue is clicked twice in a row", async () => {
+    const onSubmit = vi.fn();
+    const onSkip = vi.fn();
+    const { findButton, cleanup } = await renderQuestionFlow({
+      onSubmit,
+      onSkip,
+    });
+
+    // Select an option so the required-answered gate does not block submit.
+    const mobileOption = findButton("Mobile");
+    expect(mobileOption).toBeTruthy();
+    await act(async () => {
+      mobileOption!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    const continueButton = findButton("Continue");
+    expect(continueButton).toBeTruthy();
+
+    await act(async () => {
+      continueButton!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      continueButton!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(continueButton!.hasAttribute("disabled")).toBe(true);
+
+    await cleanup();
+  });
+
+  it("only calls onSkip once when Skip is clicked twice in a row", async () => {
+    const onSubmit = vi.fn();
+    const onSkip = vi.fn();
+    const { findButton, cleanup } = await renderQuestionFlow({
+      onSubmit,
+      onSkip,
+    });
+
+    const skipButton = findButton("Decide for me");
+    expect(skipButton).toBeTruthy();
+
+    await act(async () => {
+      skipButton!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      skipButton!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    expect(onSkip).toHaveBeenCalledTimes(1);
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    await cleanup();
+  });
+
+  it("re-enables submit for a fresh question set after answering a previous one", async () => {
+    const onSubmit = vi.fn();
+    const onSkip = vi.fn();
+    const { findButton, renderQuestions, cleanup } = await renderQuestionFlow({
+      onSubmit,
+      onSkip,
+    });
+
+    const mobileOption = findButton("Mobile");
+    await act(async () => {
+      mobileOption!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    const continueButton = findButton("Continue");
+    await act(async () => {
+      continueButton!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(findButton("Continue")!.hasAttribute("disabled")).toBe(true);
+
+    // A new, different question set arrives (e.g. a follow-up clarifying
+    // question later in the same design session) — the fingerprint changes,
+    // so the guard must reset instead of leaving Continue disabled forever.
+    await renderQuestions([
+      {
+        id: "palette",
+        type: "text-options",
+        question: "Which palette?",
+        options: [{ label: "Warm", value: "warm" }],
+        allowOther: false,
+        includeExplore: false,
+        includeDecide: false,
+      },
+    ]);
+
+    const warmOption = findButton("Warm");
+    await act(async () => {
+      warmOption!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    expect(findButton("Continue")!.hasAttribute("disabled")).toBe(false);
+
+    await cleanup();
+  });
+});
diff --git a/templates/design/app/components/design/QuestionFlow.tsx b/templates/design/app/components/design/QuestionFlow.tsx
index e8b9f588ed..82a6703caa 100644
--- a/templates/design/app/components/design/QuestionFlow.tsx
+++ b/templates/design/app/components/design/QuestionFlow.tsx
@@ -10,7 +10,7 @@ import {
 } from "@agent-native/core/client";
 import type { QuestionFlowQuestion } from "@shared/api";
 import { IconCheck, IconPalette, IconUpload, IconX } from "@tabler/icons-react";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 import { Button } from "@/components/ui/button";
 import { Slider } from "@/components/ui/slider";
@@ -39,6 +39,15 @@ export function QuestionFlow({
   const t = useT();
   const guidedQuestions = questions as GuidedQuestion[];
   const [answers, setAnswers] = useState<Record<string, unknown>>({});
+  // Guards against a rapid double-click (or two events firing within the
+  // same React batch) triggering onSubmit/onSkip twice before the parent
+  // hook clears the persisted question payload and this component unmounts.
+  // Both handlers post a message to the agent chat, so firing twice would
+  // duplicate the turn. A ref is required (not just state) because the gate
+  // must be visible synchronously to a second click handled in the same
+  // task, before React has flushed the re-render that disables the button.
+  const respondedRef = useRef(false);
+  const [responded, setResponded] = useState(false);
   const questionsFingerprint = useMemo(
     () => questionFlowFingerprint(guidedQuestions),
     [guidedQuestions],
@@ -46,6 +55,8 @@ export function QuestionFlow({
 
   useEffect(() => {
     setAnswers({});
+    respondedRef.current = false;
+    setResponded(false);
   }, [questionsFingerprint]);
 
   const setAnswer = useCallback((id: string, value: unknown) => {
@@ -98,8 +109,13 @@ export function QuestionFlow({
           <Button
             type="button"
             size="sm"
-            onClick={() => onSubmit(normalizeGuidedAnswers(answers))}
-            disabled={!allRequiredAnswered}
+            onClick={() => {
+              if (respondedRef.current) return;
+              respondedRef.current = true;
+              setResponded(true);
+              onSubmit(normalizeGuidedAnswers(answers));
+            }}
+            disabled={responded || !allRequiredAnswered}
             className="h-8 cursor-pointer rounded-md bg-[var(--design-editor-accent-color)] px-3 text-[12px] text-[var(--design-editor-accent-contrast-color)] shadow-none hover:bg-[var(--design-editor-accent-hover-color)] hover:text-[var(--design-editor-accent-contrast-color)] focus-visible:ring-[var(--design-editor-accent-color)]"
           >
             {submitLabel ?? t("questionFlow.continue")}
@@ -108,8 +124,14 @@ export function QuestionFlow({
             type="button"
             variant="ghost"
             size="sm"
-            onClick={onSkip}
-            className="h-8 cursor-pointer rounded-md px-3 text-[12px] text-muted-foreground hover:bg-[var(--design-editor-layer-hover-color)] hover:text-foreground"
+            onClick={() => {
+              if (respondedRef.current) return;
+              respondedRef.current = true;
+              setResponded(true);
+              onSkip();
+            }}
+            disabled={responded}
+            className="h-8 cursor-pointer rounded-md px-3 text-[12px] text-muted-foreground hover:bg-[var(--design-editor-layer-hover-color)] hover:text-foreground disabled:cursor-not-allowed disabled:opacity-60"
           >
             {skipLabel ?? t("questionFlow.skip")}
           </Button>
diff --git a/templates/design/app/components/design/ReviewPanel.test.tsx b/templates/design/app/components/design/ReviewPanel.test.tsx
new file mode 100644
index 0000000000..30deb91a1c
--- /dev/null
+++ b/templates/design/app/components/design/ReviewPanel.test.tsx
@@ -0,0 +1,162 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { A11yFinding } from "../../../shared/design-review.js";
+import { ReviewPanel } from "./ReviewPanel";
+
+const mutateAsync = vi.fn();
+vi.mock("@agent-native/core/client", () => ({
+  cn: (...values: Array<string | false | null | undefined>) =>
+    values.filter(Boolean).join(" "),
+  useActionMutation: () => ({
+    mutateAsync: (...args: unknown[]) => mutateAsync(...args),
+  }),
+}));
+
+function finding(overrides: Partial<A11yFinding> = {}): A11yFinding {
+  return {
+    id: "contrast:node-42",
+    severity: "error",
+    category: "contrast",
+    message: "Contrast ratio 2.1:1 — minimum is 4.5:1",
+    nodeId: "node-42",
+    fixAvailable: true,
+    ...overrides,
+  };
+}
+
+let cleanup: (() => Promise<void>) | undefined;
+let root: Root | undefined;
+let container: HTMLDivElement | undefined;
+
+beforeEach(() => {
+  (
+    globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }
+  ).IS_REACT_ACT_ENVIRONMENT = true;
+  mutateAsync.mockReset();
+});
+
+afterEach(async () => {
+  await cleanup?.();
+  cleanup = undefined;
+  root = undefined;
+  container = undefined;
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+});
+
+async function renderPanel(findings: A11yFinding[]) {
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+  cleanup = async () => {
+    await act(async () => root?.unmount());
+    container?.remove();
+  };
+  const rerender = async (nextFindings: A11yFinding[]) => {
+    await act(async () => {
+      root!.render(
+        <ReviewPanel
+          findings={nextFindings}
+          fixSource={{ designId: "design-1", fileId: "file-1" }}
+        />,
+      );
+    });
+  };
+  await rerender(findings);
+  return { rerender };
+}
+
+describe("ReviewPanel FindingRow fix status", () => {
+  it("does not keep showing 'Fixed' if a fresh audit re-reports the same finding", async () => {
+    mutateAsync.mockResolvedValue({ applied: true });
+    const original = finding();
+    const { rerender } = await renderPanel([original]);
+
+    const fixButton = Array.from(container!.querySelectorAll("button")).find(
+      (btn) => btn.textContent?.includes("Fix"),
+    );
+    if (!fixButton) throw new Error("Fix button did not render");
+    await act(async () => {
+      fixButton.click();
+    });
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(container!.textContent).toContain("Fixed");
+
+    // A fresh audit pass returns a *new* finding object with the same stable
+    // id — meaning the fix didn't actually resolve it. The row must not keep
+    // showing a stale "Fixed" checkmark for a currently-live issue.
+    const reAudited = finding({
+      message: "Contrast ratio 2.3:1 — minimum is 4.5:1",
+    });
+    await rerender([reAudited]);
+
+    expect(container!.textContent).not.toContain("Fixed");
+    const retriedFixButton = Array.from(
+      container!.querySelectorAll("button"),
+    ).find((btn) => btn.textContent?.includes("Fix"));
+    expect(retriedFixButton).toBeTruthy();
+  });
+
+  it("keeps showing 'Fixed' across re-renders that don't change the finding", async () => {
+    mutateAsync.mockResolvedValue({ applied: true });
+    const original = finding();
+    const { rerender } = await renderPanel([original]);
+
+    const fixButton = Array.from(container!.querySelectorAll("button")).find(
+      (btn) => btn.textContent?.includes("Fix"),
+    );
+    await act(async () => {
+      fixButton?.click();
+    });
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(container!.textContent).toContain("Fixed");
+
+    // Re-rendering with the exact same finding reference (e.g. a parent
+    // re-render unrelated to the audit) must not reset the optimistic state.
+    await rerender([original]);
+    expect(container!.textContent).toContain("Fixed");
+  });
+});
+
+describe("ReviewPanel FindingRow keyboard activation", () => {
+  it("prevents the default Space scroll when activating a finding row via keyboard", async () => {
+    const onFindingClick = vi.fn();
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    cleanup = async () => {
+      await act(async () => root?.unmount());
+      container?.remove();
+    };
+    await act(async () => {
+      root!.render(
+        <ReviewPanel findings={[finding()]} onFindingClick={onFindingClick} />,
+      );
+    });
+
+    const row = container.querySelector('[role="button"]');
+    if (!row) throw new Error("Finding row did not render");
+    const event = new KeyboardEvent("keydown", {
+      key: " ",
+      bubbles: true,
+      cancelable: true,
+    });
+    await act(async () => {
+      row.dispatchEvent(event);
+    });
+
+    expect(event.defaultPrevented).toBe(true);
+    expect(onFindingClick).toHaveBeenCalledWith(finding());
+  });
+});
diff --git a/templates/design/app/components/design/ReviewPanel.tsx b/templates/design/app/components/design/ReviewPanel.tsx
index 54e66b1ecf..cc7b0a5636 100644
--- a/templates/design/app/components/design/ReviewPanel.tsx
+++ b/templates/design/app/components/design/ReviewPanel.tsx
@@ -31,7 +31,7 @@ import {
   IconShieldCheck,
   IconTool,
 } from "@tabler/icons-react";
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -194,6 +194,21 @@ function FindingRow({
   const applyFix = useActionMutation("apply-a11y-fix");
   const [fixStatus, setFixStatus] = useState<FixStatus>("idle");
 
+  // `finding.id` is stable across audit runs (`"category:node-id"`), so a
+  // parent refetch that still includes the same id — e.g. the fix didn't
+  // fully resolve the issue and a fresh audit re-detected it — reuses this
+  // same row instance. Without this, a stale "Fixed" checkmark would keep
+  // showing even though the finding is live again. Only reset when a
+  // genuinely new `finding` object arrives (a fresh audit pass), not on our
+  // own optimistic `setFixStatus` calls, which don't touch the prop.
+  const lastFindingRef = useRef(finding);
+  useEffect(() => {
+    if (lastFindingRef.current !== finding) {
+      lastFindingRef.current = finding;
+      setFixStatus("idle");
+    }
+  }, [finding]);
+
   // A Fix affordance is shown only when (a) the finding maps to a deterministic
   // inline edit and (b) a design source is available to write to.  Everything
   // else stays informational.
@@ -248,7 +263,13 @@ function FindingRow({
       tabIndex={onClick ? 0 : undefined}
       onClick={() => onClick?.(finding)}
       onKeyDown={(e) => {
-        if (e.key === "Enter" || e.key === " ") onClick?.(finding);
+        if (e.key === "Enter" || e.key === " ") {
+          // This is a `role="button"` div, not a native <button>, so the
+          // browser's default Space behavior (page scroll) isn't suppressed
+          // automatically — prevent it before activating.
+          e.preventDefault();
+          onClick?.(finding);
+        }
       }}
       aria-label={finding.message}
     >
diff --git a/templates/design/app/components/design/TokensPanel.test.ts b/templates/design/app/components/design/TokensPanel.test.ts
new file mode 100644
index 0000000000..f12c026a91
--- /dev/null
+++ b/templates/design/app/components/design/TokensPanel.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { isColorValue, normalizeCssVarName } from "./TokensPanel";
+
+describe("isColorValue", () => {
+  it("accepts valid hex color lengths (#rgb, #rgba, #rrggbb, #rrggbbaa)", () => {
+    expect(isColorValue("#fff")).toBe(true);
+    expect(isColorValue("#ffff")).toBe(true);
+    expect(isColorValue("#3B82F6")).toBe(true);
+    expect(isColorValue("#3B82F6FF")).toBe(true);
+  });
+
+  it("rejects malformed hex lengths instead of matching them as colors", () => {
+    // A bare `{3,8}` digit-count range (the original regex) incorrectly
+    // matched 5- and 7-digit hex strings, which aren't valid CSS colors and
+    // render as a blank swatch instead of falling back to the type icon.
+    expect(isColorValue("#12345")).toBe(false);
+    expect(isColorValue("#1234567")).toBe(false);
+  });
+
+  it("still accepts rgba/hsla/oklch/color() functional forms", () => {
+    expect(isColorValue("rgba(59, 130, 246, 1)")).toBe(true);
+    expect(isColorValue("hsl(217 91% 60%)")).toBe(true);
+    expect(isColorValue("oklch(0.6 0.15 240)")).toBe(true);
+    expect(isColorValue("color(display-p3 0.1 0.2 0.3)")).toBe(true);
+  });
+
+  it("rejects non-color token values", () => {
+    expect(isColorValue("0.75rem")).toBe(false);
+    expect(isColorValue("Inter, sans-serif")).toBe(false);
+  });
+});
+
+describe("normalizeCssVarName", () => {
+  it("adds a -- prefix when missing", () => {
+    expect(normalizeCssVarName("my-token")).toBe("--my-token");
+  });
+
+  it("leaves an already-prefixed name untouched", () => {
+    expect(normalizeCssVarName("--my-token")).toBe("--my-token");
+  });
+
+  it("trims surrounding whitespace before checking the prefix", () => {
+    // Regression: trimming after the startsWith("--") check meant a leading
+    // space (e.g. pasted input) produced a doubled, server-rejected name
+    // like "-- --foo" instead of "--foo".
+    expect(normalizeCssVarName("  --foo  ")).toBe("--foo");
+    expect(normalizeCssVarName("  foo  ")).toBe("--foo");
+  });
+});
diff --git a/templates/design/app/components/design/TokensPanel.tsx b/templates/design/app/components/design/TokensPanel.tsx
index ab2b4e485a..fd15c3a24a 100644
--- a/templates/design/app/components/design/TokensPanel.tsx
+++ b/templates/design/app/components/design/TokensPanel.tsx
@@ -108,10 +108,14 @@ export interface TokensPanelProps {
 // ---------------------------------------------------------------------------
 
 /** True when the value looks like an opaque colour we can render as a swatch. */
-function isColorValue(value: string): boolean {
+export function isColorValue(value: string): boolean {
   const v = value.trim();
   return (
-    /^#[0-9a-fA-F]{3,8}$/.test(v) ||
+    // Valid CSS hex-color lengths are exactly 3, 4, 6, or 8 digits (#rgb,
+    // #rgba, #rrggbb, #rrggbbaa) — a bare `{3,8}` range also matched
+    // malformed 5- and 7-digit strings, which render as a blank swatch
+    // instead of falling back to the neutral type icon.
+    /^#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(v) ||
     /^rgba?\(/.test(v) ||
     /^hsla?\(/.test(v) ||
     /^oklch\(/.test(v) ||
@@ -119,6 +123,18 @@ function isColorValue(value: string): boolean {
   );
 }
 
+/**
+ * Normalizes user-typed CSS custom-property input for the manual "Add one
+ * token" flow: trims surrounding whitespace first, then ensures a `--`
+ * prefix. Trimming before the prefix check matters — a leading space (e.g.
+ * pasted input) would otherwise fail `startsWith("--")` and produce a
+ * doubled-up, server-rejected name like `-- --foo`.
+ */
+export function normalizeCssVarName(raw: string): string {
+  const trimmed = raw.trim();
+  return trimmed.startsWith("--") ? trimmed : `--${trimmed}`;
+}
+
 /** Type label + icon for a section header. */
 function typeLabel(type: DesignToken["type"]): {
   label: string;
@@ -146,7 +162,6 @@ function typeLabel(type: DesignToken["type"]): {
 
 interface TokenRowProps {
   token: DesignToken;
-  onEdit: (cssVar: string, value: string) => void;
   editing: boolean;
   editDraft: string;
   onDraftChange: (v: string) => void;
@@ -272,7 +287,6 @@ interface TokenGroupSectionProps {
   onDraftChange: (v: string) => void;
   onCommit: () => void;
   onCancelEdit: () => void;
-  onEdit: (cssVar: string, value: string) => void;
 }
 
 function TokenGroupSection({
@@ -283,7 +297,6 @@ function TokenGroupSection({
   onDraftChange,
   onCommit,
   onCancelEdit,
-  onEdit,
 }: TokenGroupSectionProps) {
   const [collapsed, setCollapsed] = useState(false);
   const { label, Icon } = typeLabel(group.type);
@@ -321,7 +334,6 @@ function TokenGroupSection({
               onCommit={onCommit}
               onStartEdit={() => onStartEdit(token.cssVar, token.value)}
               onCancelEdit={onCancelEdit}
-              onEdit={onEdit}
             />
           ))}
         </div>
@@ -364,12 +376,12 @@ function NewTokenPopover({
   const t = useT();
 
   const handleAdd = () => {
-    const cleanVar = cssVar.startsWith("--") ? cssVar : `--${cssVar}`;
-    onAdd(cleanVar, value);
+    onAdd(normalizeCssVarName(cssVar), value.trim());
     setOpen(false);
     setMode("menu");
     setCssVar("--my-token");
     setValue("#000000");
+    setText("");
   };
 
   const runImport = async (
@@ -394,8 +406,14 @@ function NewTokenPopover({
   const closeOrReset = (nextOpen: boolean) => {
     setOpen(nextOpen);
     if (!nextOpen) {
+      // Reset every draft field, not just mode/status, so reopening the
+      // popover after a dismissed (uncommitted) edit always starts fresh
+      // instead of silently resurrecting a stale cssVar/value/text draft.
       setMode("menu");
       setStatus(null);
+      setCssVar("--my-token");
+      setValue("#000000");
+      setText("");
     }
   };
 
@@ -487,7 +505,7 @@ function NewTokenPopover({
               type="button"
               className="h-7 w-full cursor-pointer !text-[11px]"
               onClick={handleAdd}
-              disabled={!cssVar || !value}
+              disabled={!cssVar.trim() || !value.trim()}
             >
               {t("designEditor.tokens.add")}
             </Button>
@@ -650,6 +668,15 @@ export function TokensPanel({ designId, onTokensApplied }: TokensPanelProps) {
   const applyMutation = useActionMutation("apply-design-token-edit");
   const importMutation = useActionMutation("import-design-tokens");
 
+  // This panel is reused across designs (the editor route swaps `designId`
+  // in place rather than remounting), so an apply/import mutation kicked off
+  // for one design can resolve after the user has already switched to
+  // another. Track the latest `designId` in a ref so a stale response can
+  // detect that and skip pushing its (now wrong-design) resolved CSS vars
+  // into the currently active design via `onTokensApplied`.
+  const designIdRef = useRef(designId);
+  designIdRef.current = designId;
+
   // ------------------------------------------------------------------
   // Local edit state
   // ------------------------------------------------------------------
@@ -666,18 +693,14 @@ export function TokensPanel({ designId, onTokensApplied }: TokensPanelProps) {
     setEditDraft("");
   };
 
-  const commitEdit = () => {
-    if (!editingKey || !editDraft.trim()) {
-      cancelEdit();
-      return;
-    }
-    const cssVar = editingKey;
-    const value = editDraft.trim();
-    cancelEdit();
+  /** Shared apply path for both inline row edits and "Add one token". */
+  const applyTokenEdit = (cssVar: string, value: string) => {
+    const requestDesignId = designId;
     applyMutation.mutate(
       { designId, edits: [{ cssVar, value }] },
       {
         onSuccess: (result) => {
+          if (designIdRef.current !== requestDesignId) return;
           void refetch();
           const r = result as { resolvedCssVars?: Record<string, string> };
           if (r?.resolvedCssVars && onTokensApplied) {
@@ -688,22 +711,26 @@ export function TokensPanel({ designId, onTokensApplied }: TokensPanelProps) {
     );
   };
 
+  const commitEdit = () => {
+    if (!editingKey || !editDraft.trim()) {
+      cancelEdit();
+      return;
+    }
+    const cssVar = editingKey;
+    const value = editDraft.trim();
+    cancelEdit();
+    applyTokenEdit(cssVar, value);
+  };
+
   const handleNewToken = (cssVar: string, value: string) => {
-    applyMutation.mutate(
-      { designId, edits: [{ cssVar, value }] },
-      {
-        onSuccess: (result) => {
-          void refetch();
-          const r = result as { resolvedCssVars?: Record<string, string> };
-          if (r?.resolvedCssVars && onTokensApplied) {
-            onTokensApplied(r.resolvedCssVars);
-          }
-        },
-      },
-    );
+    applyTokenEdit(cssVar, value);
   };
 
-  const handleImportSuccess = (result: ImportDesignTokensResult) => {
+  const handleImportSuccess = (
+    result: ImportDesignTokensResult,
+    requestDesignId: string,
+  ) => {
+    if (designIdRef.current !== requestDesignId) return result;
     void refetch();
     if (result.resolvedCssVars && onTokensApplied) {
       onTokensApplied(result.resolvedCssVars);
@@ -712,29 +739,32 @@ export function TokensPanel({ designId, onTokensApplied }: TokensPanelProps) {
   };
 
   const importFiles = async (files: TokenImportFile[]) => {
+    const requestDesignId = designId;
     const result = (await importMutation.mutateAsync({
       designId,
       source: "files",
       files,
     })) as ImportDesignTokensResult;
-    return handleImportSuccess(result);
+    return handleImportSuccess(result, requestDesignId);
   };
 
   const importText = async (text: string) => {
+    const requestDesignId = designId;
     const result = (await importMutation.mutateAsync({
       designId,
       source: "paste",
       text,
     })) as ImportDesignTokensResult;
-    return handleImportSuccess(result);
+    return handleImportSuccess(result, requestDesignId);
   };
 
   const importCurrentDesign = async () => {
+    const requestDesignId = designId;
     const result = (await importMutation.mutateAsync({
       designId,
       source: "current-design",
     })) as ImportDesignTokensResult;
-    return handleImportSuccess(result);
+    return handleImportSuccess(result, requestDesignId);
   };
 
   // ------------------------------------------------------------------
@@ -821,22 +851,6 @@ export function TokensPanel({ designId, onTokensApplied }: TokensPanelProps) {
                 onDraftChange={setEditDraft}
                 onCommit={commitEdit}
                 onCancelEdit={cancelEdit}
-                onEdit={(cssVar, value) =>
-                  applyMutation.mutate(
-                    { designId, edits: [{ cssVar, value }] },
-                    {
-                      onSuccess: (result) => {
-                        void refetch();
-                        const r = result as {
-                          resolvedCssVars?: Record<string, string>;
-                        };
-                        if (r?.resolvedCssVars && onTokensApplied) {
-                          onTokensApplied(r.resolvedCssVars);
-                        }
-                      },
-                    },
-                  )
-                }
               />
             ))}
           </div>
diff --git a/templates/design/app/components/design/bridge/bridge.guard.spec.ts b/templates/design/app/components/design/bridge/bridge.guard.spec.ts
index bcf5e9a269..26169d7cb5 100644
--- a/templates/design/app/components/design/bridge/bridge.guard.spec.ts
+++ b/templates/design/app/components/design/bridge/bridge.guard.spec.ts
@@ -35,6 +35,7 @@ import { describe, expect, it } from "vitest";
 import { editorChromeBridgeScript } from "../../../../.generated/bridge/editor-chrome.generated";
 import { embeddedWheelBridgeScript } from "../../../../.generated/bridge/embedded-wheel.generated";
 import { hitTestBridgeScript } from "../../../../.generated/bridge/hit-test.generated";
+import { buildCodeLayerProjection } from "../../../../shared/code-layer";
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const designRoot = resolve(__dirname, "../../../..");
@@ -54,14 +55,39 @@ function generatedPath(bridgeFilename: string): string {
   return join(generatedDir, `${name}.generated.ts`);
 }
 
-function hydratedEditorChromeBridgeScript(): string {
+function hydratedEditorChromeBridgeScript(
+  runtimeLayerSnapshotEnabled = false,
+  screenId = "bridge-guard",
+): string {
   return editorChromeBridgeScript
     .replace("__READ_ONLY__", "false")
     .replace("__TEXT_EDITING_ENABLED__", "false")
     .replace("__EDITOR_CHROME_SCALE_X__", "1")
     .replace("__EDITOR_CHROME_SCALE_Y__", "1")
-    .replace("__DESIGN_CANVAS_SCREEN_ID__", JSON.stringify("bridge-guard"))
-    .replace("__DESIGN_CANVAS_BOARD_SURFACE__", "false");
+    .replace("__DESIGN_CANVAS_SCREEN_ID__", JSON.stringify(screenId))
+    .replace("__DESIGN_CANVAS_BOARD_SURFACE__", "false")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_X__", "0")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_Y__", "0")
+    .replace(
+      "__RUNTIME_LAYER_SNAPSHOT_ENABLED__",
+      runtimeLayerSnapshotEnabled ? "true" : "false",
+    );
+}
+
+function hydratedBoardEditorChromeBridgeScriptWithOffset(
+  x: number,
+  y: number,
+): string {
+  return editorChromeBridgeScript
+    .replace("__READ_ONLY__", "false")
+    .replace("__TEXT_EDITING_ENABLED__", "false")
+    .replace("__EDITOR_CHROME_SCALE_X__", "1")
+    .replace("__EDITOR_CHROME_SCALE_Y__", "1")
+    .replace("__DESIGN_CANVAS_SCREEN_ID__", JSON.stringify("board"))
+    .replace("__DESIGN_CANVAS_BOARD_SURFACE__", "true")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_X__", String(x))
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_Y__", String(y))
+    .replace("__RUNTIME_LAYER_SNAPSHOT_ENABLED__", "false");
 }
 
 // Same hydration but with a caller-supplied editor-chrome scale, for the
@@ -76,7 +102,10 @@ function hydratedEditorChromeBridgeScriptWithScale(scale: number): string {
     .replace("__EDITOR_CHROME_SCALE_X__", String(scale))
     .replace("__EDITOR_CHROME_SCALE_Y__", String(scale))
     .replace("__DESIGN_CANVAS_SCREEN_ID__", JSON.stringify("bridge-guard"))
-    .replace("__DESIGN_CANVAS_BOARD_SURFACE__", "false");
+    .replace("__DESIGN_CANVAS_BOARD_SURFACE__", "false")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_X__", "0")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_Y__", "0")
+    .replace("__RUNTIME_LAYER_SNAPSHOT_ENABLED__", "false");
 }
 
 // Same hydration but with text editing enabled, for the text-editing-session
@@ -88,7 +117,10 @@ function hydratedEditorChromeBridgeScriptWithTextEditing(): string {
     .replace("__EDITOR_CHROME_SCALE_X__", "1")
     .replace("__EDITOR_CHROME_SCALE_Y__", "1")
     .replace("__DESIGN_CANVAS_SCREEN_ID__", JSON.stringify("bridge-guard"))
-    .replace("__DESIGN_CANVAS_BOARD_SURFACE__", "false");
+    .replace("__DESIGN_CANVAS_BOARD_SURFACE__", "false")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_X__", "0")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_Y__", "0")
+    .replace("__RUNTIME_LAYER_SNAPSHOT_ENABLED__", "false");
 }
 
 function hydratedEmbeddedCanvasGestureBridgeScript(options?: {
@@ -291,6 +323,45 @@ it(
         ),
       ).toBe(1);
 
+      // Overview/focused transitions now keep one installed gesture script
+      // and change wheel routing in place. This keeps the localhost bridge
+      // key stable across Full view instead of forcing a new registration.
+      await page.mouse.move(centerX, centerY);
+      await page.mouse.wheel(0, 40);
+      expect(
+        (
+          await page.evaluate(
+            () =>
+              (
+                window as Window & {
+                  __bridgeMessages?: Array<{ type?: string }>;
+                }
+              ).__bridgeMessages ?? [],
+          )
+        ).filter((message) => message.type === "embedded-canvas-wheel"),
+      ).toHaveLength(0);
+      await page.evaluate(() => {
+        window.postMessage(
+          {
+            type: "embedded-canvas-gesture-mode",
+            wheelEnabled: true,
+            spaceKeyForwardingEnabled: true,
+          },
+          "*",
+        );
+      });
+      await page.waitForTimeout(0);
+      await page.mouse.wheel(0, 40);
+      await page.waitForFunction(() =>
+        (
+          (
+            window as Window & {
+              __bridgeMessages?: Array<{ type?: string }>;
+            }
+          ).__bridgeMessages ?? []
+        ).some((message) => message.type === "embedded-canvas-wheel"),
+      );
+
       // Middle-button drag is always a canvas pan and never reaches app code.
       await page.mouse.move(centerX, centerY);
       await page.mouse.down({ button: "middle" });
@@ -1369,6 +1440,306 @@ it(
   },
 );
 
+// ── Resize origin must seed from RENDERED px, not the raw CSS value ───────
+//
+// startResize used to read `resizeEl.style.width || cs.width` — the raw
+// inline style string wins whenever one is set, and readPx() just runs it
+// through parseFloat. For a non-px value like "100%" that parses to the
+// number 100 and is silently treated as 100px, so growing a `width: 100%;
+// height: 160px` element's SE corner by (+50, +30) produced height 190px
+// (correct) but width 150px (100 + 50) instead of the ~408px the box was
+// actually rendered at — a shrink instead of a grow. The fix reads
+// getComputedStyle().width/height instead, which always resolves to the
+// element's used-value pixel size regardless of the authored unit (%, em,
+// rem, vh, vw, calc(), auto) and is unaffected by rotation.
+it(
+  "editor chrome bridge resize seeds the origin from rendered pixels for every non-px CSS width/height unit (%, vw/vh, rem, em, calc)",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; font-size: 16px; }
+      body { background: white; }
+      #wrap {
+        position: absolute; left: 0; top: 0; width: 400px; height: 400px;
+      }
+      #target {
+        position: absolute; left: 20px; top: 20px; height: 100px;
+        font-size: 20px; background: #e9eef8; border: none;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="wrap"><div id="target" data-agent-native-node-id="target">Target</div></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+
+      const DELTA = 40;
+      const widthUnits = ["50%", "20vw", "3rem", "2em", "calc(50% + 20px)"];
+      for (const unit of widthUnits) {
+        await page.evaluate(
+          ({ unit }) => {
+            const target = document.querySelector<HTMLElement>("#target")!;
+            target.style.width = unit;
+            target.style.height = "100px";
+          },
+          { unit },
+        );
+        // Re-click to (re)select and force the overlay to reposition against
+        // the just-changed rendered box before reading the handle position.
+        await page.mouse.click(30, 30);
+        await page.waitForFunction(() => {
+          const overlay = document.querySelector<HTMLElement>(
+            '[data-agent-native-edit-overlay="selection"]',
+          );
+          return (
+            overlay && window.getComputedStyle(overlay).display === "block"
+          );
+        });
+
+        const before = await page.evaluate(
+          () =>
+            document.querySelector("#target")!.getBoundingClientRect().width,
+        );
+
+        const eHandle = page.locator('[data-agent-native-edge-handle="e"]');
+        const eBox = await eHandle.boundingBox();
+        if (!eBox)
+          throw new Error(`"e" edge handle not found for unit ${unit}`);
+        const cx = eBox.x + eBox.width / 2;
+        const cy = eBox.y + eBox.height / 2;
+        await page.mouse.move(cx, cy);
+        await page.mouse.down();
+        await page.mouse.move(cx + DELTA, cy);
+        await page.mouse.up();
+
+        const after = await page.evaluate(
+          () =>
+            document.querySelector("#target")!.getBoundingClientRect().width,
+        );
+        expect(after - before, `unit=${unit}`).toBeGreaterThan(DELTA - 2);
+        expect(after - before, `unit=${unit}`).toBeLessThan(DELTA + 2);
+      }
+
+      // Reset width to a fixed px baseline and run the same matrix for height
+      // via the pure-vertical "s" edge handle.
+      const heightUnits = ["50%", "20vh", "3rem", "2em", "calc(50% + 20px)"];
+      for (const unit of heightUnits) {
+        await page.evaluate(
+          ({ unit }) => {
+            const target = document.querySelector<HTMLElement>("#target")!;
+            target.style.width = "100px";
+            target.style.height = unit;
+          },
+          { unit },
+        );
+        await page.mouse.click(30, 30);
+        await page.waitForFunction(() => {
+          const overlay = document.querySelector<HTMLElement>(
+            '[data-agent-native-edit-overlay="selection"]',
+          );
+          return (
+            overlay && window.getComputedStyle(overlay).display === "block"
+          );
+        });
+
+        const before = await page.evaluate(
+          () =>
+            document.querySelector("#target")!.getBoundingClientRect().height,
+        );
+
+        const sHandle = page.locator('[data-agent-native-edge-handle="s"]');
+        const sBox = await sHandle.boundingBox();
+        if (!sBox)
+          throw new Error(`"s" edge handle not found for unit ${unit}`);
+        const cx = sBox.x + sBox.width / 2;
+        const cy = sBox.y + sBox.height / 2;
+        await page.mouse.move(cx, cy);
+        await page.mouse.down();
+        await page.mouse.move(cx, cy + DELTA);
+        await page.mouse.up();
+
+        const after = await page.evaluate(
+          () =>
+            document.querySelector("#target")!.getBoundingClientRect().height,
+        );
+        expect(after - before, `unit=${unit}`).toBeGreaterThan(DELTA - 2);
+        expect(after - before, `unit=${unit}`).toBeLessThan(DELTA + 2);
+      }
+
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── Live repro: SE-corner resize of a `width:100%; height:160px` element ──
+it(
+  "editor chrome bridge SE-corner resize of a width:100% element grows width from its rendered size, not from a shrunk parsed-percentage value",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { background: white; }
+      #wrap { position: absolute; left: 0; top: 0; width: 500px; height: 400px; }
+    </style>
+  </head>
+  <body>
+    <div id="wrap"><div id="target" data-agent-native-node-id="target" style="position: absolute; left: 20px; top: 20px; width: 100%; height: 160px; background: #e9eef8;">Target</div></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+
+      const renderedBefore = await page.evaluate(() => {
+        const target = document.querySelector<HTMLElement>("#target")!;
+        return {
+          width: target.getBoundingClientRect().width,
+          height: target.getBoundingClientRect().height,
+        };
+      });
+      // Sanity check the fixture: width:100% inside a 500px wrap renders at
+      // 500px, well above the old parseFloat("100%") -> 100 misread.
+      expect(renderedBefore.width).toBeCloseTo(500, 0);
+      expect(renderedBefore.height).toBeCloseTo(160, 0);
+
+      await page.mouse.click(30, 30);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+
+      const seHandle = page.locator('[data-agent-native-edit-handle="se"]');
+      const seBox = await seHandle.boundingBox();
+      if (!seBox) throw new Error("resize handle not found");
+      const cx = seBox.x + seBox.width / 2;
+      const cy = seBox.y + seBox.height / 2;
+      await page.mouse.move(cx, cy);
+      await page.mouse.down();
+      await page.mouse.move(cx + 50, cy + 30);
+      await page.mouse.up();
+
+      const after = await page.evaluate(() => {
+        const target = document.querySelector<HTMLElement>("#target")!;
+        return {
+          width: target.style.width,
+          height: target.style.height,
+          renderedWidth: target.getBoundingClientRect().width,
+        };
+      });
+      // Height (a plain px value the whole time) behaves as before.
+      expect(after.height).toBe("190px");
+      // Width must grow from the rendered ~500px, landing at ~550px — NOT
+      // shrink to 150px (the pre-fix 100 + 50 parseFloat("100%") result).
+      expect(after.width).not.toBe("150px");
+      expect(after.renderedWidth).toBeGreaterThan(500);
+      expect(after.renderedWidth).toBeCloseTo(550, 0);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── Commit semantics: only the dragged axis is written back ───────────────
+it(
+  "editor chrome bridge resize commits only the axis the user actually dragged, leaving a percentage width untouched on a pure vertical drag",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { background: white; }
+      #wrap { position: absolute; left: 0; top: 0; width: 500px; height: 400px; }
+    </style>
+  </head>
+  <body>
+    <div id="wrap"><div id="target" data-agent-native-node-id="target" style="position: absolute; left: 20px; top: 20px; width: 100%; height: 160px; background: #e9eef8;">Target</div></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+
+      await page.mouse.click(30, 30);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+
+      // Pure vertical drag: the "s" EDGE handle (not a corner), so width
+      // should never enter into the gesture at all.
+      const sHandle = page.locator('[data-agent-native-edge-handle="s"]');
+      const sBox = await sHandle.boundingBox();
+      if (!sBox) throw new Error("resize handle not found");
+      const cx = sBox.x + sBox.width / 2;
+      const cy = sBox.y + sBox.height / 2;
+      await page.mouse.move(cx, cy);
+      await page.mouse.down();
+      await page.mouse.move(cx, cy + 30);
+      await page.mouse.up();
+
+      const after = await page.evaluate(() => {
+        const target = document.querySelector<HTMLElement>("#target")!;
+        return {
+          width: target.style.width,
+          height: target.style.height,
+          renderedWidth: target.getBoundingClientRect().width,
+        };
+      });
+      // Height is the dragged axis — committed as px.
+      expect(after.height).toBe("190px");
+      // Width was NEVER dragged — must still be the original percentage
+      // string, not silently rewritten to a px value.
+      expect(after.width).toBe("100%");
+      expect(after.renderedWidth).toBeCloseTo(500, 0);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
 it(
   "editor chrome bridge renders gradient edit handles for gradient-edit-target and emits gradient-edit-change while dragging an endpoint",
   { timeout: 30_000 },
@@ -3485,6 +3856,24 @@ it(
     <div id="dragme" data-agent-native-node-id="dragme">Drag me</div>
   </body>
 </html>`);
+      // React 19's development Fiber stack is the source of truth for local
+      // TSX nodes that do not carry explicit data-source-* attributes. The
+      // structure-change contract must preserve the DROP ANCHOR's provenance,
+      // not only the dragged node's payload, so the host can resolve both AST
+      // anchors without guessing from a selector after the optimistic reparent.
+      await page.locator("#frame").evaluate((element) => {
+        Object.defineProperty(element, "__reactFiber$structureanchor", {
+          configurable: true,
+          enumerable: true,
+          value: {
+            _debugStack: {
+              stack:
+                "Error\n    at SettingsFrame (http://127.0.0.1:7331/app/components/SettingsFrame.tsx:42:7)",
+            },
+            return: null,
+          },
+        });
+      });
       await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
       await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
       await collectBridgeMessages(page);
@@ -3566,6 +3955,21 @@ it(
       expect(structureMessage).toBeTruthy();
       expect(structureMessage.dropMode).toBe("flow-insert");
       expect(structureMessage.placement).toBe("inside");
+      expect(structureMessage.anchorPayload).toMatchObject({
+        tagName: "div",
+        id: "frame",
+        sourceId: "frame",
+        selector: '[data-agent-native-node-id="frame"]',
+        provenance: {
+          sourceFile: "app/components/SettingsFrame.tsx",
+          line: 42,
+          column: 7,
+          component: "SettingsFrame",
+        },
+      });
+      expect(structureMessage.anchorPayload.computedStyles.display).toBe(
+        "flex",
+      );
       // The style conversion must be posted before the structural move so the
       // host applies them in order against its synchronous content refs.
       expect(messages.indexOf(styleMessage)).toBeLessThan(
@@ -3791,9 +4195,24 @@ it(
 );
 
 it(
-  "editor chrome bridge respects the insertion index when dropping between existing children of a converted container",
+  "editor chrome bridge rebases left/top correctly through TWO levels of nested containing blocks under a non-zero board offset",
   { timeout: 30_000 },
   async () => {
+    // Coverage gap flagged by review: rebaseAbsoluteMemberForContainerDrop's
+    // old/new containing-block origin math (editor-chrome.bridge.ts, the
+    // "Absolute-container nest rebase" block above) is only exercised with
+    // the member and the drop container each ONE level of nesting below the
+    // single translated board-root node (see the "removes the finite board
+    // render offset" test above, where #note/#container sit directly on
+    // body). Here #note's containing block (#outer) is nested inside #screen
+    // (the translated root), and the drop target (#inner) is nested a level
+    // deeper still, inside #outer — a genuine two-level-nested containing
+    // block chain. Since the board's render-time translate is applied once,
+    // at #screen, both #outer's and #inner's getBoundingClientRect() already
+    // bake in that single offset regardless of how deep they sit beneath
+    // #screen, so the "subtract boardOffset once" math in
+    // rebaseAbsoluteMemberForContainerDrop should hold at any nesting depth,
+    // not just one level. This asserts that holds.
     const browser = await chromium.launch({ headless: true });
     const pageErrors: string[] = [];
 
@@ -3802,48 +4221,259 @@ it(
         viewport: { width: 900, height: 700 },
       });
       page.on("pageerror", (err) => pageErrors.push(err.message));
-
       await page.setContent(`<!doctype html>
 <html>
   <head>
     <style>
       html, body { margin: 0; width: 100%; height: 100%; }
-      body { background: white; }
-      #frame {
+      body { position: relative; }
+      body > [data-agent-native-node-id="screen"] { translate: 4096px 4096px; }
+      #screen {
+        position: absolute; left: -4096px; top: -4096px;
+        width: 900px; height: 700px;
+      }
+      #outer {
         position: absolute; left: 300px; top: 100px;
-        width: 320px; height: 240px; background: #f4f4f8;
-        margin: 0; padding: 0;
+        width: 400px; height: 300px; background: #f4f4f8;
+        border: 2px solid #999999;
       }
-      /* Genuine flex children — normal flow, no absolute positioning, so
-         layout (and this test's insertion-index assertion) is driven purely
-         by flex-direction:column + gap, matching what a real converted
-         container looks like. */
-      .child {
-        width: 100px; height: 60px; background: #a5b4fc;
-        margin: 0;
+      #inner {
+        position: absolute; left: 20px; top: 20px;
+        width: 200px; height: 140px; background: #eeeeee;
+        border: 2px solid #888888; overflow: hidden;
       }
-      #dragme {
-        position: absolute; left: 40px; top: 400px;
-        width: 80px; height: 60px; background: #6366f1;
+      #note {
+        position: absolute; left: 40px; top: 180px;
+        width: 80px; height: 40px; background: #6366f1;
       }
     </style>
   </head>
   <body>
-    <div id="frame" data-agent-native-node-id="frame">
-      <div id="childA" class="child" data-agent-native-node-id="childA">A</div>
-      <div id="childB" class="child" data-agent-native-node-id="childB">B</div>
+    <div id="screen" data-agent-native-node-id="screen">
+      <div id="outer" data-an-primitive="frame" data-agent-native-node-id="outer">
+        <div id="inner" data-an-primitive="frame" data-agent-native-node-id="inner"></div>
+        <div id="note" data-agent-native-node-id="note">Note</div>
+      </div>
     </div>
-    <div id="dragme" data-agent-native-node-id="dragme">Drag me</div>
   </body>
 </html>`);
-      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.addScriptTag({
+        content: hydratedBoardEditorChromeBridgeScriptWithOffset(4096, 4096),
+      });
       await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
 
-      // #frame is already display:flex (auto-layout) here via inline style
-      // set after load, so this test isolates "respect insertion index"
-      // from the "convert to auto-layout" behavior covered above.
-      await page.evaluate(() => {
-        const frame = document.querySelector<HTMLElement>("#frame")!;
+      // #note renders at roughly (342, 282)-(422, 322) on screen
+      // (outer's origin ~(300,100) + 2px border + note's own left/top).
+      await page.mouse.click(382, 302);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+      await page.mouse.move(382, 302);
+      await page.mouse.down();
+      await page.mouse.move(392, 312); // crosses the 3px threshold → reference
+      await page.mouse.move(420, 190); // #inner's interior
+
+      const preDropRect = await page.evaluate(() => {
+        const rect = document.querySelector("#note")!.getBoundingClientRect();
+        return { left: rect.left, top: rect.top };
+      });
+      await page.mouse.up();
+      await page.waitForTimeout(30);
+
+      const result = await page.evaluate(() => {
+        const note = document.querySelector<HTMLElement>("#note")!;
+        const inner = document.querySelector<HTMLElement>("#inner")!;
+        const noteRect = note.getBoundingClientRect();
+        const innerRect = inner.getBoundingClientRect();
+        return {
+          parentId: note.parentElement?.id,
+          position: window.getComputedStyle(note).position,
+          styleLeft: Number.parseFloat(note.style.left),
+          styleTop: Number.parseFloat(note.style.top),
+          rectLeft: noteRect.left,
+          rectTop: noteRect.top,
+          // #inner's padding-edge origin (border box + 2px border).
+          innerPaddingLeft: innerRect.left + 2,
+          innerPaddingTop: innerRect.top + 2,
+        };
+      });
+
+      expect(result.parentId).toBe("inner");
+      expect(result.position).toBe("absolute");
+      // The on-screen position survives the reparent bit-for-bit through both
+      // nesting levels...
+      expect(Math.abs(result.rectLeft - preDropRect.left)).toBeLessThan(1);
+      expect(Math.abs(result.rectTop - preDropRect.top)).toBeLessThan(1);
+      // ...because left/top were rebased into #inner's padding-edge space —
+      // small parent-relative numbers, not #outer- or #screen-relative ones.
+      expect(
+        Math.abs(
+          result.styleLeft - (result.rectLeft - result.innerPaddingLeft),
+        ),
+      ).toBeLessThan(1);
+      expect(
+        Math.abs(result.styleTop - (result.rectTop - result.innerPaddingTop)),
+      ).toBeLessThan(1);
+      expect(result.styleLeft).toBeGreaterThanOrEqual(0);
+      expect(result.styleLeft).toBeLessThan(200);
+      expect(result.styleTop).toBeGreaterThanOrEqual(0);
+      expect(result.styleTop).toBeLessThan(140);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "editor chrome bridge removes the finite board render offset when nesting into a frame",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { position: relative; }
+      body > [data-agent-native-node-id] { translate: 4096px 4096px; }
+      #container {
+        position: absolute; left: -3696px; top: -3896px;
+        width: 220px; height: 160px; background: #f4f4f8;
+        border: 2px solid #cccccc; overflow: hidden;
+      }
+      #note {
+        position: absolute; left: -4036px; top: -3696px;
+        width: 100px; height: 40px; background: #6366f1;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="container" data-an-primitive="frame" data-agent-native-node-id="container"></div>
+    <div id="note" data-agent-native-node-id="note">Note</div>
+  </body>
+</html>`);
+      await page.addScriptTag({
+        content: hydratedBoardEditorChromeBridgeScriptWithOffset(4096, 4096),
+      });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      await page.mouse.click(110, 420);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+      await page.mouse.move(110, 420);
+      await page.mouse.down();
+      await page.mouse.move(120, 430);
+      await page.mouse.move(510, 280);
+      await page.mouse.up();
+      await page.waitForTimeout(30);
+
+      const result = await page.evaluate(() => {
+        const note = document.querySelector<HTMLElement>("#note")!;
+        const container = document.querySelector<HTMLElement>("#container")!;
+        const noteRect = note.getBoundingClientRect();
+        const containerRect = container.getBoundingClientRect();
+        return {
+          parentId: note.parentElement?.id,
+          styleLeft: Number.parseFloat(note.style.left),
+          styleTop: Number.parseFloat(note.style.top),
+          rectLeft: noteRect.left,
+          rectTop: noteRect.top,
+          containerLeft: containerRect.left,
+          containerTop: containerRect.top,
+        };
+      });
+
+      expect(result.parentId).toBe("container");
+      expect(result.styleLeft).toBeGreaterThanOrEqual(0);
+      expect(result.styleLeft).toBeLessThan(220);
+      expect(result.styleTop).toBeGreaterThanOrEqual(0);
+      expect(result.styleTop).toBeLessThan(160);
+      expect(result.rectLeft).toBeGreaterThanOrEqual(result.containerLeft);
+      expect(result.rectTop).toBeGreaterThanOrEqual(result.containerTop);
+      const messages = await readBridgeMessages(page);
+      const structureMessage = messages.find(
+        (message) => message.type === "visual-structure-change",
+      ) as any;
+      expect(structureMessage?.dropMode).toBe("absolute-container");
+      expect(structureMessage?.anchorSourceId).toBe("container");
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "editor chrome bridge respects the insertion index when dropping between existing children of a converted container",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { background: white; }
+      #frame {
+        position: absolute; left: 300px; top: 100px;
+        width: 320px; height: 240px; background: #f4f4f8;
+        margin: 0; padding: 0;
+      }
+      /* Genuine flex children — normal flow, no absolute positioning, so
+         layout (and this test's insertion-index assertion) is driven purely
+         by flex-direction:column + gap, matching what a real converted
+         container looks like. */
+      .child {
+        width: 100px; height: 60px; background: #a5b4fc;
+        margin: 0;
+      }
+      #dragme {
+        position: absolute; left: 40px; top: 400px;
+        width: 80px; height: 60px; background: #6366f1;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="frame" data-agent-native-node-id="frame">
+      <div id="childA" class="child" data-agent-native-node-id="childA">A</div>
+      <div id="childB" class="child" data-agent-native-node-id="childB">B</div>
+    </div>
+    <div id="dragme" data-agent-native-node-id="dragme">Drag me</div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+
+      // #frame is already display:flex (auto-layout) here via inline style
+      // set after load, so this test isolates "respect insertion index"
+      // from the "convert to auto-layout" behavior covered above.
+      await page.evaluate(() => {
+        const frame = document.querySelector<HTMLElement>("#frame")!;
         frame.style.display = "flex";
         frame.style.flexDirection = "column";
         frame.style.gap = "8px";
@@ -4197,7 +4827,7 @@ it(
 );
 
 it(
-  "editor chrome bridge still collapses the selection on a plain click (no drag) on a group member",
+  "editor chrome bridge round-trips flow child through freeform root, flow, and absolute container",
   { timeout: 30_000 },
   async () => {
     const browser = await chromium.launch({ headless: true });
@@ -4207,65 +4837,123 @@ it(
         viewport: { width: 900, height: 700 },
       });
       page.on("pageerror", (err) => pageErrors.push(err.message));
-
       await page.setContent(`<!doctype html>
 <html>
   <head>
     <style>
       html, body { margin: 0; width: 100%; height: 100%; }
-      body { background: white; }
-      .box { position: absolute; width: 120px; height: 80px; }
-      #boxA { left: 60px; top: 60px; background: #6366f1; }
-      #boxB { left: 260px; top: 60px; background: #22c55e; }
+      body { position: relative; background: white; }
+      .flow { position: absolute; top: 40px; width: 220px; min-height: 150px; padding: 12px; display: flex; flex-direction: column; gap: 8px; box-sizing: border-box; background: #f5f5f5; }
+      #flowA { left: 40px; }
+      #flowB { left: 340px; }
+      #item { width: 100px; height: 44px; background: #6366f1; color: white; }
+      #absoluteFrame { position: absolute; left: 340px; top: 300px; width: 240px; height: 180px; background: #eef2ff; }
     </style>
   </head>
   <body>
-    <div id="boxA" class="box" data-agent-native-node-id="boxA">A</div>
-    <div id="boxB" class="box" data-agent-native-node-id="boxB">B</div>
+    <div id="flowA" class="flow" data-agent-native-node-id="flowA">
+      <div id="item" data-agent-native-node-id="item">Move me</div>
+    </div>
+    <div id="flowB" class="flow" data-agent-native-node-id="flowB"></div>
+    <div id="absoluteFrame" data-agent-native-node-id="absoluteFrame" data-an-primitive="frame"></div>
   </body>
 </html>`);
       await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
       await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
 
-      await page.mouse.click(120, 100);
-      await page.waitForFunction(() => {
-        const overlay = document.querySelector<HTMLElement>(
-          '[data-agent-native-edit-overlay="selection"]',
-        );
-        return overlay && window.getComputedStyle(overlay).display === "block";
+      const dragTo = async (x: number, y: number) => {
+        const box = (await page.locator("#item").boundingBox())!;
+        const startX = box.x + box.width / 2;
+        const startY = box.y + box.height / 2;
+        await page.mouse.click(startX, startY);
+        await page.waitForTimeout(30);
+        await page.mouse.move(startX, startY);
+        await page.mouse.down();
+        await page.mouse.move(startX + 5, startY + 5, { steps: 2 });
+        await page.mouse.move(x, y, { steps: 8 });
+        await page.mouse.up();
+        await page.waitForTimeout(50);
+      };
+
+      // Flow -> freeform root: release-point placement with the original
+      // pointer offset preserved.
+      await dragTo(760, 560);
+      const rootResult = await page.evaluate(() => {
+        const item = document.querySelector<HTMLElement>("#item")!;
+        const rect = item.getBoundingClientRect();
+        return {
+          parentId: item.parentElement?.id || item.parentElement?.tagName,
+          position: window.getComputedStyle(item).position,
+          left: rect.left,
+          top: rect.top,
+        };
       });
-      await page.keyboard.down("Shift");
-      await page.mouse.click(320, 100);
-      await page.keyboard.up("Shift");
-      await page.waitForFunction(() => {
-        const passive = document.querySelector<HTMLElement>(
-          '[data-agent-native-edit-overlay="multi-selection"]',
-        );
-        return passive && window.getComputedStyle(passive).display !== "none";
+      expect(rootResult.parentId).toBe("BODY");
+      expect(rootResult.position).toBe("absolute");
+      expect(rootResult.left).toBeCloseTo(710, 0);
+      expect(rootResult.top).toBeCloseTo(538, 0);
+
+      // Absolute root -> flow: absolute position props are stripped and the
+      // element occupies a real flow slot.
+      await dragTo(450, 105);
+      const flowResult = await page.evaluate(() => {
+        const item = document.querySelector<HTMLElement>("#item")!;
+        return {
+          parentId: item.parentElement?.id,
+          position: window.getComputedStyle(item).position,
+          left: item.style.left,
+          top: item.style.top,
+        };
+      });
+      expect(flowResult.parentId).toBe("flowB");
+      expect(["static", "relative"]).toContain(flowResult.position);
+      expect(flowResult.left).toBe("");
+      expect(flowResult.top).toBe("");
+
+      // Flow -> absolute frame keeps the visual release point and absolute
+      // semantics inside the new containing block.
+      await dragTo(460, 390);
+      const frameResult = await page.evaluate(() => {
+        const item = document.querySelector<HTMLElement>("#item")!;
+        const rect = item.getBoundingClientRect();
+        return {
+          parentId: item.parentElement?.id,
+          position: window.getComputedStyle(item).position,
+          left: rect.left,
+          top: rect.top,
+        };
       });
+      expect(frameResult.parentId).toBe("absoluteFrame");
+      expect(frameResult.position).toBe("absolute");
+      expect(frameResult.left).toBeCloseTo(410, 0);
+      expect(frameResult.top).toBeCloseTo(368, 0);
 
-      // Plain click (no movement) on member A: collapses the selection to A
-      // (existing disambiguation) — the collapse is signaled to the host as a
-      // non-additive element-select for A, and no move messages fire.
-      await collectBridgeMessages(page);
-      await page.mouse.click(120, 100);
-      await page.waitForTimeout(30);
+      // Absolute frame -> flow completes the round trip.
+      await dragTo(145, 105);
+      const roundTripResult = await page.evaluate(() => {
+        const item = document.querySelector<HTMLElement>("#item")!;
+        return {
+          parentId: item.parentElement?.id,
+          position: window.getComputedStyle(item).position,
+        };
+      });
+      expect(roundTripResult.parentId).toBe("flowA");
+      expect(["static", "relative"]).toContain(roundTripResult.position);
 
       const messages = await readBridgeMessages(page);
-      const selects = messages.filter(
-        (m) => m.type === "element-select",
-      ) as any[];
-      expect(selects.length).toBeGreaterThan(0);
-      const lastSelect = selects[selects.length - 1];
-      expect(lastSelect.payload.selector).toContain("boxA");
-      expect(Boolean(lastSelect.intent?.additive)).toBe(false);
+      const structureMessages = messages.filter(
+        (message) => message.type === "visual-structure-change",
+      ) as Array<{ dropMode?: string; placement?: string }>;
+      expect(structureMessages.map((message) => message.dropMode)).toEqual([
+        "absolute-container",
+        "flow-insert",
+        "absolute-container",
+        "flow-insert",
+      ]);
       expect(
-        messages.some(
-          (m) =>
-            m.type === "visual-structure-change" ||
-            m.type === "visual-style-change",
-        ),
-      ).toBe(false);
+        structureMessages.every((message) => message.placement === "inside"),
+      ).toBe(true);
       expect(pageErrors).toEqual([]);
     } finally {
       await browser.close();
@@ -4273,33 +4961,205 @@ it(
   },
 );
 
-// ── Zoom-invariant chrome (constant screen size) ────────────────────────────
-//
-// The host CSS-scales the whole iframe by the canvas zoom and reports that
-// scale to the bridge; every piece of editor chrome must multiply its
-// intrinsic sizes by the inverse so the APPARENT size on screen is constant
-// at any zoom — zoomed out (scale < 1) AND zoomed in (scale > 1, where the
-// old Math.max(1, …) floors made chrome render chunky).
-
 it(
-  "editor chrome bridge renders selection border, handles, and the spacing badge at constant screen size across zoom levels",
-  { timeout: 60_000 },
+  "editor chrome bridge honors Space retain-parent and Control Ignore-auto-layout modifiers",
+  { timeout: 30_000 },
   async () => {
     const browser = await chromium.launch({ headless: true });
     const pageErrors: string[] = [];
     try {
-      const observed: Array<{
-        scale: number;
-        screenSelBorder: number;
-        screenHandle: number;
-        screenBadgeFont: number;
-        badgeShown: boolean;
-      }> = [];
-      for (const scale of [0.19, 1, 2.67]) {
-        const page = await browser.newPage({
-          viewport: { width: 900, height: 700 },
-        });
-        page.on("pageerror", (err) => pageErrors.push(err.message));
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { position: relative; background: white; }
+      .flow { position: absolute; top: 40px; width: 220px; min-height: 180px; padding: 12px; display: flex; flex-direction: column; gap: 8px; box-sizing: border-box; background: #f5f5f5; }
+      #flowA { left: 40px; }
+      #flowB { left: 340px; }
+      .item { width: 100px; height: 44px; color: white; }
+      #spaceItem { background: #6366f1; }
+      #controlItem { background: #22c55e; }
+    </style>
+  </head>
+  <body>
+    <div id="flowA" class="flow" data-agent-native-node-id="flowA">
+      <div id="spaceItem" class="item" data-agent-native-node-id="spaceItem">Space</div>
+      <div id="controlItem" class="item" data-agent-native-node-id="controlItem">Control</div>
+    </div>
+    <div id="flowB" class="flow" data-agent-native-node-id="flowB"></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      const spaceBox = (await page.locator("#spaceItem").boundingBox())!;
+      const spaceStartX = spaceBox.x + spaceBox.width / 2;
+      const spaceStartY = spaceBox.y + spaceBox.height / 2;
+      await page.mouse.click(spaceStartX, spaceStartY);
+      await page.mouse.move(spaceStartX, spaceStartY);
+      await page.mouse.down();
+      await page.keyboard.down("Space");
+      await page.mouse.move(760, 560, { steps: 8 });
+      await page.mouse.up();
+      await page.keyboard.up("Space");
+      await page.waitForTimeout(50);
+
+      const retained = await page.evaluate(() => {
+        const item = document.querySelector<HTMLElement>("#spaceItem")!;
+        return {
+          parentId: item.parentElement?.id,
+          position: window.getComputedStyle(item).position,
+        };
+      });
+      expect(retained.parentId).toBe("flowA");
+      expect(["static", "relative"]).toContain(retained.position);
+
+      const controlBox = (await page.locator("#controlItem").boundingBox())!;
+      const controlStartX = controlBox.x + controlBox.width / 2;
+      const controlStartY = controlBox.y + controlBox.height / 2;
+      await page.mouse.click(controlStartX, controlStartY);
+      await page.mouse.move(controlStartX, controlStartY);
+      await page.mouse.down();
+      await page.keyboard.down("Control");
+      await page.mouse.move(450, 115, { steps: 8 });
+      await page.mouse.up();
+      await page.keyboard.up("Control");
+      await page.waitForTimeout(50);
+
+      const ignored = await page.evaluate(() => {
+        const item = document.querySelector<HTMLElement>("#controlItem")!;
+        return {
+          parentId: item.parentElement?.id,
+          position: window.getComputedStyle(item).position,
+        };
+      });
+      expect(ignored.parentId).toBe("flowB");
+      expect(ignored.position).toBe("absolute");
+
+      const messages = await readBridgeMessages(page);
+      const structureMessages = messages.filter(
+        (message) => message.type === "visual-structure-change",
+      ) as Array<{ dropMode?: string }>;
+      expect(structureMessages[structureMessages.length - 1]?.dropMode).toBe(
+        "absolute-container",
+      );
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "editor chrome bridge still collapses the selection on a plain click (no drag) on a group member",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { background: white; }
+      .box { position: absolute; width: 120px; height: 80px; }
+      #boxA { left: 60px; top: 60px; background: #6366f1; }
+      #boxB { left: 260px; top: 60px; background: #22c55e; }
+    </style>
+  </head>
+  <body>
+    <div id="boxA" class="box" data-agent-native-node-id="boxA">A</div>
+    <div id="boxB" class="box" data-agent-native-node-id="boxB">B</div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+
+      await page.mouse.click(120, 100);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+      await page.keyboard.down("Shift");
+      await page.mouse.click(320, 100);
+      await page.keyboard.up("Shift");
+      await page.waitForFunction(() => {
+        const passive = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="multi-selection"]',
+        );
+        return passive && window.getComputedStyle(passive).display !== "none";
+      });
+
+      // Plain click (no movement) on member A: collapses the selection to A
+      // (existing disambiguation) — the collapse is signaled to the host as a
+      // non-additive element-select for A, and no move messages fire.
+      await collectBridgeMessages(page);
+      await page.mouse.click(120, 100);
+      await page.waitForTimeout(30);
+
+      const messages = await readBridgeMessages(page);
+      const selects = messages.filter(
+        (m) => m.type === "element-select",
+      ) as any[];
+      expect(selects.length).toBeGreaterThan(0);
+      const lastSelect = selects[selects.length - 1];
+      expect(lastSelect.payload.selector).toContain("boxA");
+      expect(Boolean(lastSelect.intent?.additive)).toBe(false);
+      expect(
+        messages.some(
+          (m) =>
+            m.type === "visual-structure-change" ||
+            m.type === "visual-style-change",
+        ),
+      ).toBe(false);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── Zoom-invariant chrome (constant screen size) ────────────────────────────
+//
+// The host CSS-scales the whole iframe by the canvas zoom and reports that
+// scale to the bridge; every piece of editor chrome must multiply its
+// intrinsic sizes by the inverse so the APPARENT size on screen is constant
+// at any zoom — zoomed out (scale < 1) AND zoomed in (scale > 1, where the
+// old Math.max(1, …) floors made chrome render chunky).
+
+it(
+  "editor chrome bridge renders selection border, handles, and the spacing badge at constant screen size across zoom levels",
+  { timeout: 60_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const observed: Array<{
+        scale: number;
+        screenSelBorder: number;
+        screenHandle: number;
+        screenBadgeFont: number;
+        badgeShown: boolean;
+      }> = [];
+      for (const scale of [0.19, 1, 2.67]) {
+        const page = await browser.newPage({
+          viewport: { width: 900, height: 700 },
+        });
+        page.on("pageerror", (err) => pageErrors.push(err.message));
         await page.setContent(`<!doctype html>
 <html>
   <head>
@@ -4670,7 +5530,7 @@ it(
 );
 
 it(
-  "editor chrome bridge mints a pendingNodeId for id-less nodes without changing selector resolution (B5-5 bridge side)",
+  "editor chrome bridge reads React jsxDEV source provenance from the development Fiber stack",
   { timeout: 30_000 },
   async () => {
     const browser = await chromium.launch({ headless: true });
@@ -4680,62 +5540,83 @@ it(
         viewport: { width: 900, height: 700 },
       });
       page.on("pageerror", (err) => pageErrors.push(err.message));
-      // AI-generated-design shape: NO data-agent-native-node-id anywhere.
       await page.setContent(`<!doctype html>
 <html>
-  <head>
-    <style>
-      html, body { margin: 0; width: 100%; height: 100%; }
-      body { background: white; }
-      .target-box { position: absolute; left: 100px; top: 100px; width: 160px; height: 100px; background: #6366f1; }
-    </style>
-  </head>
-  <body>
-    <div class="target-box">Content</div>
-  </body>
+  <head><style>html,body{margin:0;width:100%;height:100%}h1{margin:80px;width:320px;height:60px}</style></head>
+  <body><h1 id="react-heading">How can I help?</h1></body>
 </html>`);
-      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.locator("#react-heading").evaluate((element) => {
+        Object.defineProperty(element, "__reactFiber$bridgeguard", {
+          configurable: true,
+          enumerable: true,
+          value: {
+            _debugStack: {
+              stack:
+                "Error\n    at ChatRoute (http://127.0.0.1:7331/app/routes/_index.tsx:78:35)",
+            },
+            return: null,
+          },
+        });
+      });
+      await page.addScriptTag({
+        content: hydratedEditorChromeBridgeScript(true),
+      });
       await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
       await collectBridgeMessages(page);
+      await page.waitForFunction(() =>
+        ((window as any).__bridgeMessages ?? []).some(
+          (message: any) =>
+            message.type === "agent-native:runtime-layer-snapshot",
+        ),
+      );
 
-      await page.mouse.click(180, 150);
-      await page.waitForTimeout(60);
-      await page.mouse.click(500, 500); // deselect (empty area)
-      await page.waitForTimeout(30);
-      await page.mouse.click(180, 150); // reselect — mint must be stable
-      await page.waitForTimeout(60);
-
-      const result = await page.evaluate(() => {
-        const selects = ((window as any).__bridgeMessages ?? []).filter(
-          (m: any) =>
-            m.type === "element-select" && m.payload?.tagName === "div",
+      const runtimeSnapshot = await page.evaluate(
+        () =>
+          ((window as any).__bridgeMessages ?? []).find(
+            (message: any) =>
+              message.type === "agent-native:runtime-layer-snapshot",
+          )?.payload,
+      );
+      expect(runtimeSnapshot.nodeCount).toBeGreaterThan(0);
+      expect(runtimeSnapshot.html).toContain("How can I help?");
+      expect(runtimeSnapshot.html).toContain(
+        'data-source-file="app/routes/_index.tsx"',
+      );
+      const runtimeIdentity = await page.evaluate((snapshotHtml) => {
+        const live = document.querySelector("#react-heading");
+        const snapshot = new DOMParser().parseFromString(
+          snapshotHtml,
+          "text/html",
         );
-        const box = document.querySelector<HTMLElement>(".target-box")!;
         return {
-          payloads: selects.map((m: any) => ({
-            pendingNodeId: m.payload.pendingNodeId,
-            selector: m.payload.selector,
-            sourceId: m.payload.sourceId,
-          })),
-          // The mint must NOT be written as a real node id (that would break
-          // the host's structural-selector fallback against source HTML).
-          realNodeIdAttr: box.getAttribute("data-agent-native-node-id"),
-          pendingAttr: box.getAttribute("data-an-pending-node-id"),
+          liveNodeId: live?.getAttribute("data-agent-native-node-id"),
+          snapshotNodeId: snapshot
+            .querySelector("#react-heading")
+            ?.getAttribute("data-agent-native-node-id"),
+          runtimeOnlyDescendants: snapshot.querySelectorAll(
+            "body *[data-an-runtime-layer-only]",
+          ).length,
         };
+      }, runtimeSnapshot.html);
+      expect(runtimeIdentity.liveNodeId).toMatch(/^runtime-/);
+      expect(runtimeIdentity.snapshotNodeId).toBe(runtimeIdentity.liveNodeId);
+      expect(runtimeIdentity.runtimeOnlyDescendants).toBe(0);
+
+      await page.mouse.click(160, 105);
+      await page.waitForTimeout(60);
+      const provenance = await page.evaluate(() => {
+        const selections = ((window as any).__bridgeMessages ?? []).filter(
+          (message: any) => message.type === "element-select",
+        );
+        return selections.at(-1)?.payload?.provenance ?? null;
       });
 
-      expect(result.payloads.length).toBeGreaterThanOrEqual(2);
-      const first = result.payloads[0];
-      const last = result.payloads[result.payloads.length - 1];
-      expect(first.pendingNodeId).toMatch(/^an-pending-/);
-      // Stable across re-selection (one mint per element).
-      expect(last.pendingNodeId).toBe(first.pendingNodeId);
-      // sourceId stays empty and the selector stays a structural fallback —
-      // resolution semantics are unchanged until the host persists the id.
-      expect(first.sourceId).toBe("");
-      expect(first.selector).toContain("target-box");
-      expect(result.realNodeIdAttr).toBeNull();
-      expect(result.pendingAttr).toBe(first.pendingNodeId);
+      expect(provenance).toEqual({
+        sourceFile: "app/routes/_index.tsx",
+        line: 78,
+        column: 35,
+        component: "ChatRoute",
+      });
       expect(pageErrors).toEqual([]);
     } finally {
       await browser.close();
@@ -4743,54 +5624,377 @@ it(
   },
 );
 
-// ── Template-clone reorder rejection + drop-on-leaf fix (DnD hardening) ────
-//
-// Two related fixes for the flow-reorder drag path:
-//
-// 1. An Alpine `<template x-for>` runtime clone has no counterpart in the
-//    static source HTML (only the single template child exists there), so a
-//    structural move targeting one can never resolve on the host — it used
-//    to optimistically reorder the live DOM then silently revert it with
-//    zero feedback. Reject up front instead (isTemplateCloneElement).
-// 2. isContainerDropTarget's flex/grid computed-display check alone can't
-//    tell a genuine layout container apart from an interactive leaf control
-//    (e.g. `<button style="display:flex">` used purely to align its own
-//    icon + label) — both LITERALLY have display:flex. hasOnlyLeafContent
-//    closes that gap by inspecting the element's own children.
-
 it(
-  "editor chrome bridge rejects reordering an Alpine x-for template clone with visible feedback and no DOM mutation",
+  "runtime layers qualify shared React shell identities by screen so hover and selection keep the correct route owner",
   { timeout: 30_000 },
   async () => {
     const browser = await chromium.launch({ headless: true });
     const pageErrors: string[] = [];
     try {
-      const page = await browser.newPage({
-        viewport: { width: 900, height: 700 },
-      });
-      page.on("pageerror", (err) => pageErrors.push(err.message));
-
-      // Alpine's runtime shape for `<template x-for>`: the <template> stays
-      // in the live DOM as a hidden marker, and every rendered instance is
-      // inserted as a DIRECT SIBLING of it, all still children of the same
-      // parent — `ul > template, li, li` — exactly mirroring what Alpine
-      // itself produces (no Alpine runtime needed to test the bridge's own
-      // detection, which only inspects DOM shape).
-      await page.setContent(`<!doctype html>
+      const screens = [
+        { id: "route-home", route: "/" },
+        { id: "route-settings", route: "/settings" },
+      ];
+      const runtimeScreens = await Promise.all(
+        screens.map(async (screen) => {
+          const page = await browser.newPage({
+            viewport: { width: 900, height: 700 },
+          });
+          page.on("pageerror", (error) =>
+            pageErrors.push(`${screen.route}: ${error.message}`),
+          );
+          await page.setContent(`<!doctype html>
 <html>
-  <head>
-    <style>
-      html, body { margin: 0; width: 100%; height: 100%; }
-      body { background: white; }
-      ul { position: absolute; left: 40px; top: 40px; width: 240px; display: flex; flex-direction: column; gap: 8px; list-style: none; padding: 0; margin: 0; }
-      li { display: flex; align-items: center; padding: 12px; border: 1px solid #ccc; background: #f5f5f5; height: 48px; box-sizing: border-box; }
-    </style>
-  </head>
-  <body>
-    <ul>
-      <template x-for="t in items"></template>
-      <li>Alpha</li>
-      <li>Beta</li>
+  <head><style>html,body{margin:0;width:100%;height:100%}h1{margin:80px;width:320px;height:60px}</style></head>
+  <body><h1 id="shared-shell-heading">Shared shell</h1></body>
+</html>`);
+          await page.locator("#shared-shell-heading").evaluate((element) => {
+            Object.defineProperty(element, "__reactFiber$sharedshell", {
+              configurable: true,
+              enumerable: true,
+              value: {
+                _debugStack: {
+                  stack:
+                    "Error\n    at AppShell (http://127.0.0.1:7331/app/components/AppShell.tsx:42:17)",
+                },
+                return: null,
+              },
+            });
+          });
+          await page.addScriptTag({
+            content: hydratedEditorChromeBridgeScript(true, screen.id),
+          });
+          await page.waitForSelector(
+            '[data-agent-native-edit-overlay="shield"]',
+          );
+          await collectBridgeMessages(page);
+          await page.waitForFunction(() =>
+            ((window as any).__bridgeMessages ?? []).some(
+              (message: any) =>
+                message.type === "agent-native:runtime-layer-snapshot",
+            ),
+          );
+          const snapshot = await page.evaluate(
+            () =>
+              ((window as any).__bridgeMessages ?? []).find(
+                (message: any) =>
+                  message.type === "agent-native:runtime-layer-snapshot",
+              )?.payload,
+          );
+          await page.mouse.move(160, 105);
+          await page.waitForTimeout(60);
+          await page.mouse.click(160, 105);
+          await page.waitForTimeout(60);
+          const messages = await readBridgeMessages(page);
+          const hover = messages.find(
+            (message) => message.type === "element-hover",
+          ) as { payload?: { sourceId?: string } } | undefined;
+          const selections = messages.filter(
+            (message) => message.type === "element-select",
+          ) as Array<{ payload?: { sourceId?: string } }>;
+          return {
+            ...screen,
+            snapshotHtml: snapshot.html as string,
+            nodeId: await page
+              .locator("#shared-shell-heading")
+              .getAttribute("data-agent-native-node-id"),
+            hoverSourceId: hover?.payload?.sourceId,
+            selectionSourceId:
+              selections[selections.length - 1]?.payload?.sourceId,
+          };
+        }),
+      );
+
+      const [home, settings] = runtimeScreens;
+      expect(home.nodeId).toMatch(/^runtime-/);
+      expect(settings.nodeId).toMatch(/^runtime-/);
+      expect(home.nodeId).not.toBe(settings.nodeId);
+      expect(home.hoverSourceId).toBe(home.nodeId);
+      expect(home.selectionSourceId).toBe(home.nodeId);
+      expect(settings.hoverSourceId).toBe(settings.nodeId);
+      expect(settings.selectionSourceId).toBe(settings.nodeId);
+
+      const owners = new Map<string, string>();
+      const projectedLayerIds = new Map<string, string>();
+      runtimeScreens.forEach((screen) => {
+        const projection = buildCodeLayerProjection(screen.snapshotHtml);
+        projection.nodes.forEach((node) => owners.set(node.id, screen.id));
+        const runtimeNode = projection.nodes.find(
+          (node) =>
+            node.dataAttributes["data-agent-native-node-id"] === screen.nodeId,
+        );
+        expect(runtimeNode).toBeDefined();
+        projectedLayerIds.set(screen.id, runtimeNode!.id);
+      });
+      expect(projectedLayerIds.get("route-home")).not.toBe(
+        projectedLayerIds.get("route-settings"),
+      );
+      expect(owners.get(projectedLayerIds.get("route-home")!)).toBe(
+        "route-home",
+      );
+      expect(owners.get(projectedLayerIds.get("route-settings")!)).toBe(
+        "route-settings",
+      );
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "runtime Layers ignores animation churn but refreshes semantic layout and tree mutations",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html><body><main id="app"><div id="animated">Card</div></main></body></html>`);
+      await collectBridgeMessages(page);
+      await page.addScriptTag({
+        content: hydratedEditorChromeBridgeScript(true),
+      });
+      await page.waitForFunction(
+        () =>
+          ((window as any).__bridgeMessages ?? []).filter(
+            (message: any) =>
+              message.type === "agent-native:runtime-layer-snapshot",
+          ).length === 1,
+      );
+
+      // These are typical animation/runtime-state writes. Neither changes the
+      // hierarchy, layer name, or container classification, so a large burst
+      // must stay inside the initial one-snapshot budget.
+      await page.locator("#animated").evaluate((element) => {
+        const html = element as HTMLElement;
+        for (let index = 0; index < 250; index += 1) {
+          html.style.transform = `translateX(${index}px)`;
+          html.style.opacity = String((index % 100) / 100);
+          html.setAttribute("class", `motion-frame-${index}`);
+        }
+        const transientChrome = document.createElement("div");
+        transientChrome.setAttribute(
+          "data-agent-native-edit-overlay",
+          "transient-test",
+        );
+        document.body.appendChild(transientChrome);
+        transientChrome.remove();
+      });
+      await page.waitForTimeout(350);
+      expect(
+        await page.evaluate(
+          () =>
+            ((window as any).__bridgeMessages ?? []).filter(
+              (message: any) =>
+                message.type === "agent-native:runtime-layer-snapshot",
+            ).length,
+        ),
+      ).toBe(1);
+
+      // Continuous text/child churn used to serialize the full DOM every
+      // 200ms forever. During a one-second stream the trailing debounce must
+      // not post at all; once the stream settles, Layers receives one latest
+      // snapshot (the 1.5s max-wait still bounds truly endless streams).
+      await page.locator("#animated").evaluate(async (element) => {
+        for (let index = 0; index < 20; index += 1) {
+          element.textContent = `Streaming card ${index}`;
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+      });
+      expect(
+        await page.evaluate(
+          () =>
+            ((window as any).__bridgeMessages ?? []).filter(
+              (message: any) =>
+                message.type === "agent-native:runtime-layer-snapshot",
+            ).length,
+        ),
+      ).toBe(1);
+      await page.waitForFunction(
+        () =>
+          ((window as any).__bridgeMessages ?? []).filter(
+            (message: any) =>
+              message.type === "agent-native:runtime-layer-snapshot",
+          ).length === 2,
+      );
+
+      // A flex utility changes the Layers icon/layout contract and must still
+      // refresh exactly once after the observer's coalescing window.
+      await page.locator("#animated").evaluate((element) => {
+        element.setAttribute("class", "motion-frame flex");
+      });
+      await page.waitForFunction(
+        () =>
+          ((window as any).__bridgeMessages ?? []).filter(
+            (message: any) =>
+              message.type === "agent-native:runtime-layer-snapshot",
+          ).length === 3,
+      );
+      const semanticHtml = await page.evaluate(() => {
+        const snapshots = ((window as any).__bridgeMessages ?? []).filter(
+          (message: any) =>
+            message.type === "agent-native:runtime-layer-snapshot",
+        );
+        return snapshots.at(-1)?.payload?.html ?? "";
+      });
+      expect(semanticHtml).toContain('class="motion-frame flex"');
+
+      // Dynamic text and child hierarchy remain live in Layers.
+      await page.locator("#animated").evaluate((element) => {
+        element.textContent = "Updated card";
+        element.appendChild(document.createElement("button")).textContent =
+          "Open";
+      });
+      await page.waitForFunction(
+        () =>
+          ((window as any).__bridgeMessages ?? []).filter(
+            (message: any) =>
+              message.type === "agent-native:runtime-layer-snapshot",
+          ).length === 4,
+      );
+      const treeHtml = await page.evaluate(() => {
+        const snapshots = ((window as any).__bridgeMessages ?? []).filter(
+          (message: any) =>
+            message.type === "agent-native:runtime-layer-snapshot",
+        );
+        return snapshots.at(-1)?.payload?.html ?? "";
+      });
+      expect(treeHtml).toContain("Updated card");
+      expect(treeHtml).toContain("<button");
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "editor chrome bridge mints a pendingNodeId for id-less nodes without changing selector resolution (B5-5 bridge side)",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      // AI-generated-design shape: NO data-agent-native-node-id anywhere.
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { background: white; }
+      .target-box { position: absolute; left: 100px; top: 100px; width: 160px; height: 100px; background: #6366f1; }
+    </style>
+  </head>
+  <body>
+    <div class="target-box">Content</div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      await page.mouse.click(180, 150);
+      await page.waitForTimeout(60);
+      await page.mouse.click(500, 500); // deselect (empty area)
+      await page.waitForTimeout(30);
+      await page.mouse.click(180, 150); // reselect — mint must be stable
+      await page.waitForTimeout(60);
+
+      const result = await page.evaluate(() => {
+        const selects = ((window as any).__bridgeMessages ?? []).filter(
+          (m: any) =>
+            m.type === "element-select" && m.payload?.tagName === "div",
+        );
+        const box = document.querySelector<HTMLElement>(".target-box")!;
+        return {
+          payloads: selects.map((m: any) => ({
+            pendingNodeId: m.payload.pendingNodeId,
+            selector: m.payload.selector,
+            sourceId: m.payload.sourceId,
+          })),
+          // The mint must NOT be written as a real node id (that would break
+          // the host's structural-selector fallback against source HTML).
+          realNodeIdAttr: box.getAttribute("data-agent-native-node-id"),
+          pendingAttr: box.getAttribute("data-an-pending-node-id"),
+        };
+      });
+
+      expect(result.payloads.length).toBeGreaterThanOrEqual(2);
+      const first = result.payloads[0];
+      const last = result.payloads[result.payloads.length - 1];
+      expect(first.pendingNodeId).toMatch(/^an-pending-/);
+      // Stable across re-selection (one mint per element).
+      expect(last.pendingNodeId).toBe(first.pendingNodeId);
+      // sourceId stays empty and the selector stays a structural fallback —
+      // resolution semantics are unchanged until the host persists the id.
+      expect(first.sourceId).toBe("");
+      expect(first.selector).toContain("target-box");
+      expect(result.realNodeIdAttr).toBeNull();
+      expect(result.pendingAttr).toBe(first.pendingNodeId);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── Template-clone reorder rejection + drop-on-leaf fix (DnD hardening) ────
+//
+// Two related fixes for the flow-reorder drag path:
+//
+// 1. An Alpine `<template x-for>` runtime clone has no counterpart in the
+//    static source HTML (only the single template child exists there), so a
+//    structural move targeting one can never resolve on the host — it used
+//    to optimistically reorder the live DOM then silently revert it with
+//    zero feedback. Reject up front instead (isTemplateCloneElement).
+// 2. isContainerDropTarget's flex/grid computed-display check alone can't
+//    tell a genuine layout container apart from an interactive leaf control
+//    (e.g. `<button style="display:flex">` used purely to align its own
+//    icon + label) — both LITERALLY have display:flex. hasOnlyLeafContent
+//    closes that gap by inspecting the element's own children.
+
+it(
+  "editor chrome bridge rejects reordering an Alpine x-for template clone with visible feedback and no DOM mutation",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+
+      // Alpine's runtime shape for `<template x-for>`: the <template> stays
+      // in the live DOM as a hidden marker, and every rendered instance is
+      // inserted as a DIRECT SIBLING of it, all still children of the same
+      // parent — `ul > template, li, li` — exactly mirroring what Alpine
+      // itself produces (no Alpine runtime needed to test the bridge's own
+      // detection, which only inspects DOM shape).
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { background: white; }
+      ul { position: absolute; left: 40px; top: 40px; width: 240px; display: flex; flex-direction: column; gap: 8px; list-style: none; padding: 0; margin: 0; }
+      li { display: flex; align-items: center; padding: 12px; border: 1px solid #ccc; background: #f5f5f5; height: 48px; box-sizing: border-box; }
+    </style>
+  </head>
+  <body>
+    <ul>
+      <template x-for="t in items"></template>
+      <li>Alpha</li>
+      <li>Beta</li>
     </ul>
   </body>
 </html>`);
@@ -4886,7 +6090,7 @@ it(
 );
 
 it(
-  "editor chrome bridge still reorders a normal (non-template) flow child normally, unaffected by the template-clone rejection",
+  "editor chrome bridge rejects text-editing an Alpine x-for template clone with visible feedback and no contenteditable mutation",
   { timeout: 30_000 },
   async () => {
     const browser = await chromium.launch({ headless: true });
@@ -4897,6 +6101,14 @@ it(
       });
       page.on("pageerror", (err) => pageErrors.push(err.message));
 
+      // Same clone shape as the reorder-rejection test above, but the clone
+      // items here are plain-text `<li>`s — exactly the shape that used to
+      // pass findTextEditTarget's "only inline-editable descendants" check
+      // and enter contenteditable mode on the raw clone, an edit that could
+      // never resolve on commit (no per-instance source node exists for a
+      // clone — only the single `<template>` does). The `<ul>` carries its
+      // own stable id so the rejection fallback (select nearest source-
+      // backed ancestor) has something real to land on.
       await page.setContent(`<!doctype html>
 <html>
   <head>
@@ -4908,48 +6120,149 @@ it(
     </style>
   </head>
   <body>
-    <ul>
-      <li data-agent-native-node-id="itemA">Alpha</li>
-      <li data-agent-native-node-id="itemB">Beta</li>
+    <ul data-agent-native-node-id="list">
+      <template x-for="t in items"></template>
+      <li>Alpha</li>
+      <li>Beta</li>
     </ul>
   </body>
 </html>`);
-      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.addScriptTag({
+        content: hydratedEditorChromeBridgeScriptWithTextEditing(),
+      });
       await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
       await collectBridgeMessages(page);
 
-      const itemABox = (await page
-        .locator('[data-agent-native-node-id="itemA"]')
-        .boundingBox())!;
-      const itemBBox = (await page
-        .locator('[data-agent-native-node-id="itemB"]')
-        .boundingBox())!;
-      const startX = itemABox.x + itemABox.width / 2;
-      const startY = itemABox.y + itemABox.height / 2;
+      const itemABox = (await page.locator("li").first().boundingBox())!;
+      const dblclickX = itemABox.x + itemABox.width / 2;
+      const dblclickY = itemABox.y + itemABox.height / 2;
 
-      await page.mouse.click(startX, startY);
-      await page.waitForFunction(() => {
-        const overlay = document.querySelector<HTMLElement>(
+      await page.mouse.dblclick(dblclickX, dblclickY);
+      await page.waitForTimeout(80);
+
+      const state = await page.evaluate(() => {
+        const items = Array.from(document.querySelectorAll("li"));
+        const badge = document.querySelector<HTMLElement>(
+          "[data-agent-native-transform-badge]",
+        );
+        const selection = document.querySelector<HTMLElement>(
           '[data-agent-native-edit-overlay="selection"]',
         );
-        return overlay && window.getComputedStyle(overlay).display === "block";
+        const list = document.querySelector<HTMLElement>("ul")!;
+        return {
+          anyContentEditable: items.some(
+            (el) => el.getAttribute("contenteditable") === "true",
+          ),
+          anyTextEditingActive: !!document.querySelector(
+            "[data-agent-native-text-editing]",
+          ),
+          badgeText:
+            badge && window.getComputedStyle(badge).display !== "none"
+              ? badge.textContent
+              : null,
+          selectionMatchesList:
+            !!selection &&
+            window.getComputedStyle(selection).display === "block" &&
+            Math.abs(
+              selection.getBoundingClientRect().left -
+                list.getBoundingClientRect().left,
+            ) < 1,
+        };
       });
 
-      await page.mouse.move(startX, startY);
-      await page.mouse.down();
-      await page.mouse.move(startX - 5, startY - 5, { steps: 3 });
-      const targetY = itemBBox.y + itemBBox.height - 5;
-      await page.mouse.move(startX, targetY, { steps: 10 });
-      await page.waitForTimeout(80);
+      // No clone was put into edit mode, and no orphaned in-progress session.
+      expect(state.anyContentEditable).toBe(false);
+      expect(state.anyTextEditingActive).toBe(false);
+      // Clear rejection feedback, same contract as the reorder rejection.
+      expect(state.badgeText).toMatch(/can.t edit/i);
+      // Falls back to selecting the nearest source-backed ancestor (the
+      // list container) instead of leaving a stale/no selection.
+      expect(state.selectionMatchesList).toBe(true);
 
-      const guideVisible = await page.evaluate(() => {
-        const guide = document.querySelector<HTMLElement>(
-          "[data-agent-native-insertion-guide]",
-        );
-        return guide
-          ? window.getComputedStyle(guide).display === "block"
-          : false;
-      });
+      // Never posts a doomed text-content-change for the clone.
+      const messages = await readBridgeMessages(page);
+      expect(messages.some((m) => m.type === "text-content-change")).toBe(
+        false,
+      );
+      // Source text is completely untouched.
+      const order = await page.evaluate(() =>
+        Array.from(document.querySelectorAll("li")).map((el) =>
+          el.textContent?.trim(),
+        ),
+      );
+      expect(order).toEqual(["Alpha", "Beta"]);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "editor chrome bridge still reorders a normal (non-template) flow child normally, unaffected by the template-clone rejection",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      body { background: white; }
+      ul { position: absolute; left: 40px; top: 40px; width: 240px; display: flex; flex-direction: column; gap: 8px; list-style: none; padding: 0; margin: 0; }
+      li { display: flex; align-items: center; padding: 12px; border: 1px solid #ccc; background: #f5f5f5; height: 48px; box-sizing: border-box; }
+    </style>
+  </head>
+  <body>
+    <ul>
+      <li data-agent-native-node-id="itemA">Alpha</li>
+      <li data-agent-native-node-id="itemB">Beta</li>
+    </ul>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      const itemABox = (await page
+        .locator('[data-agent-native-node-id="itemA"]')
+        .boundingBox())!;
+      const itemBBox = (await page
+        .locator('[data-agent-native-node-id="itemB"]')
+        .boundingBox())!;
+      const startX = itemABox.x + itemABox.width / 2;
+      const startY = itemABox.y + itemABox.height / 2;
+
+      await page.mouse.click(startX, startY);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+
+      await page.mouse.move(startX, startY);
+      await page.mouse.down();
+      await page.mouse.move(startX - 5, startY - 5, { steps: 3 });
+      const targetY = itemBBox.y + itemBBox.height - 5;
+      await page.mouse.move(startX, targetY, { steps: 10 });
+      await page.waitForTimeout(80);
+
+      const guideVisible = await page.evaluate(() => {
+        const guide = document.querySelector<HTMLElement>(
+          "[data-agent-native-insertion-guide]",
+        );
+        return guide
+          ? window.getComputedStyle(guide).display === "block"
+          : false;
+      });
       expect(guideVisible).toBe(true);
 
       await page.mouse.up();
@@ -5658,13 +6971,18 @@ it(
         return {
           draggedParentId: dragged.parentElement?.id,
           position: dragged.style.position,
+          positionPriority: dragged.style.getPropertyPriority("position"),
         };
       });
 
       // Correct target: reparented INTO #row, not as a sibling inside <main>.
       expect(result.draggedParentId).toBe("row");
-      // Absolute-into-flow strip still applies on the correct target.
-      expect(result.position).toBe("");
+      // Absolute-into-flow cleanup still applies on the correct target. This
+      // fixture supplies position:absolute from an authored stylesheet rather
+      // than inline style, so the bridge adds a temporary static override to
+      // prevent a one-frame absolute flash before the host's source round-trip.
+      expect(result.position).toBe("static");
+      expect(result.positionPriority).toBe("important");
 
       const messages = await readBridgeMessages(page);
       const structureMessage = messages.find(
@@ -5672,6 +6990,7 @@ it(
       ) as any;
       expect(structureMessage).toBeTruthy();
       expect(structureMessage.dropMode).toBe("flow-insert");
+      expect(structureMessage.forceFlowPositionOverride).toBe(true);
       // The anchor must identify #row (via its stable node id), never <main>.
       expect(structureMessage.anchorSourceId).toBe("row");
       expect(structureMessage.anchorSelector).toContain("row");
@@ -5814,6 +7133,183 @@ it(
   },
 );
 
+it(
+  "applies host-driven runtime layer moves by unique source ids and rolls rejected moves back",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      #origin { position: absolute; left: 20px; top: 300px; }
+      #anchor { display: flex; flex-direction: column; gap: 8px; }
+    </style>
+  </head>
+  <body>
+    <div id="origin">
+      <div class="repeated" data-agent-native-node-id="runtime-subject" style="position:absolute;left:40px;top:30px">Subject</div>
+      <span id="sibling">Sibling</span>
+    </div>
+    <section id="anchor" class="repeated" data-agent-native-node-id="runtime-anchor"></section>
+  </body>
+</html>`);
+      await page.locator("#origin .repeated").evaluate((element) => {
+        Object.defineProperty(element, "__reactFiber$runtimemovesubject", {
+          configurable: true,
+          enumerable: true,
+          value: {
+            _debugStack: {
+              stack:
+                "Error\n    at ComposerButton (http://127.0.0.1:7331/app/components/ComposerButton.tsx:18:5)",
+            },
+            return: null,
+          },
+        });
+      });
+      await page.locator("#anchor").evaluate((element) => {
+        Object.defineProperty(element, "__reactFiber$runtimemoveanchor", {
+          configurable: true,
+          enumerable: true,
+          value: {
+            _debugStack: {
+              stack:
+                "Error\n    at ComposerActions (http://127.0.0.1:7331/app/components/ComposerActions.tsx:31:3)",
+            },
+            return: null,
+          },
+        });
+      });
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      const before = await page.evaluate(() => {
+        const subject = document.querySelector<HTMLElement>(
+          '[data-agent-native-node-id="runtime-subject"]',
+        )!;
+        return {
+          parentId: subject.parentElement?.id,
+          nextSiblingId: subject.nextElementSibling?.id,
+          position: subject.style.position,
+          left: subject.style.left,
+          top: subject.style.top,
+        };
+      });
+      await page.evaluate(() => {
+        window.postMessage(
+          {
+            type: "runtime-structure-move",
+            subjectSelector: ".repeated",
+            subjectSourceId: "runtime-subject",
+            anchorSelector: ".repeated",
+            anchorSourceId: "runtime-anchor",
+            placement: "inside",
+          },
+          "*",
+        );
+      });
+      await page.waitForFunction(() =>
+        ((window as any).__bridgeMessages ?? []).some(
+          (message: any) => message.type === "visual-structure-change",
+        ),
+      );
+
+      const optimistic = await page.evaluate(() => {
+        const subject = document.querySelector<HTMLElement>(
+          '[data-agent-native-node-id="runtime-subject"]',
+        )!;
+        return {
+          parentId: subject.parentElement?.id,
+          position: subject.style.position,
+        };
+      });
+      expect(optimistic).toEqual({ parentId: "anchor", position: "" });
+
+      const messages = await readBridgeMessages(page);
+      const structureMessage = messages.find(
+        (message) => message.type === "visual-structure-change",
+      ) as any;
+      expect(structureMessage).toMatchObject({
+        sourceId: "runtime-subject",
+        anchorSourceId: "runtime-anchor",
+        placement: "inside",
+        dropMode: "flow-insert",
+        payload: {
+          provenance: {
+            sourceFile: "app/components/ComposerButton.tsx",
+            line: 18,
+            column: 5,
+            component: "ComposerButton",
+          },
+        },
+        anchorPayload: {
+          provenance: {
+            sourceFile: "app/components/ComposerActions.tsx",
+            line: 31,
+            column: 3,
+            component: "ComposerActions",
+          },
+        },
+      });
+
+      await page.evaluate((requestId: string) => {
+        window.postMessage(
+          {
+            type: "visual-structure-ack",
+            requestId,
+            applied: false,
+          },
+          "*",
+        );
+      }, structureMessage.requestId);
+      await page.waitForTimeout(30);
+
+      const after = await page.evaluate(() => {
+        const subject = document.querySelector<HTMLElement>(
+          '[data-agent-native-node-id="runtime-subject"]',
+        )!;
+        return {
+          parentId: subject.parentElement?.id,
+          nextSiblingId: subject.nextElementSibling?.id,
+          position: subject.style.position,
+          left: subject.style.left,
+          top: subject.style.top,
+        };
+      });
+      expect(after).toEqual(before);
+
+      await page.evaluate(() => {
+        window.postMessage(
+          {
+            type: "runtime-structure-move",
+            subjectSelector: ".repeated",
+            anchorSelector: ".repeated",
+            placement: "inside",
+          },
+          "*",
+        );
+      });
+      await page.waitForTimeout(30);
+      expect(
+        (await readBridgeMessages(page)).filter(
+          (message) => message.type === "visual-structure-change",
+        ),
+      ).toHaveLength(1);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
 // ── Template-clone ANCHOR resolution (drop INTO a clones-only container) ───
 //
 // Companion to the "template-clone reorder rejection" fix above, which only
@@ -6109,6 +7605,55 @@ it(
   },
 );
 
+it(
+  "hit-test bridge recognizes a plain absolute frame as a container",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      await page.setContent(`<!doctype html><html><body style="margin:0">
+        <div id="frame" data-agent-native-node-id="frame" data-an-primitive="frame" style="position:absolute;left:300px;top:180px;width:220px;height:160px"></div>
+      </body></html>`);
+      await page.addScriptTag({ content: hydratedHitTestBridgeScript() });
+
+      const reply = (await page.evaluate(
+        () =>
+          new Promise((resolve) => {
+            const onMessage = (event: MessageEvent) => {
+              if (event.data?.type !== "agent-native:hit-test-result") return;
+              window.removeEventListener("message", onMessage);
+              resolve(event.data);
+            };
+            window.addEventListener("message", onMessage);
+            window.postMessage(
+              {
+                type: "agent-native:hit-test",
+                correlationId: "frame-container",
+                x: 410,
+                y: 260,
+                preview: false,
+              },
+              "*",
+            );
+          }),
+      )) as {
+        anchorNodeId: string;
+        placement: string;
+        dropMode: string;
+      };
+
+      expect(reply.anchorNodeId).toBe("frame");
+      expect(reply.placement).toBe("inside");
+      expect(reply.dropMode).toBe("absolute-container");
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
 it(
   "hit-test bridge prefers the nearest NON-clone static sibling as anchor when a container mixes clone and static children",
   { timeout: 30_000 },
@@ -6180,3 +7725,1000 @@ it(
     }
   },
 );
+
+// ── Hover-info postMessage de-duplication (perf) ────────────────────────────
+//
+it(
+  "editor chrome bridge flow-inserts grid children and CSS grid tracks reflow when the parent resizes",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html><head><style>
+  html, body { margin: 0; width: 100%; height: 100%; }
+  #grid { position:absolute; left:100px; top:80px; width:400px; display:grid;
+    grid-template-columns:repeat(2,minmax(0,1fr)); grid-template-rows:repeat(2,80px);
+    column-gap:20px; row-gap:16px; padding:12px; }
+  .cell { background:#a5b4fc; }
+</style></head><body>
+  <div id="grid" data-agent-native-node-id="grid">
+    <div class="cell" id="cellA" data-agent-native-node-id="a">A</div>
+    <div class="cell" id="cellB" data-agent-native-node-id="b">B</div>
+    <div class="cell" id="cellC" data-agent-native-node-id="c">C</div>
+    <div class="cell" id="cellD" data-agent-native-node-id="d">D</div>
+  </div>
+</body></html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      const widthsBefore = await page.evaluate(() =>
+        Array.from(document.querySelectorAll<HTMLElement>("#grid > .cell")).map(
+          (element) => element.getBoundingClientRect().width,
+        ),
+      );
+      await page.evaluate(() => {
+        document.querySelector<HTMLElement>("#grid")!.style.width = "600px";
+      });
+      const widthsAfter = await page.evaluate(() =>
+        Array.from(document.querySelectorAll<HTMLElement>("#grid > .cell")).map(
+          (element) => element.getBoundingClientRect().width,
+        ),
+      );
+      expect(widthsAfter[0]).toBeGreaterThan(widthsBefore[0]);
+      expect(widthsAfter[0]).toBeCloseTo(widthsAfter[1], 5);
+
+      // Move D into the first-row column gap. The bridge must use a flow
+      // insertion slot, then native CSS Grid performs the child reflow.
+      await page.mouse.click(570, 236);
+      await page.mouse.move(570, 236);
+      await page.mouse.down();
+      await page.mouse.move(562, 228, { steps: 2 });
+      await page.mouse.move(400, 120, { steps: 6 });
+      await page.waitForTimeout(50);
+      await page.mouse.up();
+      await page.waitForTimeout(50);
+
+      const order = await page.evaluate(() =>
+        Array.from(document.querySelectorAll<HTMLElement>("#grid > .cell")).map(
+          (element) => element.id,
+        ),
+      );
+      expect(order).not.toEqual(["cellA", "cellB", "cellC", "cellD"]);
+      const structureMessages = (await readBridgeMessages(page)).filter(
+        (message) => message.type === "visual-structure-change",
+      ) as Array<{ dropMode?: string }>;
+      expect(structureMessages[structureMessages.length - 1]?.dropMode).toBe(
+        "flow-insert",
+      );
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// The shield's pointermove handler used to call getLightElementInfo (two
+// getComputedStyle reads) and post a fresh "element-hover" message on EVERY
+// raw pointermove tick, even when the hit-tested element hadn't changed since
+// the previous tick — dozens to hundreds of wasted calls for a pointer that
+// simply rests inside one element for a second or two. Fixed by gating the
+// info-compute + post on hoveredEl actually changing since the last post.
+
+it(
+  "editor chrome bridge posts element-hover only when the hovered element actually changes, not on every raw pointermove",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      #box { position: absolute; left: 100px; top: 100px; width: 200px; height: 150px; background: #6366f1; }
+    </style>
+  </head>
+  <body>
+    <div id="box" data-agent-native-node-id="box"></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      // Several raw pointermove ticks that all stay inside #box — simulates
+      // a slow, jittery real-mouse hover over one unchanged element.
+      await page.mouse.move(150, 150);
+      await page.mouse.move(152, 151);
+      await page.mouse.move(154, 153);
+      await page.mouse.move(151, 155);
+      await page.mouse.move(153, 152);
+      await page.waitForTimeout(50);
+
+      const hoverMessages = (await readBridgeMessages(page)).filter(
+        (m) => m.type === "element-hover",
+      );
+      expect(hoverMessages.length).toBe(1);
+
+      // Moving onto <body> background (a genuinely different hoveredEl —
+      // there's no "off the iframe" in this single-document harness) posts
+      // one more; moving back onto #box posts one more again. Three distinct
+      // hoveredEl values across the whole gesture, three posts total — never
+      // one post per raw pointermove tick (5 ticks landed on #box above, 1
+      // message; if the old unthrottled behavior were still in place this
+      // would be 5 + 1 + 1 = 7, not 3).
+      await page.mouse.move(500, 500);
+      await page.waitForTimeout(30);
+      await page.mouse.move(150, 150);
+      await page.mouse.move(152, 151);
+      await page.waitForTimeout(30);
+
+      const hoverMessagesAfter = (await readBridgeMessages(page)).filter(
+        (m) => m.type === "element-hover",
+      );
+      expect(hoverMessagesAfter.length).toBe(3);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "editor chrome bridge re-posts element-hover for the SAME element after a real pointerleave off the shield (regression: gate must re-arm on pointer-leaves-iframe, not just on hovering a different element)",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      #box { position: absolute; left: 100px; top: 100px; width: 200px; height: 150px; background: #6366f1; }
+    </style>
+  </head>
+  <body>
+    <div id="box" data-agent-native-node-id="box"></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      // 1) Hover the box — one "element-hover" post.
+      await page.mouse.move(150, 150);
+      await page.waitForTimeout(30);
+      const afterHover = (await readBridgeMessages(page)).filter(
+        (m) => m.type === "element-hover",
+      );
+      expect(afterHover.length).toBe(1);
+
+      // 2) The cursor leaves the iframe content entirely (to a host panel,
+      // or outside the browser window) without landing on any other
+      // in-document element first. There's no "off the iframe" to move the
+      // mouse to in this single-document harness, so — exactly like the
+      // live repro — dispatch a real `pointerleave` on the shield element
+      // directly. This must post "element-hover: null" AND re-arm the gate.
+      await page.evaluate(() => {
+        const shield = document.querySelector(
+          '[data-agent-native-edit-overlay="shield"]',
+        );
+        shield?.dispatchEvent(
+          new PointerEvent("pointerleave", {
+            bubbles: false,
+            cancelable: true,
+            clientX: 150,
+            clientY: 150,
+          }),
+        );
+      });
+      await page.waitForTimeout(30);
+      const afterLeave = (await readBridgeMessages(page)).filter(
+        (m) => m.type === "element-hover",
+      );
+      expect(afterLeave.length).toBe(2);
+      expect(afterLeave[1].payload).toBeNull();
+
+      // 3) The pointer comes back to the SAME element (#box). Before the
+      // fix, lastHoverInfoPostedEl still held #box from step 1, so this
+      // pointermove's `hoveredEl !== lastHoverInfoPostedEl` gate check was
+      // false and the bridge silently skipped posting — the host's hover
+      // highlight stayed stuck at "nothing" forever, since only a hover onto
+      // a genuinely different element would ever unstick it.
+      await page.mouse.move(152, 151);
+      await page.waitForTimeout(30);
+      const afterReturn = (await readBridgeMessages(page)).filter(
+        (m) => m.type === "element-hover",
+      );
+      expect(afterReturn.length).toBe(3);
+      expect(afterReturn[2].payload).not.toBeNull();
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── Cross-screen-drag "move" phase rAF coalescing (perf) ────────────────────
+//
+// postCrossScreenDrag("move", ...) used to post once per raw mousemove tick
+// during a free-position drag — a getBoundingClientRect plus a structured-
+// clone postMessage on every event, unthrottled, for the whole gesture. A
+// synchronous burst of raw events within one frame (a fast mouse/trackpad, or
+// a script driving many DOM mousemove dispatches back to back) must now
+// collapse to a single postMessage per animation frame, carrying the LATEST
+// position — not the first tick's stale one — and no coalesced tick may ever
+// fire after the gesture's own "cancel"/"end" phase already posted.
+
+it(
+  "editor chrome bridge coalesces cross-screen-drag move-phase posts to one per frame, with the latest position",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      #target { position: absolute; left: 100px; top: 100px; width: 120px; height: 80px; background: #6366f1; }
+    </style>
+  </head>
+  <body>
+    <div id="target" data-agent-native-node-id="target"></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      // Capture the iframe-to-host calls synchronously. Listening for the
+      // same-window `message` event introduces a second, unrelated scheduler:
+      // postMessage delivery is a queued task and is not guaranteed to run
+      // before the next animation frame (especially under loaded CI). This
+      // test is about how often the bridge CALLS postMessage per frame.
+      await page.evaluate(() => {
+        (window as any).__bridgeMessages = [];
+        window.postMessage = ((message: unknown) => {
+          (window as any).__bridgeMessages.push(message);
+        }) as typeof window.postMessage;
+      });
+
+      await page.mouse.click(160, 140);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+      await page.mouse.move(160, 140);
+      await page.mouse.down();
+      // Cross the drag threshold with a real move first. The shield arms the
+      // gesture from a "pointerdown" listener (shieldOverlay.addEventListener
+      // ("pointerdown", beginPotentialShieldDrag, ...)), so dragEventNames(e)
+      // resolves to {move:"pointermove", up:"pointerup"} for the whole
+      // gesture — the burst below must dispatch that same event type, not
+      // "mousemove"/"mouseup", or the document-level listener never sees it.
+      await page.mouse.move(170, 150);
+
+      const moveMessageCount = await page.evaluate(async () => {
+        // Synchronous burst: 20 raw pointermove events with the position
+        // advancing between each, none of which yield to a frame in between —
+        // exactly what a fast mouse/trackpad's event queue looks like within
+        // one frame budget.
+        for (let i = 0; i < 20; i++) {
+          document.dispatchEvent(
+            new PointerEvent("pointermove", {
+              bubbles: true,
+              cancelable: true,
+              clientX: 170 + i,
+              clientY: 150 + i,
+            }),
+          );
+        }
+        await new Promise((r) => requestAnimationFrame(() => r(null)));
+        await new Promise((r) => requestAnimationFrame(() => r(null)));
+        const messages = (window as any).__bridgeMessages as Array<
+          Record<string, unknown>
+        >;
+        return messages.filter(
+          (m) =>
+            m.type === "agent-native:cross-screen-drag" && m.phase === "move",
+        ).length;
+      });
+      // 20 raw events synchronously dispatched within one frame → coalesced
+      // to exactly one "move" post, not 20.
+      expect(moveMessageCount).toBe(1);
+
+      const lastMoveMessage = await page.evaluate(() => {
+        const messages = (window as any).__bridgeMessages as Array<
+          Record<string, unknown>
+        >;
+        const moves = messages.filter(
+          (m) =>
+            m.type === "agent-native:cross-screen-drag" && m.phase === "move",
+        );
+        return moves[moves.length - 1] as { iframeX: number; iframeY: number };
+      });
+      // Carries the LAST dispatched position (170+19, 150+19), not the first.
+      expect(lastMoveMessage.iframeX).toBe(189);
+      expect(lastMoveMessage.iframeY).toBe(169);
+
+      // Schedule one more tick, then release in the SAME synchronous task
+      // (both dispatched in-page, back to back, with no `await` between them
+      // so no animation frame can possibly run in between) — cleanupMoveDrag
+      // must cancel the still-pending tick so no stale "move" can post after
+      // "end". Using page.mouse.up() here instead would reintroduce exactly
+      // the real-IPC-timing race this synchronous dispatch avoids.
+      await page.evaluate(() => {
+        document.dispatchEvent(
+          new PointerEvent("pointermove", {
+            bubbles: true,
+            cancelable: true,
+            clientX: 400,
+            clientY: 400,
+          }),
+        );
+        document.dispatchEvent(
+          new PointerEvent("pointerup", {
+            bubbles: true,
+            cancelable: true,
+            clientX: 400,
+            clientY: 400,
+          }),
+        );
+      });
+      await new Promise((r) => setTimeout(r, 60));
+
+      const postReleaseCounts = await page.evaluate(() => {
+        const messages = (window as any).__bridgeMessages as Array<
+          Record<string, unknown>
+        >;
+        const crossScreen = messages.filter(
+          (m) => m.type === "agent-native:cross-screen-drag",
+        );
+        return {
+          move: crossScreen.filter((m) => m.phase === "move").length,
+          end: crossScreen.filter((m) => m.phase === "end").length,
+          lastPhase: crossScreen[crossScreen.length - 1]?.phase,
+        };
+      });
+      // Still exactly one "move" (the pending tick from right before mouseup
+      // was cancelled, never posted after release).
+      expect(postReleaseCounts.move).toBe(1);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── Selection overlay tracks CSS transitions/animations ─────────────────────
+//
+// ResizeObserver (the existing overlay-sync mechanism) only fires on
+// border-box SIZE changes, so a purely transform-driven transition/animation
+// on the selected element — extremely common for hover/toggle states in
+// generated prototypes — never triggered a re-sync. The one-shot
+// MutationObserver callback that fires when the triggering class/style
+// changes reads the element's rect at essentially the START of the
+// transition, so the overlay used to freeze there for the whole transition
+// duration instead of following the element to its final position.
+
+it(
+  "editor chrome bridge keeps the selection overlay tracking an element through a transform transition, not just its start/end rect",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      #target {
+        position: absolute; left: 40px; top: 40px; width: 100px; height: 60px;
+        background: #6366f1;
+        transition: transform 400ms linear;
+      }
+      #target.moved { transform: translateX(300px); }
+    </style>
+  </head>
+  <body>
+    <div id="target" data-agent-native-node-id="target"></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+
+      await page.mouse.click(90, 70);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+
+      // Start the transition, then sample the overlay vs. the element's live
+      // rect partway through — both read in the SAME evaluate call so the
+      // comparison isn't skewed by round-trip timing.
+      await page.evaluate(() => {
+        document.getElementById("target")!.classList.add("moved");
+      });
+      await page.waitForTimeout(200); // ~midpoint of the 400ms transition
+
+      const midTransition = await page.evaluate(() => {
+        const target = document.getElementById("target")!;
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        )!;
+        return {
+          targetLeft: target.getBoundingClientRect().left,
+          overlayLeft: overlay.getBoundingClientRect().left,
+        };
+      });
+      // Element should be roughly mid-flight (well past its start position,
+      // not yet at its end position) — sanity-checks the transition is
+      // actually running under this browser/headless timing before we
+      // assert anything about overlay tracking.
+      expect(midTransition.targetLeft).toBeGreaterThan(60);
+      expect(midTransition.targetLeft).toBeLessThan(320);
+      // The overlay must be within a small tolerance of the element's
+      // CURRENT (mid-transition) position — not still sitting at the
+      // pre-transition rect (left≈40, which the old frozen-overlay bug would
+      // show here) and not already jumped to the final rect (left≈340).
+      expect(
+        Math.abs(midTransition.overlayLeft - midTransition.targetLeft),
+      ).toBeLessThan(20);
+
+      await page.waitForTimeout(300); // settle past transitionend
+      const settled = await page.evaluate(() => {
+        const target = document.getElementById("target")!;
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        )!;
+        return {
+          targetLeft: target.getBoundingClientRect().left,
+          overlayLeft: overlay.getBoundingClientRect().left,
+        };
+      });
+      expect(Math.abs(settled.overlayLeft - settled.targetLeft)).toBeLessThan(
+        2,
+      );
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── shouldForwardDesignHotkey primary-modifier whitelist audit ──────────────
+//
+// Data-driven ground truth: every one of these chords has a real handler in
+// useDesignHotkeys.ts (see that file's handleDesignHotkey for the exact
+// binding cited in each row's comment). If shouldForwardDesignHotkey doesn't
+// forward the chord while focus is inside the design iframe, the shortcut is
+// silently dead for canvas users (Cmd+U underline was exactly this bug).
+// Keeping this list in one place means future drift between the two files
+// fails loudly here instead of waiting for the next live-QA pass.
+const PRIMARY_HOTKEY_FORWARDING_CASES: Array<{
+  name: string;
+  key: string;
+  shift?: boolean;
+  alt?: boolean;
+  ctrlOnly?: boolean;
+}> = [
+  { name: "Cmd/Ctrl+Z undo", key: "z" },
+  { name: "Cmd/Ctrl+Shift+Z redo", key: "z", shift: true },
+  { name: "Cmd/Ctrl+Y redo", key: "y" },
+  { name: "Cmd/Ctrl+F find", key: "f" },
+  { name: "Cmd/Ctrl+A select all", key: "a" },
+  { name: "Cmd/Ctrl+X cut", key: "x" },
+  { name: "Cmd/Ctrl+Shift+X strikethrough", key: "x", shift: true },
+  { name: "Cmd/Ctrl+U underline", key: "u" },
+  { name: "Cmd/Ctrl+C copy", key: "c" },
+  // NOTE: bare Cmd/Ctrl+V (plain paste) is deliberately excluded here. It's
+  // the one chord shouldForwardDesignHotkey defers instead of forwarding
+  // immediately (see plainPasteHotkey in editor-chrome.bridge.ts): the
+  // keydown handler leaves the browser's native paste alone and schedules a
+  // design-hotkey post on a 0ms timer, but the document-level "paste"
+  // listener unconditionally cancels that timer the instant a real paste
+  // DOMEvent arrives (Figma-clipboard-flavored or not) so paste is never
+  // double-handled. Chromium's synthetic CDP keyboard input dispatches that
+  // real paste event even against a non-editable, unfocused document body,
+  // so this chord can't be exercised as a simple "did a design-hotkey
+  // message arrive" assertion the way every other chord here can. The
+  // Cmd+Alt+V / Cmd+Shift+V variants below aren't `plainPasteHotkey` (that
+  // flag requires !altKey && !shiftKey) and forward immediately and
+  // synchronously like every other chord, so they cover the same "v" array
+  // entry without the paste-event race.
+  { name: "Cmd/Ctrl+Alt+V paste properties", key: "v", alt: true },
+  { name: "Cmd/Ctrl+Shift+V paste over", key: "v", shift: true },
+  { name: "Cmd/Ctrl+D duplicate", key: "d" },
+  { name: "Cmd/Ctrl+R rename", key: "r" },
+  { name: "Cmd/Ctrl+Shift+R paste to replace", key: "r", shift: true },
+  { name: "Cmd/Ctrl+Shift+H toggle hidden", key: "h", shift: true },
+  { name: "Cmd/Ctrl+Shift+L toggle locked", key: "l", shift: true },
+  { name: "Cmd/Ctrl+G group", key: "g" },
+  // BUG-UNGROUP-HOTKEY: Shift+Cmd+G ungroups (see useDesignHotkeys.ts's Cmd+G
+  // family) — was dead because handleDesignHotkey itself swallowed it, not
+  // because the bridge failed to forward it (this row pins that the bridge
+  // side was never the problem: "g" is already unconditionally in the
+  // primary-modifier whitelist above, regardless of shiftKey).
+  { name: "Cmd/Ctrl+Shift+G ungroup", key: "g", shift: true },
+  { name: "Cmd/Ctrl+Alt+G frame selection", key: "g", alt: true },
+  { name: "Cmd/Ctrl+= zoom in", key: "=" },
+  { name: "Cmd/Ctrl+- zoom out", key: "-" },
+  { name: "Cmd/Ctrl+0 zoom reset", key: "0" },
+  { name: "Cmd/Ctrl+Alt+K create component", key: "k", alt: true },
+  { name: "Cmd/Ctrl+Alt+B detach instance", key: "b", alt: true },
+  { name: "Cmd/Ctrl+] bring forward", key: "]" },
+  { name: "Cmd/Ctrl+[ send backward", key: "[" },
+  { name: "Cmd/Ctrl+\\ toggle UI", key: "\\" },
+  { name: "Cmd/Ctrl+Backspace ungroup", key: "Backspace" },
+  {
+    name: "Ctrl+Alt+H distribute horizontal (literal Control)",
+    key: "h",
+    alt: true,
+    ctrlOnly: true,
+  },
+  {
+    name: "Ctrl+Alt+T tidy up (literal Control)",
+    key: "t",
+    alt: true,
+    ctrlOnly: true,
+  },
+];
+
+it(
+  "editor chrome bridge forwards every host-handled primary-modifier hotkey (data-driven audit against useDesignHotkeys.ts)",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html><html><body>
+        <div id="el" data-agent-native-node-id="el" style="position:absolute;left:40px;top:40px;width:80px;height:60px;background:#6366f1">El</div>
+      </body></html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await page.mouse.click(80, 70);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+      await collectBridgeMessages(page);
+
+      const failures: string[] = [];
+      for (const testCase of PRIMARY_HOTKEY_FORWARDING_CASES) {
+        await page.evaluate(() => {
+          (window as any).__bridgeMessages = [];
+        });
+        const modifier = testCase.ctrlOnly ? "Control" : "Meta";
+        await page.keyboard.down(modifier);
+        if (testCase.alt) await page.keyboard.down("Alt");
+        if (testCase.shift) await page.keyboard.down("Shift");
+        await page.keyboard.press(testCase.key);
+        if (testCase.shift) await page.keyboard.up("Shift");
+        if (testCase.alt) await page.keyboard.up("Alt");
+        await page.keyboard.up(modifier);
+        // postMessage always dispatches asynchronously even for same-window
+        // self-messages (per spec), and the plain-paste chord additionally
+        // defers its post behind a setTimeout(0) (see plainPasteHotkey in
+        // editor-chrome.bridge.ts) — 60ms matches this file's other
+        // message-polling waits (see the runtime-layer-snapshot test above).
+        await page.waitForTimeout(60);
+        const messages = await readBridgeMessages(page);
+        const forwarded = messages.some(
+          (message) => message.type === "design-hotkey",
+        );
+        if (!forwarded) failures.push(testCase.name);
+      }
+
+      expect(failures).toEqual([]);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "editor chrome bridge leaves bare Cmd/Ctrl+T and Cmd/Ctrl+L alone (no host binding without the alt/shift gate)",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html><html><body>
+        <div id="el" data-agent-native-node-id="el" style="position:absolute;left:40px;top:40px;width:80px;height:60px;background:#6366f1">El</div>
+      </body></html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await page.mouse.click(80, 70);
+      await page.waitForFunction(() => {
+        const overlay = document.querySelector<HTMLElement>(
+          '[data-agent-native-edit-overlay="selection"]',
+        );
+        return overlay && window.getComputedStyle(overlay).display === "block";
+      });
+      await collectBridgeMessages(page);
+
+      // Bare Cmd+T has no host binding — only the literal Ctrl+Alt+T "tidy
+      // up" combo does (see useDesignHotkeys.ts). Forwarding bare Cmd+T
+      // anyway would preventDefault() the browser's own "new tab" shortcut
+      // for nothing every time focus sits inside the design iframe.
+      await page.keyboard.down("Meta");
+      await page.keyboard.press("t");
+      await page.keyboard.up("Meta");
+      // Bare Cmd+L has no host binding either — only Cmd+Shift+L (toggle
+      // locked) does. Bare Cmd/Ctrl+L is the browser's "focus address bar"
+      // shortcut.
+      await page.keyboard.down("Meta");
+      await page.keyboard.press("l");
+      await page.keyboard.up("Meta");
+      await page.waitForTimeout(60);
+
+      const messages = await readBridgeMessages(page);
+      expect(messages.some((message) => message.type === "design-hotkey")).toBe(
+        false,
+      );
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── getElementInfo() computed-style payload completeness ───────────────────
+//
+// The properties panel's decoration toggles and auto-layout Gap field read
+// `element.computedStyles.textDecorationLine` / `.gap` / `.rowGap` /
+// `.columnGap` directly (see typography-helpers.ts's PERSISTENCE GOTCHA
+// comment and layout-properties.tsx's FlexContainerControls). A field the
+// bridge never puts in the payload reads as permanently blank/zero in the
+// panel no matter what the element's actual style is.
+it(
+  "editor chrome bridge's element-select payload includes textDecorationLine and rowGap/columnGap alongside gap",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      /* Tailwind-style utility class — the ONLY source of the gap, no
+         inline style at all, matching the live-QA "gap-3" repro. */
+      .gap-3 { gap: 12px; }
+      #row {
+        position: absolute; left: 20px; top: 20px; width: 300px; height: 80px;
+        display: flex;
+      }
+      /* Asymmetric row/column gap so rowGap and columnGap are provably
+         distinct fields, not just aliases of the shorthand. */
+      #split {
+        position: absolute; left: 20px; top: 120px; width: 300px; height: 80px;
+        display: flex; flex-wrap: wrap; row-gap: 6px; column-gap: 18px;
+      }
+      #underlined {
+        position: absolute; left: 20px; top: 220px; width: 200px; height: 30px;
+        text-decoration: underline;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="row" class="gap-3" data-agent-native-node-id="row"></div>
+    <div id="split" data-agent-native-node-id="split"></div>
+    <div id="underlined" data-agent-native-node-id="underlined">Hi</div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      // Class-driven gap container (Tailwind-style `gap-3` utility class,
+      // no inline style at all) — the live-QA "shows 0" repro case. Wait for
+      // the actual "element-select" message rather than the overlay's
+      // display style: postMessage always dispatches asynchronously (even
+      // same-window self-messages), so racing straight from the overlay's
+      // (synchronously-set) display style to reading __bridgeMessages can
+      // read the array before the message has actually arrived.
+      await page.mouse.click(170, 60);
+      await page.waitForFunction(() =>
+        ((window as any).__bridgeMessages ?? []).some(
+          (message: any) => message.type === "element-select",
+        ),
+      );
+      const rowMessages = await readBridgeMessages(page);
+      const rowSelect = rowMessages.find(
+        (message) => message.type === "element-select",
+      ) as
+        | { payload?: { computedStyles?: Record<string, string> } }
+        | undefined;
+      expect(rowSelect?.payload?.computedStyles?.gap).toBe("12px");
+      expect(rowSelect?.payload?.computedStyles?.rowGap).toBe("12px");
+      expect(rowSelect?.payload?.computedStyles?.columnGap).toBe("12px");
+
+      await page.evaluate(() => {
+        (window as any).__bridgeMessages = [];
+      });
+      await page.mouse.click(170, 160);
+      await page.waitForFunction(() =>
+        ((window as any).__bridgeMessages ?? []).some(
+          (message: any) => message.type === "element-select",
+        ),
+      );
+      const splitMessages = await readBridgeMessages(page);
+      const splitSelect = splitMessages.find(
+        (message) => message.type === "element-select",
+      ) as
+        | { payload?: { computedStyles?: Record<string, string> } }
+        | undefined;
+      expect(splitSelect?.payload?.computedStyles?.rowGap).toBe("6px");
+      expect(splitSelect?.payload?.computedStyles?.columnGap).toBe("18px");
+
+      await page.evaluate(() => {
+        (window as any).__bridgeMessages = [];
+      });
+      await page.mouse.click(60, 235);
+      await page.waitForFunction(() =>
+        ((window as any).__bridgeMessages ?? []).some(
+          (message: any) => message.type === "element-select",
+        ),
+      );
+      const underlinedMessages = await readBridgeMessages(page);
+      const underlinedSelect = underlinedMessages.find(
+        (message) => message.type === "element-select",
+      ) as
+        | { payload?: { computedStyles?: Record<string, string> } }
+        | undefined;
+      expect(
+        underlinedSelect?.payload?.computedStyles?.textDecorationLine,
+      ).toBe("underline");
+
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+// ── Layers-panel-driven selection must post the same rich payload ──────────
+//
+// The host tells the iframe which element is selected via a "select-element"
+// postMessage (this is how Layers-panel clicks, not just canvas pointer
+// clicks, drive selection). Before this fix, that handler only repositioned
+// the selection overlay and never called postElementSelect(), so the
+// properties panel kept whatever payload (or lack of one) it already had —
+// live-QA symptom: canvas-click selection showed Fill correctly, the same
+// element selected via the Layers panel showed an empty Fill section.
+it(
+  "editor chrome bridge posts the full element-select payload when the host drives selection via select-element (Layers panel parity with pointer selection)",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      page.on("pageerror", (err) => pageErrors.push(err.message));
+      await page.setContent(`<!doctype html>
+<html>
+  <head>
+    <style>
+      html, body { margin: 0; width: 100%; height: 100%; }
+      #target {
+        position: absolute; left: 40px; top: 40px; width: 120px; height: 60px;
+        background: linear-gradient(90deg, red 0%, green 50%, blue 100%);
+      }
+    </style>
+  </head>
+  <body>
+    <div id="target" data-agent-native-node-id="target"></div>
+  </body>
+</html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      // Host-driven selection — exactly what DesignCanvas.tsx sends when the
+      // Layers panel (or replayIframeEditorState) selects a node by selector,
+      // with no prior pointer interaction inside the iframe at all.
+      await page.evaluate(() => {
+        window.postMessage(
+          {
+            type: "select-element",
+            selector: "#target",
+            selectorCandidates: ["#target"],
+          },
+          "*",
+        );
+      });
+      // Wait for the actual "element-select" message (postMessage always
+      // dispatches asynchronously, even for same-window self-messages) —
+      // racing straight from the overlay's synchronously-set display style
+      // would read __bridgeMessages before the message has actually arrived.
+      await page.waitForFunction(() =>
+        ((window as any).__bridgeMessages ?? []).some(
+          (message: any) => message.type === "element-select",
+        ),
+      );
+
+      const messages = await readBridgeMessages(page);
+      const select = messages.find(
+        (message) => message.type === "element-select",
+      ) as
+        | {
+            payload?: {
+              computedStyles?: Record<string, string>;
+              selector?: string;
+            };
+          }
+        | undefined;
+      expect(select).toBeTruthy();
+      expect(select?.payload?.selector).toBe(
+        '[data-agent-native-node-id="target"]',
+      );
+      // The full payload — not the empty-computedStyles light descriptor —
+      // must be what's posted, with the gradient's backgroundImage intact
+      // (all 3 stops, not truncated/parsed down to fewer). Computed style
+      // normalizes named colors to rgb()/rgba(), so assert on stop COUNT
+      // (one "%" per authored stop) rather than the literal color names.
+      const backgroundImage = select?.payload?.computedStyles?.backgroundImage;
+      expect(backgroundImage).toBeTruthy();
+      expect(backgroundImage).toContain("gradient");
+      expect((backgroundImage ?? "").match(/%/g)?.length).toBe(3);
+
+      // Re-sending the identical select-element (the ~1-2s poll-tick replay)
+      // must NOT re-post — this is the guard that keeps the fix from
+      // becoming a message-spam loop.
+      await page.evaluate(() => {
+        (window as any).__bridgeMessages = [];
+      });
+      await page.evaluate(() => {
+        window.postMessage(
+          {
+            type: "select-element",
+            selector: "#target",
+            selectorCandidates: ["#target"],
+          },
+          "*",
+        );
+      });
+      await page.waitForTimeout(60);
+      const replayMessages = await readBridgeMessages(page);
+      expect(
+        replayMessages.some((message) => message.type === "element-select"),
+      ).toBe(false);
+
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
+
+it(
+  "editor chrome bridge posts an ordered selectable layer stack for contextmenu points",
+  { timeout: 30_000 },
+  async () => {
+    const browser = await chromium.launch({ headless: true });
+    const pageErrors: string[] = [];
+    try {
+      const page = await browser.newPage({
+        viewport: { width: 600, height: 500 },
+      });
+      page.on("pageerror", (error) => pageErrors.push(error.message));
+      await page.setContent(`<!doctype html><html><body style="margin:0">
+        <div data-agent-native-node-id="stage" data-agent-native-layer-name="Stage frame" style="position:relative;width:400px;height:350px">
+          <div data-agent-native-node-id="back" data-agent-native-layer-name="Back sibling" style="position:absolute;left:40px;top:40px;width:260px;height:250px;background:#acf">Back</div>
+          <div data-agent-native-node-id="parent" data-agent-native-layer-name="Nested parent" style="position:absolute;z-index:1;left:80px;top:80px;width:200px;height:200px;background:#afa">
+            <div data-agent-native-node-id="child" data-agent-native-layer-name="Nested child" style="position:absolute;left:20px;top:20px;width:140px;height:140px;background:#ffa">Child</div>
+          </div>
+          <div data-agent-native-node-id="front" data-agent-native-layer-name="Front sibling" style="position:absolute;z-index:2;left:120px;top:120px;width:110px;height:110px;background:#faa">Front</div>
+          <div data-agent-native-node-id="hidden" data-agent-native-layer-name="Hidden cover" data-agent-native-hidden="true" style="position:absolute;z-index:3;left:130px;top:130px;width:90px;height:90px">Hidden</div>
+          <div data-agent-native-node-id="locked" data-agent-native-layer-name="Locked cover" data-agent-native-locked="true" style="position:absolute;z-index:4;left:140px;top:140px;width:70px;height:70px">Locked</div>
+        </div>
+      </body></html>`);
+      await page.addScriptTag({ content: hydratedEditorChromeBridgeScript() });
+      await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+      await collectBridgeMessages(page);
+
+      await page.evaluate(() => {
+        const shield = document.querySelector(
+          '[data-agent-native-edit-overlay="shield"]',
+        );
+        shield?.dispatchEvent(
+          new MouseEvent("contextmenu", {
+            bubbles: true,
+            cancelable: true,
+            button: 2,
+            clientX: 165,
+            clientY: 165,
+          }),
+        );
+      });
+      await page.waitForFunction(() =>
+        ((window as any).__bridgeMessages ?? []).some(
+          (message: any) => message.type === "element-contextmenu",
+        ),
+      );
+      const messages = await readBridgeMessages(page);
+      expect(
+        messages.some((message) => message.type === "element-select"),
+      ).toBe(false);
+      const contextMenu = messages.find(
+        (message) => message.type === "element-contextmenu",
+      ) as
+        | {
+            screenId?: string;
+            layerCandidates?: Array<{
+              label?: string;
+              info?: { sourceId?: string; selector?: string };
+            }>;
+          }
+        | undefined;
+      expect(contextMenu?.screenId).toBe("bridge-guard");
+      expect(
+        contextMenu?.layerCandidates?.map((candidate) => candidate.label),
+      ).toEqual([
+        "Front sibling",
+        "Nested child",
+        "Nested parent",
+        "Back sibling",
+        "Stage frame",
+      ]);
+      expect(
+        contextMenu?.layerCandidates?.map(
+          (candidate) => candidate.info?.sourceId,
+        ),
+      ).toEqual(["front", "child", "parent", "back", "stage"]);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await browser.close();
+    }
+  },
+);
diff --git a/templates/design/app/components/design/bridge/editor-chrome.bridge.ts b/templates/design/app/components/design/bridge/editor-chrome.bridge.ts
index e41e1b82d3..27a1703f39 100644
--- a/templates/design/app/components/design/bridge/editor-chrome.bridge.ts
+++ b/templates/design/app/components/design/bridge/editor-chrome.bridge.ts
@@ -13,6 +13,9 @@
  *   __EDITOR_CHROME_SCALE_Y__  — number string, e.g. "1.5"
  *   __DESIGN_CANVAS_SCREEN_ID__ — string literal for the owning screen/file id
  *   __DESIGN_CANVAS_BOARD_SURFACE__ — boolean literal for top-level board iframe
+ *   __DESIGN_CANVAS_CONTENT_OFFSET_X__ — embedded board render-window x offset
+ *   __DESIGN_CANVAS_CONTENT_OFFSET_Y__ — embedded board render-window y offset
+ *   __RUNTIME_LAYER_SNAPSHOT_ENABLED__ — true only for URL-backed localhost apps
  *
  * Rules:
  *   • No import/require of any module (DOM globals only).
@@ -28,6 +31,9 @@ declare var __EDITOR_CHROME_SCALE_X__: string;
 declare var __EDITOR_CHROME_SCALE_Y__: string;
 declare var __DESIGN_CANVAS_SCREEN_ID__: string;
 declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
+declare var __DESIGN_CANVAS_CONTENT_OFFSET_X__: number;
+declare var __DESIGN_CANVAS_CONTENT_OFFSET_Y__: number;
+declare var __RUNTIME_LAYER_SNAPSHOT_ENABLED__: boolean;
 
 (function () {
   // Idempotency guard: replace-document-content / srcdoc rebuilds can end up
@@ -51,6 +57,11 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
   var textEditingEnabled = !readOnly && textEditingEnabledFlag;
   var designCanvasScreenId = __DESIGN_CANVAS_SCREEN_ID__ || "";
   var designCanvasBoardSurface = !!__DESIGN_CANVAS_BOARD_SURFACE__;
+  var designCanvasContentOffsetX =
+    Number(__DESIGN_CANVAS_CONTENT_OFFSET_X__) || 0;
+  var designCanvasContentOffsetY =
+    Number(__DESIGN_CANVAS_CONTENT_OFFSET_Y__) || 0;
+  var runtimeLayerSnapshotEnabled = !!__RUNTIME_LAYER_SNAPSHOT_ENABLED__;
   var scaleToolEnabled = false;
   // Interaction-state forced preview (phase 2 — see shared/interaction-states.ts's
   // "Forced-preview mechanism" doc comment). Tracks which single node id
@@ -211,6 +222,359 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     );
   }
 
+  /**
+   * React 19 development builds keep the exact jsxDEV call site on the host
+   * element's Fiber `_debugStack`, even though React does not emit that source
+   * location as a DOM attribute. Recover it without depending on React internals
+   * for mutations: this is read-only provenance used to identify the selected
+   * source file and line. Explicit data-source-* / data-loc attributes still
+   * win below, and production builds simply return undefined.
+   */
+  // Fiber debug stacks are immutable for the lifetime of a mounted host node.
+  // Keep the relatively expensive Object.keys + owner walk off the snapshot
+  // hot path after the first successful read. A WeakMap also means React can
+  // collect unmounted nodes normally. Do not cache misses: the bridge can run
+  // before a slow/Suspense hydration attaches Fiber to an existing DOM node.
+  var reactDebugProvenanceCache =
+    typeof WeakMap !== "undefined"
+      ? new WeakMap<Element, ReturnType<typeof reactDebugProvenance>>()
+      : null;
+
+  function reactDebugProvenance(el: Element):
+    | {
+        sourceFile: string;
+        line: number;
+        column?: number;
+        component?: string;
+      }
+    | undefined {
+    var cached = reactDebugProvenanceCache?.get(el);
+    if (cached !== undefined) return cached;
+    var fiberKey = Object.keys(el).find(function (key) {
+      return key.indexOf("__reactFiber$") === 0;
+    });
+    if (!fiberKey) return undefined;
+    var fiber = (el as unknown as Record<string, any>)[fiberKey];
+    for (var depth = 0; fiber && depth < 12; depth += 1) {
+      var stack = String(fiber._debugStack?.stack || "");
+      var lines = stack.split("\n");
+      for (var index = 0; index < lines.length; index += 1) {
+        var lineText = lines[index];
+        var match = lineText.match(
+          /(?:\(|\s)(https?:\/\/[^\s)]+?):(\d+):(\d+)\)?\s*$/,
+        );
+        if (!match) continue;
+        try {
+          var sourceUrl = new URL(match[1]);
+          var pathname = decodeURIComponent(sourceUrl.pathname);
+          if (pathname.indexOf("/node_modules/") >= 0) continue;
+          var sourceFile =
+            pathname.indexOf("/@fs/") === 0
+              ? pathname.slice("/@fs".length)
+              : pathname.replace(/^\/+/, "");
+          if (!sourceFile) continue;
+          var componentMatch = lineText.match(/\bat\s+([^\s(]+)\s*\(/);
+          var provenance = {
+            sourceFile: sourceFile,
+            line: parseInt(match[2], 10),
+            column: parseInt(match[3], 10),
+            component: componentMatch ? componentMatch[1] : undefined,
+          };
+          reactDebugProvenanceCache?.set(el, provenance);
+          return provenance;
+        } catch (_error) {
+          // Ignore malformed/non-URL debug frames and keep walking owners.
+        }
+      }
+      fiber = fiber.return;
+    }
+    return undefined;
+  }
+
+  var runtimeLayerSnapshotTimer: number | null = null;
+  var runtimeLayerSnapshotMaxTimer: number | null = null;
+  var lastRuntimeLayerSnapshotHtml = "";
+
+  function runtimeLayerHash(value: string): string {
+    var hash = 0x811c9dc5;
+    for (var index = 0; index < value.length; index += 1) {
+      hash ^= value.charCodeAt(index);
+      hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(36);
+  }
+
+  function runtimeLayerStructuralPath(el: Element): string {
+    var parts: string[] = [];
+    var node: Element | null = el;
+    while (node && node !== document.body) {
+      var tag = node.tagName.toLowerCase();
+      var parent = node.parentElement;
+      if (parent) {
+        var sameTag = Array.prototype.filter.call(
+          parent.children,
+          function (sibling) {
+            return sibling.tagName === node!.tagName;
+          },
+        );
+        tag += ":nth-of-type(" + (sameTag.indexOf(node) + 1) + ")";
+      }
+      parts.unshift(tag);
+      node = parent;
+    }
+    return parts.join(" > ") || "body";
+  }
+
+  function ensureRuntimeLayerNodeId(el: Element): string {
+    var existing = el.getAttribute("data-agent-native-node-id")?.trim();
+    if (existing) return existing;
+    var provenance = reactDebugProvenance(el);
+    var provenanceKey = provenance
+      ? [
+          provenance.sourceFile,
+          provenance.line,
+          provenance.column || 0,
+          provenance.component || "",
+        ].join(":")
+      : "dom";
+    var nodeId =
+      "runtime-" +
+      runtimeLayerHash(
+        designCanvasScreenId +
+          ":" +
+          provenanceKey +
+          ":" +
+          runtimeLayerStructuralPath(el),
+      );
+    // This attribute is editor-only and never persisted. Stamping the live DOM
+    // gives the runtime projection and the selectable element one exact shared
+    // identity. Qualifying the hash with the owning screen/file id prevents a
+    // shared React shell from producing the same layer id in two route iframes
+    // (which would make the editor's document-wide owner map route selection
+    // and hover to whichever screen registered last). The structural path
+    // keeps the id stable across reloads within that iframe while still
+    // disambiguating repeated JSX emitted from the same source location.
+    el.setAttribute("data-agent-native-node-id", nodeId);
+    return nodeId;
+  }
+
+  function isRuntimeLayerVisualNode(el: Element): boolean {
+    if (
+      /^(script|style|template|noscript|link|meta|title)$/i.test(el.tagName)
+    ) {
+      return false;
+    }
+    return !(
+      isOverlayElement(el) || el.closest("[data-agent-native-edit-overlay]")
+    );
+  }
+
+  function serializeRuntimeLayerSnapshot(): {
+    html: string;
+    nodeCount: number;
+  } | null {
+    if (!document.body) return null;
+    var sourceNodes = Array.prototype.slice.call(
+      document.body.querySelectorAll("*"),
+    ) as Element[];
+    var cloneBody = document.body.cloneNode(true) as HTMLElement;
+    var cloneNodes = Array.prototype.slice.call(
+      cloneBody.querySelectorAll("*"),
+    ) as Element[];
+    var nodeCount = 0;
+    for (
+      var index = 0;
+      index < sourceNodes.length && index < cloneNodes.length;
+      index += 1
+    ) {
+      var sourceNode = sourceNodes[index];
+      var cloneNode = cloneNodes[index];
+      if (!isRuntimeLayerVisualNode(sourceNode)) {
+        cloneNode.setAttribute("data-an-runtime-layer-remove", "true");
+        continue;
+      }
+      cloneNode.setAttribute(
+        "data-agent-native-node-id",
+        ensureRuntimeLayerNodeId(sourceNode),
+      );
+      var provenance = reactDebugProvenance(sourceNode);
+      if (provenance) {
+        cloneNode.setAttribute("data-source-file", provenance.sourceFile);
+        cloneNode.setAttribute("data-source-line", String(provenance.line));
+        if (provenance.column) {
+          cloneNode.setAttribute(
+            "data-source-column",
+            String(provenance.column),
+          );
+        }
+        if (provenance.component) {
+          cloneNode.setAttribute("data-component-name", provenance.component);
+        }
+      }
+      nodeCount += 1;
+    }
+    cloneBody
+      .querySelectorAll("[data-an-runtime-layer-remove]")
+      .forEach(function (node) {
+        node.remove();
+      });
+    cloneBody
+      .querySelectorAll("script,style,template,noscript,link,meta,title")
+      .forEach(function (node) {
+        node.remove();
+      });
+    cloneBody.setAttribute(
+      "data-agent-native-node-id",
+      ensureRuntimeLayerNodeId(document.body),
+    );
+    cloneBody.setAttribute("data-an-runtime-layer-snapshot", "true");
+    var html = "<!doctype html><html>" + cloneBody.outerHTML + "</html>"; // i18n-ignore serialized runtime-layer HTML payload, not visible UI copy
+    if (html.length > 2_000_000) return null;
+    return { html: html, nodeCount: nodeCount };
+  }
+
+  function postRuntimeLayerSnapshot(): void {
+    if (runtimeLayerSnapshotTimer !== null) {
+      window.clearTimeout(runtimeLayerSnapshotTimer);
+    }
+    if (runtimeLayerSnapshotMaxTimer !== null) {
+      window.clearTimeout(runtimeLayerSnapshotMaxTimer);
+    }
+    runtimeLayerSnapshotTimer = null;
+    runtimeLayerSnapshotMaxTimer = null;
+    var snapshot = serializeRuntimeLayerSnapshot();
+    if (!snapshot || snapshot.html === lastRuntimeLayerSnapshotHtml) return;
+    lastRuntimeLayerSnapshotHtml = snapshot.html;
+    (window.parent as Window).postMessage(
+      {
+        type: "agent-native:runtime-layer-snapshot",
+        payload: snapshot,
+      },
+      "*",
+    );
+  }
+
+  function scheduleRuntimeLayerSnapshot(): void {
+    // A leading-edge throttle still serializes a fast clock, streaming list,
+    // or hydration loop five times per second forever. Debounce on the trailing
+    // edge so a normal React commit becomes one snapshot, with a bounded max
+    // wait so a genuinely continuous stream still refreshes Layers eventually
+    // without monopolising the iframe main thread.
+    if (runtimeLayerSnapshotTimer !== null) {
+      window.clearTimeout(runtimeLayerSnapshotTimer);
+    }
+    runtimeLayerSnapshotTimer = window.setTimeout(
+      postRuntimeLayerSnapshot,
+      300,
+    );
+    if (runtimeLayerSnapshotMaxTimer === null) {
+      runtimeLayerSnapshotMaxTimer = window.setTimeout(
+        postRuntimeLayerSnapshot,
+        1500,
+      );
+    }
+  }
+
+  // Runtime Layers describes hierarchy, names, and layout containers. It does
+  // not need a new full-document snapshot for animation-frame churn such as
+  // transform/opacity/style streaming or state-only utility classes. Compare
+  // only the class/style subset that can change the projected Layers tree.
+  function runtimeLayerClassSignature(value: string | null): string {
+    return String(value || "")
+      .split(/\s+/)
+      .map(function (token) {
+        var parts = token.split(":");
+        var utility = String(parts[parts.length - 1] || "").replace(/^!/, "");
+        if (
+          /^(?:flex|inline-flex|grid|inline-grid|hidden|block|inline-block|flex-row|flex-col)$/.test(
+            utility,
+          ) ||
+          /^(?:items|justify)-/.test(utility)
+        ) {
+          return utility;
+        }
+        // The projection only asks whether a component-like class exists; a
+        // transition from `button-idle` to `button-active` does not change the
+        // layer type and should not trigger another full snapshot.
+        return /(?:component|card|button|control)/.test(utility)
+          ? "component-like"
+          : "";
+      })
+      .filter(Boolean)
+      .sort()
+      .join(" ");
+  }
+
+  function runtimeLayerStyleSignature(value: string | null): string {
+    var relevant: Record<string, string> = {};
+    String(value || "")
+      .split(";")
+      .forEach(function (declaration) {
+        var separator = declaration.indexOf(":");
+        if (separator < 0) return;
+        var property = declaration.slice(0, separator).trim().toLowerCase();
+        if (
+          !/^(?:display|flex-direction|align-items|justify-content)$/.test(
+            property,
+          )
+        ) {
+          return;
+        }
+        relevant[property] = declaration.slice(separator + 1).trim();
+      });
+    return Object.keys(relevant)
+      .sort()
+      .map(function (property) {
+        return property + ":" + relevant[property];
+      })
+      .join(";");
+  }
+
+  function runtimeLayerMutationIsMeaningful(mutation: MutationRecord): boolean {
+    var target = mutation.target as Element;
+    if (
+      target.nodeType === 1 &&
+      (isOverlayElement(target) ||
+        target.closest?.("[data-agent-native-edit-overlay]"))
+    ) {
+      return false;
+    }
+    if (mutation.type === "childList") {
+      var changedNodes = Array.prototype.slice
+        .call(mutation.addedNodes)
+        .concat(Array.prototype.slice.call(mutation.removedNodes));
+      return changedNodes.some(function (node: Node) {
+        var element =
+          node.nodeType === 1
+            ? (node as Element)
+            : node.parentElement || mutation.target;
+        return !(
+          element.nodeType === 1 &&
+          (isOverlayElement(element as Element) ||
+            (element as Element).closest?.("[data-agent-native-edit-overlay]"))
+        );
+      });
+    }
+    if (mutation.type === "characterData") {
+      return true;
+    }
+    if (mutation.type !== "attributes") return false;
+    var name = mutation.attributeName || "";
+    if (name === "class") {
+      return (
+        runtimeLayerClassSignature(mutation.oldValue) !==
+        runtimeLayerClassSignature(target.getAttribute("class"))
+      );
+    }
+    if (name === "style") {
+      return (
+        runtimeLayerStyleSignature(mutation.oldValue) !==
+        runtimeLayerStyleSignature(target.getAttribute("style"))
+      );
+    }
+    return true;
+  }
+
   function isDocumentRootElement(el: Element | null): boolean {
     return el === document.body || el === document.documentElement;
   }
@@ -806,10 +1170,8 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
           "Parent layout context decides whether movement means gap, order, alignment, or wrapper structure.",
       });
     }
-    // --- provenance: read source-location attributes when present ---
-    // These are emitted by connected apps via @vitejs/plugin-react jsxDEV or a
-    // Babel source plugin.  Cross-origin localhost iframes cannot be read (CSP /
-    // same-origin policy), so this will be undefined in that case — expected.
+    // --- provenance: read explicit source-location attributes when present,
+    // then fall back to React's development-only jsxDEV Fiber stack. ---
     var provenance:
       | {
           sourceFile?: string;
@@ -844,6 +1206,18 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         if (hasColumn) dataSourceColumn = lastPart;
       }
     }
+    if (!dataSourceFile) {
+      var reactProvenance = reactDebugProvenance(el);
+      if (reactProvenance) {
+        dataSourceFile = reactProvenance.sourceFile;
+        dataSourceLine = String(reactProvenance.line);
+        dataSourceColumn = reactProvenance.column
+          ? String(reactProvenance.column)
+          : null;
+        dataComponentName =
+          dataComponentName || reactProvenance.component || null;
+      }
+    }
     if (
       dataSourceFile ||
       dataSourceLine ||
@@ -884,11 +1258,18 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         lineHeight: cs.lineHeight,
         letterSpacing: cs.letterSpacing,
         textAlign: cs.textAlign,
+        // Clean longhand for decoration-toggle state (Cmd+U underline /
+        // Cmd+Shift+X strikethrough). Deliberately the longhand, not the
+        // `textDecoration` shorthand — see typography-helpers.ts's
+        // PERSISTENCE GOTCHA comment: reads use this clean value, writes
+        // still commit through the shorthand property name.
+        textDecorationLine: cs.textDecorationLine,
         display: cs.display,
         overflow: cs.overflow,
         flexDirection: cs.flexDirection,
         justifyContent: cs.justifyContent,
         alignItems: cs.alignItems,
+        justifyItems: cs.justifyItems,
         alignSelf: cs.alignSelf,
         flexGrow: cs.flexGrow,
         flexShrink: cs.flexShrink,
@@ -896,12 +1277,17 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         order: cs.order,
         gridColumn: cs.gridColumn,
         gridRow: cs.gridRow,
+        gridTemplateColumns: cs.gridTemplateColumns,
+        gridTemplateRows: cs.gridTemplateRows,
+        gridAutoFlow: cs.gridAutoFlow,
         position: cs.position,
         top: cs.top,
         right: cs.right,
         bottom: cs.bottom,
         left: cs.left,
         gap: cs.gap,
+        rowGap: cs.rowGap,
+        columnGap: cs.columnGap,
         width: cs.width,
         height: cs.height,
         opacity: cs.opacity,
@@ -961,6 +1347,9 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         width: rect.width,
         height: rect.height,
       },
+      parentBoundingRect: el.parentElement
+        ? rectInfoForElement(el.parentElement)
+        : undefined,
       textContent: el.textContent ? el.textContent.slice(0, 200) : undefined,
       htmlContent:
         el.innerHTML && el.innerHTML !== el.textContent
@@ -1475,6 +1864,27 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
 
   var selectedEl: Element | null = null;
   var hoveredEl: Element | null = null;
+  // Last element an "element-hover" message was actually posted for. Lets
+  // the shield's pointermove handler skip getLightElementInfo's two
+  // getComputedStyle calls plus the postMessage on every one of the dozens
+  // of raw pointermove ticks a slow hover over one unchanged element
+  // produces — only the FIRST tick that lands on a given element needs to
+  // tell the host anything new. The parent already de-dupes on its side
+  // (see the "PF9" equality-bail comment in DesignEditor.tsx), so skipping
+  // the redundant sends here is a pure perf win with no behavior change.
+  var lastHoverInfoPostedEl: Element | null = null;
+
+  // Every path that clears (or invalidates) the current hover must re-arm the
+  // post gate above through this helper, not just null out hoveredEl. If a
+  // path nulls hoveredEl without resetting lastHoverInfoPostedEl, the pointer
+  // returning to the SAME element the gate already posted for will silently
+  // skip re-posting "element-hover" to the host, leaving its hover state
+  // stuck until a different element is hovered.
+  function clearHoverGate(): void {
+    hoveredEl = null;
+    lastHoverInfoPostedEl = null;
+  }
+
   var passiveSelectionEls: Element[] = [];
   var passiveSelectionOverlays: HTMLElement[] = [];
   var activeMarqueeSelection: {
@@ -1648,6 +2058,8 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
   var spacingHatchNodesByKey: Record<string, Element> = {};
   var spacingOverlayRenderKey = "";
   var activeDragCancel: (() => boolean) | null = null;
+  var bridgeSpaceKeyPressed = false;
+  var bridgeSpaceKeyConsumedByDrag = false;
   var activeCrossScreenStyleSnapshot: unknown | undefined = undefined;
   var spacingDrag: {
     key: string;
@@ -1668,7 +2080,7 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
 
   function clearRuntimeSelection(): void {
     selectedEl = null;
-    hoveredEl = null;
+    clearHoverGate();
     setPassiveSelectionElements([]);
     clearSpacingHoverTimer();
     selectedSpacingHovered = false;
@@ -2015,7 +2427,7 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
             selectedEl = document.querySelector(matchedSelector);
           } catch (_err) {}
         }
-        hoveredEl = null;
+        clearHoverGate();
         if (selectedEl && !isLayerInteractionBlocked(selectedEl)) {
           positionOverlay(selectionOverlay, selectedEl);
           postElementSelect(selectedEl);
@@ -2049,7 +2461,7 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     applyHiddenSelectors();
 
     selectedEl = null;
-    hoveredEl = null;
+    clearHoverGate();
     for (var i = 0; i < activeCandidates.length && !selectedEl; i += 1) {
       try {
         var match = document.querySelector(activeCandidates[i]);
@@ -3372,6 +3784,86 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     }
   }
 
+  // Transition/animation overlay tracking: the ResizeObserver above only
+  // fires on border-box SIZE changes, so a purely transform- or left/top-
+  // driven CSS transition/animation on the selected or hovered element (very
+  // common for hover states, toggles, carousels in AI-generated prototypes)
+  // never triggers it. Without this, the one-shot MutationObserver callback
+  // that fires when the triggering class/style attribute changes reads
+  // getBoundingClientRect() at essentially the START of the transition, and
+  // the overlay then freezes there while the real element visually slides/
+  // fades to its final position — the selection outline and its handles
+  // visibly detach from the animating element for the transition's whole
+  // duration. Fixed by running a bounded rAF refresh loop for the duration of
+  // any transition/animation that starts on a tracked element, so the
+  // overlay follows every intermediate frame instead of only the first and
+  // (via the next unrelated mutation/resize/scroll) last.
+  var overlayAnimationTrackingActive = false;
+  var overlayAnimationTrackingUntil = 0;
+  var overlayAnimationTrackingStartedAt = 0;
+  // Covers the vast majority of real UI transitions/animations (hover/toggle
+  // durations are almost always well under a second); the max below is a
+  // safety net for a transition whose end event never fires (e.g. cancelled
+  // by a later style write with no transitionend), so a slow/held animation
+  // can't pin this loop on forever.
+  var OVERLAY_ANIMATION_TRACKING_WINDOW_MS = 1000;
+  var OVERLAY_ANIMATION_TRACKING_MAX_MS = 4000;
+
+  function isOverlayAnimationTrackingTarget(
+    target: EventTarget | null,
+  ): boolean {
+    if (!target) return false;
+    return target === selectedEl || target === hoveredEl;
+  }
+
+  function tickOverlayAnimationTracking(): void {
+    if (!overlayAnimationTrackingActive) return;
+    refreshOverlays();
+    var now = Date.now();
+    if (
+      now >= overlayAnimationTrackingUntil ||
+      now - overlayAnimationTrackingStartedAt >=
+        OVERLAY_ANIMATION_TRACKING_MAX_MS
+    ) {
+      overlayAnimationTrackingActive = false;
+      return;
+    }
+    window.requestAnimationFrame(tickOverlayAnimationTracking);
+  }
+
+  // Re-armed (window extended) by every qualifying transitionrun/
+  // animationstart, so a sequence of staggered transitions on the same
+  // element keeps the loop running for their combined duration rather than
+  // stopping partway through.
+  function startOverlayAnimationTracking(): void {
+    var now = Date.now();
+    overlayAnimationTrackingUntil = now + OVERLAY_ANIMATION_TRACKING_WINDOW_MS;
+    if (overlayAnimationTrackingActive) return;
+    overlayAnimationTrackingActive = true;
+    overlayAnimationTrackingStartedAt = now;
+    window.requestAnimationFrame(tickOverlayAnimationTracking);
+  }
+
+  function onOverlayAnimationTrackingEvent(e: Event): void {
+    if (isOverlayAnimationTrackingTarget(e.target as EventTarget | null)) {
+      startOverlayAnimationTracking();
+    }
+  }
+  // Capture-phase, delegated on document (not per-element add/remove-
+  // listener bookkeeping tied to selection changes): transitionrun/
+  // animationstart bubble, so one pair of listeners registered once at
+  // bridge init covers whichever element is currently selected/hovered.
+  document.addEventListener(
+    "transitionrun",
+    onOverlayAnimationTrackingEvent,
+    true,
+  );
+  document.addEventListener(
+    "animationstart",
+    onOverlayAnimationTrackingEvent,
+    true,
+  );
+
   function hideMeasurements(): void {
     measurementOverlay.style.display = "none";
     measurementOverlay.innerHTML = "";
@@ -3717,7 +4209,15 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     // not intercept Tab when the user is tabbing through browser UI with nothing
     // selected (preserves native keyboard accessibility).
     if (key === "Tab") return !!selectedEl;
-    if (key === "Delete" || key === "Backspace") return !primary;
+    if (key === "Delete" || key === "Backspace") {
+      // Cmd/Ctrl+Backspace is Figma's "ungroup" chord (see onUngroup in
+      // useDesignHotkeys.ts) — carve out that one primary-modifier exception
+      // so it isn't swallowed by the blanket "no modifier" rule below. Any
+      // other primary+Delete/Backspace combo has no host binding, so it stays
+      // local (matches prior behavior).
+      if (primary) return key === "Backspace" && !e.altKey && !e.shiftKey;
+      return true;
+    }
     if (/^Arrow/.test(key || "")) return !e.altKey;
     if (primary) {
       return (
@@ -3736,11 +4236,44 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
           "0",
           "]",
           "[",
+          // Cmd/Ctrl+U — toggle underline (useDesignHotkeys.ts onToggleUnderline).
+          "u",
+          // Cmd/Ctrl+F — find (onFind). Bridge's "primary" doesn't distinguish
+          // Cmd from Ctrl the way isPlatformPrimaryModifier does host-side, but
+          // forwarding is harmless when the host has no match for the combo.
+          "f",
+          // Cmd/Ctrl+R rename / Cmd/Ctrl+Shift+R paste-to-replace (onRename /
+          // onPasteToReplace) — both live under bare primary+r.
+          "r",
+          // Cmd/Ctrl+\ — toggle UI (onToggleUi).
+          "\\",
         ].indexOf(normalized) !== -1 ||
         e.code === "Digit1" ||
         e.code === "Digit2" ||
         key === "1" ||
-        key === "2"
+        key === "2" ||
+        // Cmd/Ctrl+Shift+H / +L — toggle hidden / toggle locked
+        // (onToggleHidden / onToggleLocked). Gated on shiftKey so bare
+        // Cmd+H / Cmd+L — common OS "Hide app" / browser "focus address bar"
+        // shortcuts the host has no bare-primary binding for — are left
+        // alone (see useDesignHotkeys.ts: both require event.shiftKey).
+        (e.shiftKey && (normalized === "h" || normalized === "l")) ||
+        // Cmd/Ctrl+Alt+B detach instance / Cmd/Ctrl+Alt+K create component
+        // (onDetachInstance / onCreateComponent). Gated on altKey so bare
+        // Cmd+B / Cmd+K are left alone — the host has no bare-primary
+        // binding for either.
+        (e.altKey && (normalized === "b" || normalized === "k")) ||
+        // Ctrl+Alt+H / Ctrl+Alt+T — distribute horizontal / tidy up
+        // (onDistributeSelection / onTidyUp). useDesignHotkeys.ts keeps these
+        // on LITERAL Control on every platform (never remapped to Cmd), so
+        // this mirrors that exact gate instead of the generic "primary" flag
+        // — a blanket "t" entry above would otherwise swallow the common
+        // Cmd+T "new tab" browser shortcut for a combo the host never binds.
+        (e.ctrlKey &&
+          e.altKey &&
+          !e.metaKey &&
+          !e.shiftKey &&
+          (normalized === "h" || normalized === "t"))
       );
     }
     if (
@@ -4164,8 +4697,64 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
   function openContextMenuAtEvent(e) {
     stopNativeInteraction(e);
     blurActiveTextEditor();
-    var target = elementFromEditorPoint(e.clientX, e.clientY);
-    if (!target && lastEditorPointWasBlocked) return;
+    var shieldPointerEvents = shieldOverlay.style.pointerEvents;
+    var selectionPointerEvents = selectionOverlay.style.pointerEvents;
+    var highlightPointerEvents = highlightOverlay.style.pointerEvents;
+    shieldOverlay.style.pointerEvents = "none";
+    selectionOverlay.style.pointerEvents = "none";
+    highlightOverlay.style.pointerEvents = "none";
+    var pointTargets = document.elementsFromPoint
+      ? document.elementsFromPoint(e.clientX, e.clientY)
+      : [document.elementFromPoint(e.clientX, e.clientY)];
+    shieldOverlay.style.pointerEvents = shieldPointerEvents;
+    selectionOverlay.style.pointerEvents = selectionPointerEvents;
+    highlightOverlay.style.pointerEvents = highlightPointerEvents;
+
+    var candidateElements: Element[] = [];
+    var layerCandidates: Array<{
+      key: string;
+      label: string;
+      info: unknown;
+    }> = [];
+    pointTargets.forEach(function (pointTarget) {
+      if (!pointTarget || pointTarget.nodeType !== 1) return;
+      if (isOverlayElement(pointTarget)) return;
+      var candidate = selectionTargetForHit(pointTarget);
+      if (
+        !candidate ||
+        isDocumentRootElement(candidate) ||
+        isOverlayElement(candidate) ||
+        isLayerInteractionBlocked(candidate) ||
+        isTemplateCloneElement(candidate) ||
+        candidateElements.indexOf(candidate) !== -1
+      ) {
+        return;
+      }
+      candidateElements.push(candidate);
+      var candidateInfo = getElementInfo(candidate);
+      var explicitLabel =
+        (candidate.getAttribute &&
+          candidate.getAttribute("data-agent-native-layer-name")) ||
+        "";
+      var textLabel = (candidate.textContent || "").trim().replace(/\s+/g, " ");
+      var label =
+        explicitLabel ||
+        candidateInfo.componentName ||
+        candidate.id ||
+        (textLabel && textLabel.length <= 48 ? textLabel : "") ||
+        candidate.tagName.toLowerCase();
+      var identity =
+        candidateInfo.sourceId ||
+        candidateInfo.selector ||
+        String(layerCandidates.length);
+      layerCandidates.push({
+        key: String(identity) + ":" + String(layerCandidates.length),
+        label: String(label).slice(0, 80),
+        info: candidateInfo,
+      });
+    });
+
+    var target = candidateElements[0] || null;
     var info = null;
     if (target) {
       selectedSpacingHovered = false;
@@ -4174,7 +4763,6 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       if (selectedEl && !isLayerInteractionBlocked(selectedEl)) {
         info = getElementInfo(selectedEl);
         positionOverlay(selectionOverlay, selectedEl);
-        postElementSelect(selectedEl, e);
       } else {
         selectedEl = null;
         hideSelectionOverlay();
@@ -4183,9 +4771,11 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     (window.parent as Window).postMessage(
       {
         type: "element-contextmenu",
+        screenId: designCanvasScreenId,
         clientX: e.clientX,
         clientY: e.clientY,
         payload: info,
+        layerCandidates: layerCandidates,
       },
       "*",
     );
@@ -4223,6 +4813,61 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     return null;
   }
 
+  // Host-driven Layers-panel moves must never inherit findRuntimeTarget's
+  // selected-element shortcut or first-match querySelector behavior. Runtime
+  // React trees routinely repeat classes and component markup, so a selector
+  // is only safe when it identifies exactly one live element. Prefer the
+  // runtime projection's stable source id and fall back to the selector only
+  // when that id has no match at all.
+  function findUniqueRuntimeStructureTarget(selector, sourceId) {
+    var matches = new Set<Element>();
+    if (typeof sourceId === "string" && sourceId) {
+      var attributes = [
+        "data-agent-native-node-id",
+        "data-code-layer-id",
+        "data-layer-id",
+        "data-builder-id",
+        "data-loc",
+        "id",
+      ];
+      for (var i = 0; i < attributes.length; i += 1) {
+        try {
+          var sourceMatches = document.querySelectorAll(
+            "[" + attributes[i] + '=\"' + escapeAttribute(sourceId) + '\"]',
+          );
+          for (var j = 0; j < sourceMatches.length; j += 1) {
+            matches.add(sourceMatches[j]);
+          }
+        } catch (_err) {}
+      }
+      if (matches.size > 1) return null;
+      if (matches.size === 1) {
+        var sourceMatch = Array.from(matches)[0];
+        return sourceMatch &&
+          sourceMatch !== document.body &&
+          sourceMatch !== document.documentElement &&
+          !isOverlayElement(sourceMatch) &&
+          !isLayerInteractionBlocked(sourceMatch)
+          ? sourceMatch
+          : null;
+      }
+    }
+    if (typeof selector !== "string" || !selector) return null;
+    try {
+      var selectorMatches = document.querySelectorAll(selector);
+      if (selectorMatches.length !== 1) return null;
+      var selectorMatch = selectorMatches[0];
+      return selectorMatch !== document.body &&
+        selectorMatch !== document.documentElement &&
+        !isOverlayElement(selectorMatch) &&
+        !isLayerInteractionBlocked(selectorMatch)
+        ? selectorMatch
+        : null;
+    } catch (_err) {
+      return null;
+    }
+  }
+
   function removeRuntimeTarget(selector, selectorCandidates) {
     var target = findRuntimeTarget(selector, selectorCandidates);
     if (
@@ -4243,7 +4888,7 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       selectedEl = null;
       hideSelectionOverlay();
     }
-    hoveredEl = null;
+    clearHoverGate();
     highlightOverlay.style.display = "none";
     hideMeasurements();
     refreshOverlays();
@@ -5368,7 +6013,12 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       el.getAttribute("data-agent-native-primitive") ||
       ""
     ).toLowerCase();
-    if (primitive !== "rectangle" && primitive !== "rect") return false;
+    if (
+      primitive !== "rectangle" &&
+      primitive !== "rect" &&
+      primitive !== "frame"
+    )
+      return false;
     var cs = window.getComputedStyle(el);
     return cs.position === "absolute" || cs.position === "fixed";
   }
@@ -6020,6 +6670,125 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     };
   }
 
+  /** Resolve a flow child's full Figma-style move target. The legacy reorder
+   * resolver always fell back to the current parent/root, so a child could be
+   * reordered but never dragged out of auto layout onto the freeform screen.
+   * Keep ordinary flow insertion intact, but turn a root/background release
+   * into an absolute-container move. Space preserves the current parent;
+   * Control drops into an auto-layout parent as Ignore auto layout. */
+  function flowMoveTargetForPoint(
+    el,
+    clientX,
+    clientY,
+    excludeEls,
+    keepCurrentParent,
+    ignoreTargetAutoLayout,
+  ) {
+    if (!el || !el.parentElement) return null;
+    var currentParent = el.parentElement;
+    var dragged: Element[] = [el].concat(excludeEls || []);
+    var parentRect = currentParent.getBoundingClientRect();
+    var pointerOutsideCurrentParent =
+      clientX < parentRect.left ||
+      clientX > parentRect.right ||
+      clientY < parentRect.top ||
+      clientY > parentRect.bottom;
+
+    if (keepCurrentParent && pointerOutsideCurrentParent) {
+      var retainedSlot = nearestChildInsertionTarget(
+        currentParent,
+        clientX,
+        clientY,
+        dragged,
+      );
+      return (
+        retainedSlot || {
+          anchor: currentParent,
+          placement: "inside",
+          axis: parentFlowAxis(currentParent),
+          dropMode: "flow-insert",
+        }
+      );
+    }
+
+    var target = reorderTargetForPoint(el, clientX, clientY, excludeEls);
+    var container = dropContainerForTarget(target);
+
+    // Figma Ignore auto layout: Control-drag into an auto-layout frame keeps
+    // the new parent but excludes the object from its flow.
+    if (
+      ignoreTargetAutoLayout &&
+      container &&
+      container !== document.body &&
+      isAutoLayoutElement(container)
+    ) {
+      return {
+        anchor: container,
+        placement: "inside",
+        axis: parentFlowAxis(container),
+        dropMode: "absolute-container",
+      };
+    }
+
+    // A target whose resolved container is body is the freeform screen/root,
+    // not an auto-layout list. Reparent inside body and preserve the release
+    // point with absolute positioning instead of inserting before/after a
+    // top-level frame as another flow child.
+    if (
+      currentParent !== document.body &&
+      (container === document.body ||
+        container === document.documentElement ||
+        target?.anchor === document.body)
+    ) {
+      return {
+        anchor: document.body,
+        placement: "inside",
+        axis: "y",
+        dropMode: "absolute-container",
+      };
+    }
+
+    // Flow child dropped into a plain container: match the absolute-drag path
+    // by converting that container to auto layout before the structural move.
+    if (
+      target &&
+      target.dropMode === "flow-insert" &&
+      container &&
+      container !== document.body &&
+      isContainerDropTarget(container) &&
+      !isAutoLayoutElement(container)
+    ) {
+      target.needsAutoLayoutConversion = true;
+      target.conversionTarget = container;
+    }
+    return target;
+  }
+
+  /** Apply Figma's Control-drag "Ignore auto layout" modifier to an
+   * absolute/freeform drag target. The flow-origin path above already made
+   * this conversion, but the ordinary absolute drag path used to ignore the
+   * modifier and strip position/left/top on drop. Resolve to the auto-layout
+   * container itself so the object keeps absolute positioning inside its new
+   * parent, regardless of whether the pointer is over a child insertion slot
+   * or the container background. */
+  function ignoreAutoLayoutForDropTarget(target) {
+    var container = dropContainerForTarget(target);
+    if (
+      !target ||
+      !container ||
+      container === document.body ||
+      !isAutoLayoutElement(container)
+    ) {
+      return target;
+    }
+    return {
+      anchor: container,
+      placement: "inside",
+      axis: parentFlowAxis(container),
+      dropMode: "absolute-container",
+    };
+  }
+
   // Accepts a single element or an array (group drags temporarily disable
   // pointer-events on EVERY dragged member so the hit test sees what's
   // underneath the whole group, not a sibling member riding along under the
@@ -6374,6 +7143,24 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     for (var i = 0; i < ABS_POSITION_INLINE_PROPS.length; i += 1) {
       htmlEl.style.removeProperty(ABS_POSITION_INLINE_PROPS[i]);
     }
+    // Utility classes and authored stylesheets can still resolve the member
+    // to absolute/fixed after the inline properties are removed. The host
+    // strips those source declarations in the same structural history step,
+    // but waiting for its in-place document round-trip leaves one rendered
+    // frame where the optimistically reparented node is still absolute and
+    // appears to jump or overlap. Override only that residual computed state
+    // until the source replacement arrives. Inline-authored absolute nodes
+    // naturally compute as static after the removal and keep the historical
+    // empty-inline-style behavior.
+    var afterRemoval = window.getComputedStyle(htmlEl).position;
+    if (afterRemoval === "absolute" || afterRemoval === "fixed") {
+      // An authored stylesheet may carry !important, so the optimistic
+      // override must match that priority. Tell the host to persist the same
+      // narrow override; otherwise its source round-trip would re-apply the
+      // stylesheet and pop the newly-flowed child back out of auto layout.
+      htmlEl.style.setProperty("position", "static", "important");
+      target.forceFlowPositionOverride = true;
+    }
   }
 
   // Absolute-container nest rebase: an "absolute-container" drop keeps the
@@ -6395,6 +7182,11 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
   // (transform-inflated) bounding box.
   function rebaseAbsoluteMemberForContainerDrop(el, target): void {
     if (!el || !target || target.dropMode !== "absolute-container") return;
+    // Flow children are prepared directly in the destination containing-block
+    // coordinate space immediately before their DOM move. Rebasing those
+    // coordinates as if they came from an old absolute containing block would
+    // apply the parent-origin delta twice.
+    if (target.absoluteCoordinatesPrepared) return;
     var container = dropContainerForTarget(target);
     if (!container || container === document.body || container === el) return;
     if (el.contains && el.contains(container)) return;
@@ -6405,12 +7197,20 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     // coordinates (border box + border widths − its own scroll offsets).
     var containerRect = container.getBoundingClientRect();
     var containerCS = window.getComputedStyle(container);
+    var boardOffsetX = designCanvasBoardSurface
+      ? designCanvasContentOffsetX
+      : 0;
+    var boardOffsetY = designCanvasBoardSurface
+      ? designCanvasContentOffsetY
+      : 0;
     var newOriginX =
-      containerRect.left +
+      containerRect.left -
+      boardOffsetX +
       readPx(containerCS.borderLeftWidth) -
       container.scrollLeft;
     var newOriginY =
-      containerRect.top +
+      containerRect.top -
+      boardOffsetY +
       readPx(containerCS.borderTopWidth) -
       container.scrollTop;
     // Current containing block origin: the member's offsetParent when it is
@@ -6432,10 +7232,30 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       if (offsetParentIsRealContainingBlock) {
         var opRect = offsetParent.getBoundingClientRect();
         var opCS = window.getComputedStyle(offsetParent);
+        // The finite board offset is applied to `body > [data-node-id]`, not
+        // to body itself. A top-level member whose containing block is the
+        // positioned body therefore still has a true origin of 0; subtracting
+        // the render offset here poisoned a frame nest by exactly one chunk
+        // (for example -4096px). Nested containing blocks do inherit the
+        // translated top-level visual space, so only those need normalization.
+        var oldContainingBlockOffsetX =
+          designCanvasBoardSurface && offsetParent !== document.body
+            ? boardOffsetX
+            : 0;
+        var oldContainingBlockOffsetY =
+          designCanvasBoardSurface && offsetParent !== document.body
+            ? boardOffsetY
+            : 0;
         oldOriginX =
-          opRect.left + readPx(opCS.borderLeftWidth) - offsetParent.scrollLeft;
+          opRect.left -
+          oldContainingBlockOffsetX +
+          readPx(opCS.borderLeftWidth) -
+          offsetParent.scrollLeft;
         oldOriginY =
-          opRect.top + readPx(opCS.borderTopWidth) - offsetParent.scrollTop;
+          opRect.top -
+          oldContainingBlockOffsetY +
+          readPx(opCS.borderTopWidth) -
+          offsetParent.scrollTop;
       }
     }
     var currentLeft = readPx(htmlEl.style.left || cs.left);
@@ -6444,6 +7264,59 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     htmlEl.style.top = currentTop + (oldOriginY - newOriginY) + "px";
   }
 
+  /** Convert flow members to absolute positioning at their drag release point
+   * before moving them into a freeform root/absolute container. The DOM move
+   * happens synchronously in the same event turn, so no intermediate frame is
+   * painted; postVisualStructureChange then measures the final geometry for
+   * the source persistence/undo entry. */
+  function prepareFlowMembersForAbsoluteDrop(
+    members: Element[],
+    target,
+    startRects: DOMRect[],
+    gestureStartRect: DOMRect,
+    pointerOffset: { x: number; y: number },
+    clientX: number,
+    clientY: number,
+  ): void {
+    if (!target || target.dropMode !== "absolute-container") return;
+    var container = dropContainerForTarget(target);
+    if (!container) return;
+    var containerRect = container.getBoundingClientRect();
+    var containerCS = window.getComputedStyle(container);
+    var containerIsBodyContainingBlock = true;
+    if (container === document.body) {
+      containerIsBodyContainingBlock =
+        containerCS.position !== "static" ||
+        containerCS.transform !== "none" ||
+        (containerCS.getPropertyValue("translate") || "none") !== "none";
+    }
+    var originX = containerIsBodyContainingBlock
+      ? containerRect.left +
+        readPx(containerCS.borderLeftWidth) -
+        container.scrollLeft
+      : -(window.scrollX || 0);
+    var originY = containerIsBodyContainingBlock
+      ? containerRect.top +
+        readPx(containerCS.borderTopWidth) -
+        container.scrollTop
+      : -(window.scrollY || 0);
+    var desiredGestureLeft = clientX - pointerOffset.x;
+    var desiredGestureTop = clientY - pointerOffset.y;
+    var deltaX = desiredGestureLeft - gestureStartRect.left;
+    var deltaY = desiredGestureTop - gestureStartRect.top;
+
+    members.forEach(function (member, index) {
+      var startRect = startRects[index] || member.getBoundingClientRect();
+      var htmlEl = member as HTMLElement;
+      htmlEl.style.position = "absolute";
+      htmlEl.style.left = Math.round(startRect.left + deltaX - originX) + "px";
+      htmlEl.style.top = Math.round(startRect.top + deltaY - originY) + "px";
+      htmlEl.style.removeProperty("right");
+      htmlEl.style.removeProperty("bottom");
+    });
+    target.absoluteCoordinatesPrepared = true;
+  }
+
   function applyRuntimeReorder(el, target) {
     if (!el || !target || !target.anchor || !target.anchor.parentElement)
       return;
@@ -6487,9 +7360,11 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         anchorSourceId: getSourceId(target.anchor),
         placement: target.placement,
         dropMode: target.dropMode || "flow-insert",
+        forceFlowPositionOverride: Boolean(target.forceFlowPositionOverride),
         sourceRect: rectInfoForElement(el),
         anchorRect: rectInfoForElement(target.anchor),
         payload: getElementInfo(el),
+        anchorPayload: getElementInfo(target.anchor),
       },
       "*",
     );
@@ -6756,7 +7631,11 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
   // pointer went down on when this drag preserves a 2+ selection instead of
   // collapsing to one element (see beginPotentialShieldDrag's group branch).
   // Defaults to selectedEl — the selection-overlay drag path.
-  function startMove(e, gestureElParam?: Element) {
+  function startMove(
+    e,
+    gestureElParam?: Element,
+    pointerStartParam?: { clientX: number; clientY: number },
+  ) {
     var gestureEl = gestureElParam || selectedEl;
     if (!gestureEl) return;
     if (isLayerInteractionBlocked(gestureEl)) return;
@@ -6870,11 +7749,18 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       // Snapshot the element being reordered so a concurrent select-element or
       // clear-selection postMessage cannot mutate the wrong element mid-drag.
       var reorderEl = gestureEl;
-      var currentTarget = reorderTargetForPoint(
+      var reorderGroupStartRects = groupEls.map(function (member) {
+        return member.getBoundingClientRect();
+      });
+      var reorderGestureStartRect = reorderEl.getBoundingClientRect();
+      var keepCurrentFlowParent = bridgeSpaceKeyPressed;
+      var currentTarget = flowMoveTargetForPoint(
         reorderEl,
         e.clientX,
         e.clientY,
         groupOthers,
+        keepCurrentFlowParent,
+        Boolean(e.ctrlKey),
       );
       showInsertionGuideFor(currentTarget);
       // Cross-screen drag state: true when the pointer is outside this iframe's
@@ -6885,9 +7771,10 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       var reorderSourceId = getSourceId(reorderEl);
       var reorderStyleSnapshot = collectPortableStyleSnapshot(reorderEl);
       var reorderRect = reorderEl.getBoundingClientRect();
+      var reorderPointerStart = pointerStartParam || e;
       var reorderPointerOffset = {
-        x: e.clientX - reorderRect.left,
-        y: e.clientY - reorderRect.top,
+        x: reorderPointerStart.clientX - reorderRect.left,
+        y: reorderPointerStart.clientY - reorderRect.top,
       };
       function onReorderMove(ev) {
         var vw = window.innerWidth;
@@ -6924,7 +7811,14 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
           showTransformBadge("Move layer", cx, cy);
         } else {
           // Cursor is inside this iframe — use existing in-iframe behavior.
-          currentTarget = reorderTargetForPoint(reorderEl, cx, cy, groupOthers);
+          currentTarget = flowMoveTargetForPoint(
+            reorderEl,
+            cx,
+            cy,
+            groupOthers,
+            keepCurrentFlowParent,
+            Boolean(ev.ctrlKey),
+          );
           showInsertionGuideFor(currentTarget);
           showTransformBadge(currentTarget ? "Move layer" : "Move", cx, cy);
         }
@@ -6933,6 +7827,7 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         document.removeEventListener(events.move, onReorderMove, true);
         document.removeEventListener(events.up, onReorderUp, true);
         document.removeEventListener("keydown", onReorderKeyDown, true);
+        document.removeEventListener("keyup", onReorderKeyUp, true);
         clearActiveDragCancel(onReorderEscape);
       }
       function onReorderEscape() {
@@ -6959,11 +7854,21 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         return true;
       }
       function onReorderKeyDown(ev) {
+        if (ev.code === "Space" || ev.key === " ") {
+          keepCurrentFlowParent = true;
+          ev.preventDefault();
+          return;
+        }
         if (ev.key === "Escape") {
           stopNativeInteraction(ev);
           onReorderEscape();
         }
       }
+      function onReorderKeyUp(ev) {
+        if (ev.code !== "Space" && ev.key !== " ") return;
+        keepCurrentFlowParent = false;
+        ev.preventDefault();
+      }
       function onReorderUp(ev) {
         cleanupReorderDrag();
         hideTransformBadge();
@@ -7003,6 +7908,14 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         // already clears cross-screen state on re-entry so checking the
         // momentary excursion flag here would wrongly drop the element nowhere.
         if (outsideOnDrop) return;
+        currentTarget = flowMoveTargetForPoint(
+          reorderEl,
+          cx,
+          cy,
+          groupOthers,
+          keepCurrentFlowParent,
+          Boolean(ev?.ctrlKey),
+        );
         if (!currentTarget) {
           // No valid drop target — clean up the clone if one was inserted so
           // no ghost element is left in the DOM.
@@ -7019,6 +7932,24 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
           }
           return;
         }
+        if (
+          currentTarget.needsAutoLayoutConversion &&
+          currentTarget.conversionTarget
+        ) {
+          applyAutoLayoutConversionForDrop(
+            currentTarget.conversionTarget,
+            groupEls,
+          );
+        }
+        prepareFlowMembersForAbsoluteDrop(
+          groupEls,
+          currentTarget,
+          reorderGroupStartRects,
+          reorderGestureStartRect,
+          reorderPointerOffset,
+          cx,
+          cy,
+        );
         if (duplicatedForDrag) {
           applyRuntimeReorder(reorderEl, currentTarget);
           postVisualDuplicateChange(
@@ -7058,6 +7989,7 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       document.addEventListener(events.move, onReorderMove, true);
       document.addEventListener(events.up, onReorderUp, true);
       document.addEventListener("keydown", onReorderKeyDown, true);
+      document.addEventListener("keyup", onReorderKeyUp, true);
       setActiveDragCancel(onReorderEscape);
       return;
     }
@@ -7120,6 +8052,34 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     if (!duplicatedForDrag && !isGroupDrag) {
       postCrossScreenDrag("start", dragEl, e);
     }
+    // rAF-coalesce the "move" phase postMessage: a raw mousemove/pointermove
+    // stream can fire well above 60/s on a high-poll-rate mouse or trackpad,
+    // and every tick of this handler already recomputes a getBoundingClientRect
+    // for postCrossScreenDrag — batching to one postMessage per animation
+    // frame matches the parent's own equivalent coalescing (see
+    // MultiScreenCanvas.tsx's rAF-batched cross-screen hit-test) without
+    // changing what gets sent, only how often. cleanupMoveDrag cancels any
+    // still-pending tick so a stale "move" can never post after "end"/"cancel".
+    var crossScreenDragMoveScheduled = false;
+    var crossScreenDragMovePendingEv: {
+      clientX: number;
+      clientY: number;
+    } | null = null;
+    function flushCrossScreenDragMove() {
+      crossScreenDragMoveScheduled = false;
+      var pendingEv = crossScreenDragMovePendingEv;
+      crossScreenDragMovePendingEv = null;
+      if (pendingEv) postCrossScreenDrag("move", dragEl, pendingEv);
+    }
+    function scheduleCrossScreenDragMove(ev): void {
+      crossScreenDragMovePendingEv = {
+        clientX: ev.clientX,
+        clientY: ev.clientY,
+      };
+      if (crossScreenDragMoveScheduled) return;
+      crossScreenDragMoveScheduled = true;
+      window.requestAnimationFrame(flushCrossScreenDragMove);
+    }
     function onMove(ev) {
       if (
         !moved &&
@@ -7174,7 +8134,7 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         state.el.style.top = Math.round(state.originTop + appliedDy) + "px";
       });
       if (!duplicatedForDrag && !isGroupDrag) {
-        postCrossScreenDrag("move", dragEl, ev);
+        scheduleCrossScreenDragMove(ev);
       }
       if (
         !duplicatedForDrag &&
@@ -7184,14 +8144,20 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         hideInsertionGuide();
         setMembersOpacity(null);
       } else {
-        currentAutoLayoutTarget = !duplicatedForDrag
-          ? autoLayoutInsertionTargetForPoint(
-              dragEl,
-              ev.clientX,
-              ev.clientY,
-              groupOthers,
-            )
-          : null;
+        currentAutoLayoutTarget =
+          !duplicatedForDrag && !bridgeSpaceKeyPressed
+            ? autoLayoutInsertionTargetForPoint(
+                dragEl,
+                ev.clientX,
+                ev.clientY,
+                groupOthers,
+              )
+            : null;
+        if (currentAutoLayoutTarget && ev.ctrlKey) {
+          currentAutoLayoutTarget = ignoreAutoLayoutForDropTarget(
+            currentAutoLayoutTarget,
+          );
+        }
         if (currentAutoLayoutTarget) {
           showInsertionGuideFor(currentAutoLayoutTarget);
           setMembersOpacity("0.4");
@@ -7235,6 +8201,10 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       document.removeEventListener(events.up, onUp, true);
       document.removeEventListener("keydown", onMoveKeyDown, true);
       clearActiveDragCancel(cancelMoveDrag);
+      // Drop any rAF-scheduled "move" tick so it can never fire and post
+      // after this gesture's "end"/"cancel" phase has already gone out.
+      crossScreenDragMoveScheduled = false;
+      crossScreenDragMovePendingEv = null;
     }
     function cancelMoveDrag() {
       cleanupMoveDrag();
@@ -7286,16 +8256,32 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         restoreSourceDragPosition();
         return;
       }
-      if (ev && !duplicatedForDrag && !outsideOnDrop) {
+      if (
+        ev &&
+        !duplicatedForDrag &&
+        !outsideOnDrop &&
+        !bridgeSpaceKeyPressed
+      ) {
         var finalAutoLayoutTarget = autoLayoutInsertionTargetForPoint(
           dragEl,
           ev.clientX,
           ev.clientY,
           groupOthers,
         );
+        if (finalAutoLayoutTarget && ev.ctrlKey) {
+          finalAutoLayoutTarget = ignoreAutoLayoutForDropTarget(
+            finalAutoLayoutTarget,
+          );
+        }
         if (finalAutoLayoutTarget) {
           currentAutoLayoutTarget = finalAutoLayoutTarget;
         }
+      } else if (bridgeSpaceKeyPressed) {
+        // Space is Figma's retain-parent modifier. Absolute/freeform drags
+        // already move in their current containing-block coordinates, so
+        // suppressing the nest target keeps the existing parent while still
+        // committing the new left/top in one style change.
+        currentAutoLayoutTarget = null;
       }
       if (duplicatedForDrag && !moved) {
         // Alt-click with no real drag — remove the premature clone and restore the original selection.
@@ -7414,11 +8400,24 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     var originalInlineFontSize = resizeEl.style.fontSize;
     ensurePositionable(resizeEl);
     var cs = window.getComputedStyle(resizeEl);
-    // Bug fix: use CSS width/height (not getBoundingClientRect) for the resize
-    // origin dimensions so that rotated elements don't use the inflated
-    // axis-aligned bounding box as the starting size.
-    var originW = readPx(resizeEl.style.width || cs.width);
-    var originH = readPx(resizeEl.style.height || cs.height);
+    // Bug fix: use COMPUTED width/height (never the raw inline style string)
+    // for the resize origin dimensions. Two distinct hazards, one fix:
+    //   1. Rotated elements — getBoundingClientRect() returns the inflated
+    //      axis-aligned bounding box of the rotated box, not its own
+    //      width/height, so it can't seed the origin either.
+    //   2. Non-px inline values — an inline style of "100%" / "50vw" / "2rem"
+    //      / "auto" / "calc(...)" is NOT a pixel measurement. Reading
+    //      `resizeEl.style.width` directly and running it through
+    //      parseFloat (readPx) previously parsed "100%" as the number 100
+    //      and treated it as 100PX, so a +50px drag produced 150px instead
+    //      of correctly growing from the ~358px the element actually
+    //      rendered at. getComputedStyle always resolves to the element's
+    //      used-value size in px regardless of the authored unit (and is
+    //      unaffected by a rotate transform, unlike getBoundingClientRect),
+    //      so it's the one source that's simultaneously rotation-safe and
+    //      unit-agnostic.
+    var originW = readPx(cs.width);
+    var originH = readPx(cs.height);
     // K-scale (Figma "Scale" tool) parity: capture the element's own border
     // width and font size once at drag-start so a uniform per-tick scale
     // factor (derived from width/height growth, see nextRect below) can
@@ -7448,6 +8447,18 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     // Capture the element rotation once at drag-start so per-move projection is
     // cheap and consistent even if the transform changes during the drag.
     var resizeTheta = (currentRotation(resizeEl) * Math.PI) / 180;
+    // Figma commit-semantics parity: a resize must only ever write the
+    // axis/axes the user actually dragged. A pure vertical edge-drag (handle
+    // "n"/"s", no Shift, scale tool off) must leave width completely alone —
+    // e.g. a `width: 100%` element stays percentage-based after a
+    // height-only resize instead of being silently pinned to a px value the
+    // user never touched. These accumulate for the life of the gesture (once
+    // an axis is touched — including transiently, e.g. Shift held mid-drag
+    // then released — it stays "touched" for this gesture's commit) and
+    // gate both the live style writes in onMove and the committed style keys
+    // in onUp.
+    var widthTouched = false;
+    var heightTouched = false;
     function nextRect(ev) {
       var screenDx = ev.clientX - startX;
       var screenDy = ev.clientY - startY;
@@ -7525,15 +8536,42 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         if (handle.indexOf("n") !== -1 || handle.indexOf("s") !== -1)
           top = origin.top - (height - origin.height) / 2;
       }
-      return { left: left, top: top, width: width, height: height };
+      // Which axis/axes this handle actually drives: the handle's own
+      // letters directly touch their axis; an active aspect-ratio lock
+      // (Shift or the K-scale tool) additionally derives the OTHER axis from
+      // the touched one for a single-axis edge handle (e.g. dragging "n"
+      // with Shift held also changes width to hold the ratio). Two-letter
+      // corner handles already touch both axes regardless of the lock.
+      var handlesWidth =
+        handle.indexOf("w") !== -1 || handle.indexOf("e") !== -1;
+      var handlesHeight =
+        handle.indexOf("n") !== -1 || handle.indexOf("s") !== -1;
+      var aspectLocked = !!(ev.shiftKey || scaleToolEnabled);
+      var touchesWidth = handlesWidth || (aspectLocked && handlesHeight);
+      var touchesHeight = handlesHeight || (aspectLocked && handlesWidth);
+      return {
+        left: left,
+        top: top,
+        width: width,
+        height: height,
+        touchesWidth: touchesWidth,
+        touchesHeight: touchesHeight,
+      };
     }
     function onMove(ev) {
       if (!resizeEl) return;
       var rect = nextRect(ev);
+      if (rect.touchesWidth) widthTouched = true;
+      if (rect.touchesHeight) heightTouched = true;
       resizeEl.style.left = Math.round(rect.left) + "px";
       resizeEl.style.top = Math.round(rect.top) + "px";
-      resizeEl.style.width = Math.round(rect.width) + "px";
-      resizeEl.style.height = Math.round(rect.height) + "px";
+      // Only write width/height for an axis this gesture actually touched —
+      // writing the untouched axis every tick (even to its own unchanged
+      // origin value) would silently convert e.g. `width: 100%` to a px
+      // value on a pure vertical drag, which is exactly the "shrank instead
+      // of preserved" class of bug this fixes.
+      if (widthTouched) resizeEl.style.width = Math.round(rect.width) + "px";
+      if (heightTouched) resizeEl.style.height = Math.round(rect.height) + "px";
       if (scaleToolEnabled) {
         // Uniform scale factor: scaleToolEnabled already forces the
         // aspect-ratio lock above (nextRect), so width/origin.width and
@@ -7597,9 +8635,14 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         position: resizeEl.style.position,
         left: resizeEl.style.left,
         top: resizeEl.style.top,
-        width: resizeEl.style.width,
-        height: resizeEl.style.height,
       };
+      // Only commit width/height for an axis this gesture actually touched
+      // (see widthTouched/heightTouched above) — a pure vertical or
+      // horizontal edge-drag must not also commit a px value for the axis
+      // the user never dragged, which would silently convert e.g.
+      // `width: 100%` to a fixed px width.
+      if (widthTouched) styles.width = resizeEl.style.width;
+      if (heightTouched) styles.height = resizeEl.style.height;
       // Only include borderWidth/fontSize when the K-scale tool actually
       // changed them (originBorderWidth/originFontSize > 0 AND
       // scaleToolEnabled) — a normal resize must never introduce these keys,
@@ -7804,12 +8847,15 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         collectMoveGroupMembers(groupGestureMember).length > 1
       ) {
         suppressNextShieldClickBriefly();
-        startMove(ev, groupGestureMember);
+        startMove(ev, groupGestureMember, {
+          clientX: startX,
+          clientY: startY,
+        });
         return;
       }
       selectTarget(dragTarget, ev);
       suppressNextShieldClickBriefly();
-      startMove(ev);
+      startMove(ev, undefined, { clientX: startX, clientY: startY });
     }
     function onUp(ev) {
       clearPendingShieldDrag();
@@ -7941,6 +8987,19 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
   document.addEventListener(
     "keydown",
     function (e) {
+      if (
+        e.key === " " &&
+        e.code === "Space" &&
+        !activeTextEditEl &&
+        !isEditorTypingTarget(e.target)
+      ) {
+        bridgeSpaceKeyPressed = true;
+        if (activeDragCancel) {
+          bridgeSpaceKeyConsumedByDrag = true;
+          stopNativeInteraction(e);
+          return;
+        }
+      }
       // T25: pending-window keydown routing — a begin-text-edit is still
       // waiting for its node. Keystrokes that land in THIS document during
       // the wait belong to the upcoming text session: buffer printable
@@ -8086,6 +9145,12 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
     "keyup",
     function (e) {
       if (e.key !== " " || e.code !== "Space") return;
+      bridgeSpaceKeyPressed = false;
+      if (bridgeSpaceKeyConsumedByDrag) {
+        bridgeSpaceKeyConsumedByDrag = false;
+        stopNativeInteraction(e);
+        return;
+      }
       if (activeTextEditEl || isEditorTypingTarget(e.target)) return;
       stopNativeInteraction(e);
       (window.parent as Window).postMessage(
@@ -8317,6 +9382,45 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       }
       return;
     }
+    // Template-clone text-edit rejection (mirrors the reorder-rejection fix
+    // above): `target` here can be a raw Alpine `<template x-for>`/`x-if`
+    // runtime clone — findTextEditTarget's climb only requires every
+    // descendant tag to be inline-editable, it never checks whether the
+    // ancestor chain crosses a clone boundary, so a repeated list/card item
+    // whose own content is plain text passes straight through. Entering
+    // contenteditable on that clone lets the user type and see the change
+    // live (it's a real DOM node), but the clone has no per-instance
+    // counterpart in the static source HTML (only the single `<template>`
+    // stays there), so getSelector's live-DOM nth-of-type path — unlike
+    // hit-test.bridge.ts's source-equivalent selector builder — cannot
+    // resolve it on commit. Previously the edit silently failed on the host
+    // (error toast, or a no-op) and vanished for good on the next Alpine
+    // re-render, with no indication anything was wrong. Reject up front
+    // instead — same UX contract as the reorder-rejection badge — and fall
+    // back to selecting the nearest source-backed ancestor (typically the
+    // repeated item's container) so the user isn't left with a stale or
+    // empty selection.
+    if (!programmaticFlag && isTemplateCloneElement(target)) {
+      showRejectedDragBadge(
+        "Can't edit repeated items directly",
+        e.clientX,
+        e.clientY,
+      );
+      // No ongoing gesture here (unlike the reorder-rejection badge, which
+      // hides on the drag's own mouseup/Escape) to hide it on, so time it
+      // out on its own instead of leaving it on screen indefinitely.
+      window.setTimeout(hideTransformBadge, 1400);
+      var rejectedTextEditFallback = selectionTargetForHit(target);
+      if (
+        rejectedTextEditFallback &&
+        !isLayerInteractionBlocked(rejectedTextEditFallback)
+      ) {
+        selectedEl = rejectedTextEditFallback;
+        positionOverlay(selectionOverlay, selectedEl);
+        postElementSelect(selectedEl, e);
+      }
+      return;
+    }
     // Anchor the selection identity to the nearest source-backed element. Text
     // editing still operates on the actual target text node, but a later
     // style edit posts from selectedEl, so it must point at a patchable
@@ -8700,6 +9804,12 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
           scheduleSpacingHoverClear(e);
         }
         hideMeasurements();
+        // Re-arm the hover-info post gate below: leaving all content (e.g.
+        // pointer over empty canvas or off the iframe entirely) means the
+        // NEXT element this pointer lands on — even if it's the same one
+        // hovered before — is a genuinely new hover the host hasn't heard
+        // about since.
+        lastHoverInfoPostedEl = null;
         return;
       }
       if (hoveredEl && hoveredEl.closest("[data-agent-native-text-editing]"))
@@ -8743,11 +9853,14 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       } else {
         hideMeasurements();
       }
-      var info = getLightElementInfo(hoveredEl);
-      (window.parent as Window).postMessage(
-        { type: "element-hover", payload: info },
-        "*",
-      );
+      if (hoveredEl !== lastHoverInfoPostedEl) {
+        lastHoverInfoPostedEl = hoveredEl;
+        var info = getLightElementInfo(hoveredEl);
+        (window.parent as Window).postMessage(
+          { type: "element-hover", payload: info },
+          "*",
+        );
+      }
     },
     true,
   );
@@ -8781,7 +9894,11 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         updateSpacingOverlay(selectedEl);
         return;
       }
-      hoveredEl = null;
+      // Leaving the iframe entirely (e.g. to a panel or outside the window)
+      // must re-arm the post gate, not just clear hoveredEl — otherwise the
+      // pointer returning to this SAME element never re-posts "element-hover"
+      // and the host's hover highlight stays stuck at "nothing".
+      clearHoverGate();
       if (!spacingDrag) {
         scheduleSpacingHoverClear(e);
       }
@@ -8858,6 +9975,17 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       }
       return;
     }
+    if (e.data.type === "set-content-offset") {
+      var nextContentOffsetX = Number(e.data.x);
+      var nextContentOffsetY = Number(e.data.y);
+      designCanvasContentOffsetX = Number.isFinite(nextContentOffsetX)
+        ? nextContentOffsetX
+        : 0;
+      designCanvasContentOffsetY = Number.isFinite(nextContentOffsetY)
+        ? nextContentOffsetY
+        : 0;
+      return;
+    }
     // begin-text-edit: enter text-editing mode for the element identified by
     // nodeId immediately (no double-click needed). Used after programmatic
     // text-element creation so the user can type right away and the autosize
@@ -9165,13 +10293,28 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
       // whenever the cursor RESTED on a handle (the user only ever saw the
       // badge flash, i.e. "the value box never shows"). A same-element
       // replay must be a no-op for hover state.
-      if (target !== selectedEl) {
+      var selectionChangedByHost = target !== selectedEl;
+      if (selectionChangedByHost) {
         selectedSpacingHovered = false;
         hoveredSpacingHandleKey = "";
       }
       selectedEl = target;
       positionOverlay(selectionOverlay, target);
       if (hoveredEl === selectedEl) highlightOverlay.style.display = "none";
+      // A host-driven selection (e.g. picking a layer in the Layers panel)
+      // only ever moved the overlay above — it never sent the rich
+      // getElementInfo() payload (computedStyles, portableStyleSnapshot,
+      // gradients, etc.) back up, unlike pointer-driven selection which
+      // calls postElementSelect() immediately. The properties panel's
+      // "element-select" listener was therefore left with whatever payload
+      // (or lack of one) it already had, which surfaced as an empty Fill
+      // section and zeroed-out layout fields right after a Layers-panel
+      // click even though the same element selected by clicking the canvas
+      // rendered correctly. Post the full payload on genuine selection
+      // changes only — the `selectionChangedByHost` guard above already
+      // keeps this a no-op on the ~1-2s poll-tick replay so it can't turn
+      // into a message-spam loop.
+      if (selectionChangedByHost) postElementSelect(target);
       return;
     }
     if (e.data.type === "hover-element") {
@@ -9194,7 +10337,7 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         hoverCandidates.push(String(e.data.selector));
       }
       if (hoverCandidates.length === 0) {
-        hoveredEl = null;
+        clearHoverGate();
         highlightOverlay.style.display = "none";
         hideMeasurements();
         return;
@@ -9232,12 +10375,72 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
         hideSelectionOverlay();
       }
       if (hoveredEl && isLayerInteractionBlocked(hoveredEl)) {
-        hoveredEl = null;
+        clearHoverGate();
         highlightOverlay.style.display = "none";
       }
       applyHiddenSelectors();
       return;
     }
+    if (e.data.type === "runtime-structure-move") {
+      if (readOnly) return;
+      var runtimePlacement = String(e.data.placement || "");
+      if (
+        runtimePlacement !== "before" &&
+        runtimePlacement !== "after" &&
+        runtimePlacement !== "inside"
+      ) {
+        return;
+      }
+      var runtimeSubject = findUniqueRuntimeStructureTarget(
+        String(e.data.subjectSelector || ""),
+        typeof e.data.subjectSourceId === "string"
+          ? e.data.subjectSourceId
+          : "",
+      );
+      var runtimeAnchor = findUniqueRuntimeStructureTarget(
+        String(e.data.anchorSelector || ""),
+        typeof e.data.anchorSourceId === "string" ? e.data.anchorSourceId : "",
+      );
+      if (
+        !runtimeSubject ||
+        !runtimeAnchor ||
+        runtimeSubject === runtimeAnchor ||
+        runtimeSubject.contains(runtimeAnchor)
+      ) {
+        return;
+      }
+      if (
+        (runtimePlacement === "inside" &&
+          !isContainerDropTarget(runtimeAnchor)) ||
+        (runtimePlacement !== "inside" && !runtimeAnchor.parentElement)
+      ) {
+        return;
+      }
+      var runtimeTarget = {
+        anchor: runtimeAnchor,
+        placement: runtimePlacement,
+        axis: parentFlowAxis(
+          runtimePlacement === "inside"
+            ? runtimeAnchor
+            : runtimeAnchor.parentElement!,
+        ),
+        dropMode:
+          runtimePlacement === "inside" &&
+          isAbsolutePrimitiveContainer(runtimeAnchor)
+            ? "absolute-container"
+            : "flow-insert",
+      };
+      var runtimeOrigin = {
+        prevParent: runtimeSubject.parentElement!,
+        prevNextSibling: runtimeSubject.nextSibling,
+        prevInlinePositionStyles: snapshotInlinePositionStyles(runtimeSubject),
+      };
+      applyRuntimeReorder(runtimeSubject, runtimeTarget);
+      selectedEl = runtimeSubject;
+      positionOverlay(selectionOverlay, selectedEl);
+      postVisualStructureChange(runtimeSubject, runtimeTarget, runtimeOrigin);
+      return;
+    }
     if (e.data.type === "visual-structure-ack") {
       var move = pendingStructureMoves[e.data.requestId];
       if (!move) return;
@@ -9434,6 +10637,42 @@ declare var __DESIGN_CANVAS_BOARD_SURFACE__: boolean;
   window.addEventListener("resize", scheduleRefreshOverlays);
   applyEditorChromeScale();
 
+  if (
+    runtimeLayerSnapshotEnabled &&
+    typeof MutationObserver !== "undefined" &&
+    document.body
+  ) {
+    var runtimeLayerObserver = new MutationObserver(function (mutations) {
+      var hasMeaningfulMutation = mutations.some(
+        runtimeLayerMutationIsMeaningful,
+      );
+      if (hasMeaningfulMutation) scheduleRuntimeLayerSnapshot();
+    });
+    runtimeLayerObserver.observe(document.body, {
+      attributes: true,
+      attributeOldValue: true,
+      childList: true,
+      characterData: true,
+      subtree: true,
+      attributeFilter: [
+        "aria-label",
+        "class",
+        "data-agent-native-component",
+        "data-agent-native-layer-name",
+        "data-an-primitive",
+        "data-component-name",
+        "data-source-column",
+        "data-source-file",
+        "data-source-line",
+        "hidden",
+        "id",
+        "style",
+        "title",
+      ],
+    });
+  }
+  if (runtimeLayerSnapshotEnabled) scheduleRuntimeLayerSnapshot();
+
   // One-time ready signal: tells the host that every message listener above is
   // now attached, so one-shot commands (begin-text-edit, set-editor-chrome-scale,
   // style-change, delete-element, replace-document-content) sent immediately
diff --git a/templates/design/app/components/design/bridge/embedded-wheel.bridge.ts b/templates/design/app/components/design/bridge/embedded-wheel.bridge.ts
index b505726646..c7aa41ad79 100644
--- a/templates/design/app/components/design/bridge/embedded-wheel.bridge.ts
+++ b/templates/design/app/components/design/bridge/embedded-wheel.bridge.ts
@@ -24,6 +24,8 @@
  * Protocol (parent → iframe):
  *
  *   { type: 'embedded-canvas-pan-mode', leftButtonEnabled }
+ *   { type: 'embedded-canvas-gesture-mode', wheelEnabled,
+ *     spaceKeyForwardingEnabled }
  *   { type: 'embedded-canvas-pan-cancel' }
  *
  * Rules:
@@ -244,6 +246,11 @@ declare var __EMBEDDED_SPACE_KEY_FORWARDING_ENABLED__: boolean;
     }
     if (e.data.type === "embedded-canvas-pan-mode") {
       leftButtonEnabled = !!e.data.leftButtonEnabled;
+      return;
+    }
+    if (e.data.type === "embedded-canvas-gesture-mode") {
+      wheelEnabled = !!e.data.wheelEnabled;
+      spaceKeyForwardingEnabled = !!e.data.spaceKeyForwardingEnabled;
     }
   }
 
diff --git a/templates/design/app/components/design/bridge/hit-test.bridge.ts b/templates/design/app/components/design/bridge/hit-test.bridge.ts
index b2b0d77b16..0e8913dcb7 100644
--- a/templates/design/app/components/design/bridge/hit-test.bridge.ts
+++ b/templates/design/app/components/design/bridge/hit-test.bridge.ts
@@ -251,7 +251,12 @@
       el.getAttribute("data-agent-native-primitive") ||
       ""
     ).toLowerCase();
-    if (primitive !== "rectangle" && primitive !== "rect") return false;
+    if (
+      primitive !== "rectangle" &&
+      primitive !== "rect" &&
+      primitive !== "frame"
+    )
+      return false;
     var cs = window.getComputedStyle(el);
     return cs.position === "absolute" || cs.position === "fixed";
   }
diff --git a/templates/design/app/components/design/bridge/motion-preview.bridge.ts b/templates/design/app/components/design/bridge/motion-preview.bridge.ts
index 676531c4d0..e9fb0a3f83 100644
--- a/templates/design/app/components/design/bridge/motion-preview.bridge.ts
+++ b/templates/design/app/components/design/bridge/motion-preview.bridge.ts
@@ -66,6 +66,26 @@
   var touchedProps: Record<string, string[]> = {};
   // Map of nodeId -> property -> original inline style value.
   var originalInlineValues: Record<string, Record<string, string>> = {};
+  // Map of nodeId -> resolved element, so applyPreview's per-track lookup
+  // during scrub/playback (driven by the parent's own rAF loop — one
+  // "motion-preview" message per frame) does one attribute-selector
+  // querySelector per node ONCE instead of once per track on every single
+  // frame. Invalidated (falls through to a fresh querySelector) whenever the
+  // cached element is no longer in the document — e.g. a host-applied edit
+  // replaced the node — so a stale reference never silently no-ops a track.
+  // Reset alongside the other per-load state in clearPreview so a reload
+  // after the previewed screen's DOM changes always re-resolves.
+  var elementCache: Record<string, HTMLElement | null> = {};
+
+  function resolveTrackElement(nodeId: string): HTMLElement | null {
+    var cached = elementCache[nodeId];
+    if (cached && document.contains(cached)) return cached;
+    var el = document.querySelector(
+      '[data-agent-native-node-id="' + nodeId + '"]',
+    ) as HTMLElement | null;
+    elementCache[nodeId] = el;
+    return el;
+  }
 
   function camelizeProp(prop: string): string {
     return String(prop).replace(/-([a-z])/g, function (_m: string, c: string) {
@@ -673,9 +693,7 @@
   function applyPreview(t: number): void {
     for (var i = 0; i < loadedTracks.length; i++) {
       var track = loadedTracks[i];
-      var el = document.querySelector(
-        '[data-agent-native-node-id="' + track.targetNodeId + '"]',
-      ) as HTMLElement | null;
+      var el = resolveTrackElement(track.targetNodeId);
       if (!el) continue;
       var value = interpolate(track.keyframes, trackLocalT(track, t));
       if (value === "") continue;
@@ -700,9 +718,7 @@
   function clearPreview(): void {
     var nodeIds = Object.keys(touchedProps);
     for (var i = 0; i < nodeIds.length; i++) {
-      var el = document.querySelector(
-        '[data-agent-native-node-id="' + nodeIds[i] + '"]',
-      ) as HTMLElement | null;
+      var el = resolveTrackElement(nodeIds[i]);
       if (!el) continue;
       var props = touchedProps[nodeIds[i]];
       for (var j = 0; j < props.length; j++) {
@@ -718,6 +734,7 @@
     loadedTracks = [];
     loadedDefaultEase = "ease";
     loadedTimelineDurationMs = null;
+    elementCache = {};
   }
 
   // Last previewed playhead position, so reloading the track list (which
diff --git a/templates/design/app/components/design/bridge/reparent-matrix.guard.spec.ts b/templates/design/app/components/design/bridge/reparent-matrix.guard.spec.ts
new file mode 100644
index 0000000000..4d92b288b4
--- /dev/null
+++ b/templates/design/app/components/design/bridge/reparent-matrix.guard.spec.ts
@@ -0,0 +1,504 @@
+import { fileURLToPath } from "node:url";
+
+import { chromium, type Browser, type Page } from "@playwright/test";
+import { buildSync } from "esbuild";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import {
+  ensureCodeLayerNodeIdsInHtml,
+  moveNodeBetweenDocuments,
+} from "../../../../shared/code-layer";
+import {
+  buildRuntimeReactStructureMoveHandoff,
+  resolveRuntimeStructureMoveExecutionMode,
+} from "../../../pages/design-editor/react-semantic-handoff";
+
+const editorChromeBridgeSource = buildSync({
+  entryPoints: [
+    fileURLToPath(new URL("./editor-chrome.bridge.ts", import.meta.url)),
+  ],
+  bundle: true,
+  format: "iife",
+  platform: "browser",
+  target: "es2020",
+  write: false,
+}).outputFiles[0]?.text;
+
+function hydratedBridge(): string {
+  if (!editorChromeBridgeSource) {
+    throw new Error("Failed to compile editor chrome bridge for matrix test");
+  }
+  return editorChromeBridgeSource
+    .replace("__READ_ONLY__", "false")
+    .replace("__TEXT_EDITING_ENABLED__", "false")
+    .replace("__EDITOR_CHROME_SCALE_X__", "1")
+    .replace("__EDITOR_CHROME_SCALE_Y__", "1")
+    .replace("__DESIGN_CANVAS_SCREEN_ID__", JSON.stringify("matrix-screen"))
+    .replace("__DESIGN_CANVAS_BOARD_SURFACE__", "false")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_X__", "0")
+    .replace("__DESIGN_CANVAS_CONTENT_OFFSET_Y__", "0")
+    .replace("__RUNTIME_LAYER_SNAPSHOT_ENABLED__", "false");
+}
+
+async function installBridge(page: Page): Promise<void> {
+  await page.addScriptTag({ content: hydratedBridge() });
+  await page.waitForSelector('[data-agent-native-edit-overlay="shield"]');
+  await page.evaluate(() => {
+    (window as Window & { __matrixMessages?: unknown[] }).__matrixMessages = [];
+    window.addEventListener("message", (event) => {
+      (
+        window as Window & { __matrixMessages?: unknown[] }
+      ).__matrixMessages?.push(event.data);
+    });
+  });
+}
+
+async function dragCenterTo(
+  page: Page,
+  selector: string,
+  target: { x: number; y: number },
+  modifier?: "Control" | "Space",
+): Promise<{ left: number; top: number }> {
+  const box = await page.locator(selector).boundingBox();
+  expect(box).not.toBeNull();
+  const startX = box!.x + box!.width / 2;
+  const startY = box!.y + box!.height / 2;
+  await page.mouse.click(startX, startY);
+  await page.mouse.move(startX, startY);
+  await page.mouse.down();
+  if (modifier) await page.keyboard.down(modifier);
+  await page.mouse.move(startX + 6, startY + 6, { steps: 2 });
+  await page.mouse.move(target.x, target.y, { steps: 8 });
+  const beforeRelease = await page.locator(selector).evaluate((element) => {
+    const rect = element.getBoundingClientRect();
+    return { left: rect.left, top: rect.top };
+  });
+  await page.mouse.up();
+  if (modifier) await page.keyboard.up(modifier);
+  await page.waitForTimeout(40);
+  return beforeRelease;
+}
+
+function sourceId(html: string, layerName: string): string {
+  const match = html.match(
+    new RegExp(
+      `data-agent-native-layer-name=["']${layerName}["'][^>]*data-agent-native-node-id=["']([^"']+)`,
+    ),
+  );
+  if (match?.[1]) return match[1];
+  const reverse = html.match(
+    new RegExp(
+      `data-agent-native-node-id=["']([^"']+)["'][^>]*data-agent-native-layer-name=["']${layerName}["']`,
+    ),
+  );
+  if (!reverse?.[1]) throw new Error(`Missing node id for ${layerName}`);
+  return reverse[1];
+}
+
+describe("Chromium reparent matrix", () => {
+  let browser: Browser;
+
+  beforeAll(async () => {
+    browser = await chromium.launch({ headless: true });
+  });
+
+  afterAll(async () => {
+    await browser.close();
+  });
+
+  it(
+    "moves absolute layers into freeform, row, column, wrap, and grid parents with the correct geometry and flow cleanup",
+    { timeout: 30_000 },
+    async () => {
+      const layouts = [
+        {
+          name: "freeform",
+          targetStyle:
+            "position:absolute;left:300px;top:80px;width:300px;height:200px;border:2px solid #999",
+          primitive: ' data-an-primitive="frame"',
+          expectedPosition: "absolute",
+          expectedDropMode: "absolute-container",
+        },
+        {
+          name: "row",
+          targetStyle:
+            "position:absolute;left:300px;top:80px;width:300px;height:200px;display:flex;flex-direction:row;gap:12px;padding:12px",
+          primitive: "",
+          expectedPosition: "static",
+          expectedDropMode: "flow-insert",
+        },
+        {
+          name: "column",
+          targetStyle:
+            "position:absolute;left:300px;top:80px;width:300px;height:200px;display:flex;flex-direction:column;gap:12px;padding:12px",
+          primitive: "",
+          expectedPosition: "static",
+          expectedDropMode: "flow-insert",
+        },
+        {
+          name: "wrap",
+          targetStyle:
+            "position:absolute;left:300px;top:80px;width:300px;height:200px;display:flex;flex-direction:row;flex-wrap:wrap;gap:12px;padding:12px",
+          primitive: "",
+          expectedPosition: "static",
+          expectedDropMode: "flow-insert",
+        },
+        {
+          name: "grid",
+          targetStyle:
+            "position:absolute;left:300px;top:80px;width:300px;height:200px;display:grid;grid-template-columns:repeat(2,minmax(0,1fr));grid-auto-rows:60px;gap:12px;padding:12px",
+          primitive: "",
+          expectedPosition: "static",
+          expectedDropMode: "flow-insert",
+        },
+      ] as const;
+
+      for (const layout of layouts) {
+        const page = await browser.newPage({
+          viewport: { width: 900, height: 700 },
+        });
+        const pageErrors: string[] = [];
+        page.on("pageerror", (error) => pageErrors.push(error.message));
+        await page.setContent(`<!doctype html><html><head><style>
+          html,body { margin:0;width:100%;height:100%; }
+          body { position:relative; }
+          #source { position:absolute;left:40px;top:420px;width:80px;height:44px;background:#6366f1; }
+          #target { ${layout.targetStyle};box-sizing:border-box;background:#eef2ff; }
+          .peer { width:70px;height:50px;background:#a5b4fc; }
+        </style></head><body>
+          <div id="source" data-agent-native-node-id="source">Source</div>
+          <div id="target" data-agent-native-node-id="target"${layout.primitive}>
+            <div id="peer-a" class="peer" data-agent-native-node-id="peer-a">A</div>
+            <div id="peer-b" class="peer" data-agent-native-node-id="peer-b">B</div>
+          </div>
+        </body></html>`);
+        await installBridge(page);
+
+        const beforeRelease = await dragCenterTo(page, "#source", {
+          x: 530,
+          y: 240,
+        });
+        const result = await page.evaluate(() => {
+          const source = document.querySelector<HTMLElement>("#source")!;
+          const target = document.querySelector<HTMLElement>("#target")!;
+          const sourceRect = source.getBoundingClientRect();
+          const targetRect = target.getBoundingClientRect();
+          const targetStyle = getComputedStyle(target);
+          const messages = (
+            window as Window & { __matrixMessages?: Record<string, unknown>[] }
+          ).__matrixMessages!;
+          const structureMessages = messages.filter(
+            (message) => message.type === "visual-structure-change",
+          );
+          const structure = structureMessages[structureMessages.length - 1] as
+            | {
+                dropMode?: string;
+                forceFlowPositionOverride?: boolean;
+              }
+            | undefined;
+          return {
+            parentId: source.parentElement?.id,
+            position: window.getComputedStyle(source).position,
+            inlineLeft: source.style.left,
+            inlineTop: source.style.top,
+            rect: { left: sourceRect.left, top: sourceRect.top },
+            target: {
+              left: targetRect.left,
+              top: targetRect.top,
+              borderLeft: Number.parseFloat(targetStyle.borderLeftWidth) || 0,
+              borderTop: Number.parseFloat(targetStyle.borderTopWidth) || 0,
+            },
+            order: Array.from(target.children).map((child) => child.id),
+            dropMode: structure?.dropMode,
+            forceFlowPositionOverride: structure?.forceFlowPositionOverride,
+          };
+        });
+
+        expect(result.parentId, layout.name).toBe("target");
+        expect(result.dropMode, layout.name).toBe(layout.expectedDropMode);
+        if (layout.expectedPosition === "absolute") {
+          expect(result.position, layout.name).toBe("absolute");
+          // Reparenting into a new containing block must not add a one-frame
+          // jump: the last dragged geometry is the post-drop geometry. Smart
+          // guides may legitimately snap that geometry by up to 6px before
+          // release, so compare the two rendered states directly.
+          expect(result.rect.left, layout.name).toBeCloseTo(
+            beforeRelease.left,
+            5,
+          );
+          expect(result.rect.top, layout.name).toBeCloseTo(
+            beforeRelease.top,
+            5,
+          );
+          expect(Number.parseFloat(result.inlineLeft), layout.name).toBeCloseTo(
+            result.rect.left - result.target.left - result.target.borderLeft,
+            0,
+          );
+          expect(Number.parseFloat(result.inlineTop), layout.name).toBeCloseTo(
+            result.rect.top - result.target.top - result.target.borderTop,
+            0,
+          );
+        } else {
+          expect(result.position, layout.name).not.toBe("absolute");
+          expect(result.forceFlowPositionOverride, layout.name).toBe(true);
+          expect(result.inlineLeft, layout.name).toBe("");
+          expect(result.inlineTop, layout.name).toBe("");
+          expect(result.order, layout.name).toContain("source");
+        }
+        expect(pageErrors, layout.name).toEqual([]);
+        await page.close();
+      }
+    },
+  );
+
+  it(
+    "moves flow children to the freeform screen root and back into auto layout without losing the grab offset",
+    { timeout: 30_000 },
+    async () => {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      await page.setContent(`<!doctype html><html><head><style>
+        html,body { margin:0;width:100%;height:100%; }
+        body { position:relative; }
+        .flow { position:absolute;top:50px;width:220px;height:180px;padding:12px;display:flex;flex-direction:column;gap:8px;box-sizing:border-box; }
+        #from { left:40px;background:#f4f4f5; }
+        #to { left:360px;background:#eef2ff; }
+        #item { width:100px;height:44px;background:#6366f1; }
+      </style></head><body>
+        <div id="from" class="flow" data-agent-native-node-id="from"><div id="item" data-agent-native-node-id="item">Item</div></div>
+        <div id="to" class="flow" data-agent-native-node-id="to"></div>
+      </body></html>`);
+      await installBridge(page);
+
+      await dragCenterTo(page, "#item", { x: 760, y: 560 });
+      const root = await page.locator("#item").evaluate((element) => {
+        const item = element as HTMLElement;
+        const rect = item.getBoundingClientRect();
+        return {
+          parent: item.parentElement?.tagName,
+          position: getComputedStyle(item).position,
+          left: rect.left,
+          top: rect.top,
+        };
+      });
+      expect(root).toMatchObject({ parent: "BODY", position: "absolute" });
+      expect(root.left).toBeCloseTo(710, 0);
+      expect(root.top).toBeCloseTo(538, 0);
+
+      await dragCenterTo(page, "#item", { x: 470, y: 120 });
+      const flowed = await page.locator("#item").evaluate((element) => {
+        const item = element as HTMLElement;
+        return {
+          parent: item.parentElement?.id,
+          position: getComputedStyle(item).position,
+          left: item.style.left,
+          top: item.style.top,
+        };
+      });
+      expect(flowed.parent).toBe("to");
+      expect(flowed.position).not.toBe("absolute");
+      expect(flowed.left).toBe("");
+      expect(flowed.top).toBe("");
+      await page.close();
+    },
+  );
+
+  it(
+    "honors Control Ignore Auto Layout and Space retain-parent for absolute drags",
+    { timeout: 30_000 },
+    async () => {
+      const page = await browser.newPage({
+        viewport: { width: 900, height: 700 },
+      });
+      await page.setContent(`<!doctype html><html><head><style>
+        html,body { margin:0;width:100%;height:100%; }
+        body { position:relative; }
+        #origin { position:absolute;left:30px;top:330px;width:240px;height:220px;background:#fafafa; }
+        #control,#space { position:absolute;left:20px;width:90px;height:44px; }
+        #control { top:20px;background:#22c55e; }
+        #space { top:90px;background:#6366f1; }
+        #target { position:absolute;left:380px;top:80px;width:300px;height:220px;padding:16px;display:flex;flex-direction:column;gap:12px;background:#eef2ff; }
+        #peer { width:100px;height:50px;background:#a5b4fc; }
+      </style></head><body>
+        <div id="origin" data-agent-native-node-id="origin">
+          <div id="control" data-agent-native-node-id="control">Control</div>
+          <div id="space" data-agent-native-node-id="space">Space</div>
+        </div>
+        <div id="target" data-agent-native-node-id="target"><div id="peer" data-agent-native-node-id="peer">Peer</div></div>
+      </body></html>`);
+      await installBridge(page);
+
+      const controlBeforeRelease = await dragCenterTo(
+        page,
+        "#control",
+        { x: 560, y: 220 },
+        "Control",
+      );
+      const ignored = await page.locator("#control").evaluate((element) => {
+        const item = element as HTMLElement;
+        const rect = item.getBoundingClientRect();
+        return {
+          parent: item.parentElement?.id,
+          position: getComputedStyle(item).position,
+          left: rect.left,
+          top: rect.top,
+        };
+      });
+      expect(ignored.parent).toBe("target");
+      expect(ignored.position).toBe("absolute");
+      expect(ignored.left).toBeCloseTo(controlBeforeRelease.left, 5);
+      expect(ignored.top).toBeCloseTo(controlBeforeRelease.top, 5);
+
+      const spaceBeforeRelease = await dragCenterTo(
+        page,
+        "#space",
+        { x: 560, y: 250 },
+        "Space",
+      );
+      const retained = await page.locator("#space").evaluate((element) => {
+        const item = element as HTMLElement;
+        const rect = item.getBoundingClientRect();
+        return {
+          parent: item.parentElement?.id,
+          position: getComputedStyle(item).position,
+          left: rect.left,
+          top: rect.top,
+        };
+      });
+      expect(retained.parent).toBe("origin");
+      expect(retained.position).toBe("absolute");
+      expect(retained.left).toBeCloseTo(spaceBeforeRelease.left, 5);
+      expect(retained.top).toBeCloseTo(spaceBeforeRelease.top, 5);
+
+      const messages = await page.evaluate(
+        () =>
+          (window as Window & { __matrixMessages?: Record<string, unknown>[] })
+            .__matrixMessages!,
+      );
+      const structures = messages.filter(
+        (message) => message.type === "visual-structure-change",
+      ) as Array<{ sourceId?: string; dropMode?: string }>;
+      expect(structures).toHaveLength(1);
+      expect(structures[0]).toMatchObject({
+        sourceId: "control",
+        dropMode: "absolute-container",
+      });
+      expect(
+        messages.some(
+          (message) =>
+            message.type === "visual-style-change" &&
+            (
+              message as { sourceId?: string; selector?: string }
+            ).selector?.includes("space"),
+        ),
+      ).toBe(true);
+      await page.close();
+    },
+  );
+});
+
+describe("cross-screen source and runtime matrix", () => {
+  it("preserves absolute semantics for freeform destinations and strips them for flex/grid destinations with exact undo/redo snapshots", () => {
+    const source = ensureCodeLayerNodeIdsInHtml(
+      `<body><div data-agent-native-layer-name="Movable" class="absolute md:!fixed left-20 top-10 rounded" style="position:absolute;left:80px;top:40px">Move</div></body>`,
+    ).content;
+    const freeform = ensureCodeLayerNodeIdsInHtml(
+      `<body><section data-agent-native-layer-name="Freeform" data-an-primitive="frame" style="position:absolute;left:20px;top:20px"></section></body>`,
+    ).content;
+    const flowTargets = [
+      `<body><section data-agent-native-layer-name="Target" style="display:flex;flex-direction:row;gap:8px"><span data-agent-native-layer-name="Peer">Peer</span></section></body>`,
+      `<body><section data-agent-native-layer-name="Target" style="display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px"><span data-agent-native-layer-name="Peer">Peer</span></section></body>`,
+    ];
+    const movableId = sourceId(source, "Movable");
+
+    const freeformMove = moveNodeBetweenDocuments(source, freeform, {
+      nodeId: movableId,
+      anchorNodeId: sourceId(freeform, "Freeform"),
+      placement: "inside",
+    });
+    expect(freeformMove.status).toBe("applied");
+    expect(freeformMove.destHtml).toContain("position:absolute");
+    expect(freeformMove.destHtml).toContain("left:80px");
+
+    for (const targetMarkup of flowTargets) {
+      const destination = ensureCodeLayerNodeIdsInHtml(targetMarkup).content;
+      const moved = moveNodeBetweenDocuments(source, destination, {
+        nodeId: movableId,
+        anchorNodeId: sourceId(destination, "Peer"),
+        placement: "before",
+      });
+      expect(moved.status).toBe("applied");
+      expect(moved.sourceHtml).not.toContain("Move</div>");
+      expect(moved.destHtml).not.toContain("position:absolute");
+      expect(moved.destHtml).not.toMatch(/(?:^|\s)absolute(?:\s|$)/);
+      expect(moved.destHtml).not.toContain("md:!fixed");
+
+      // The editor's source history is a one-snapshot mutation: undo returns
+      // both documents exactly, redo returns the exact moved pair.
+      const history = [
+        { source, destination },
+        { source: moved.sourceHtml, destination: moved.destHtml },
+      ];
+      expect(history[history.length - 2]).toEqual({ source, destination });
+      expect(history[history.length - 1]).toEqual({
+        source: moved.sourceHtml,
+        destination: moved.destHtml,
+      });
+    }
+  });
+
+  it("uses the same-screen bridge only for safe runtime/runtime moves and semantic handoff for cross-screen or mixed ownership", () => {
+    expect(
+      resolveRuntimeStructureMoveExecutionMode({
+        subjectRuntimeOnly: true,
+        targetRuntimeOnly: true,
+        sourceScreenId: "screen-a",
+        targetScreenId: "screen-a",
+      }),
+    ).toBe("screen-bridge");
+    for (const ownership of [
+      { subjectRuntimeOnly: true, targetRuntimeOnly: true },
+      { subjectRuntimeOnly: true, targetRuntimeOnly: false },
+      { subjectRuntimeOnly: false, targetRuntimeOnly: true },
+    ]) {
+      expect(
+        resolveRuntimeStructureMoveExecutionMode({
+          ...ownership,
+          sourceScreenId: "screen-a",
+          targetScreenId: "screen-b",
+        }),
+      ).toBe("semantic-handoff");
+    }
+
+    const anchor = (relPath: string, component: string) => ({
+      relPath,
+      sourceFile: relPath,
+      line: 12,
+      column: 5,
+      component,
+      runtimeMultiplicity: 1,
+      scope: "single-instance" as const,
+    });
+    const built = buildRuntimeReactStructureMoveHandoff({
+      subjectAnchor: anchor("app/components/Card.tsx", "Card"),
+      targetAnchor: anchor("app/components/Grid.tsx", "Grid"),
+      placement: "inside",
+      sourceScreenId: "screen-a",
+      targetScreenId: "screen-b",
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    expect(built.handoff.runtimeRelationship).toMatchObject({
+      kind: "inside",
+      sourceScreenId: "screen-a",
+      targetScreenId: "screen-b",
+    });
+    expect(built.handoff.executionContract).toMatchObject({
+      requiresHumanWriteConsent: true,
+      requiresExpectedVersionHash: true,
+      allowsGenericAstStructureTransform: false,
+      preservePreviewUntilHmrConfirmation: true,
+    });
+  });
+});
diff --git a/templates/design/app/components/design/bridge/sample.bridge.ts b/templates/design/app/components/design/bridge/sample.bridge.ts
index a9e9646d5a..29f8cc1f6f 100644
--- a/templates/design/app/components/design/bridge/sample.bridge.ts
+++ b/templates/design/app/components/design/bridge/sample.bridge.ts
@@ -10,6 +10,13 @@
  */
 (function () {
   window.addEventListener("message", function (e: MessageEvent) {
+    // Every other *.bridge.ts listener validates the sender before trusting
+    // the payload (see editor-chrome.bridge.ts, hit-test.bridge.ts, etc. —
+    // all check `e.source !== window.parent`); this one didn't, even though
+    // it's just a compile-pipeline smoke-test fixture with no real iframe
+    // wiring today. Match the house rule so it stays a safe template to
+    // copy from if this file is ever pointed at a live surface.
+    if (e.source !== window.parent) return;
     if (!e.data || e.data.type !== "agent-native:sample-ping") return;
     var correlationId: string = e.data.correlationId ?? "";
     try {
diff --git a/templates/design/app/components/design/code-workbench/CodeWorkbench.tsx b/templates/design/app/components/design/code-workbench/CodeWorkbench.tsx
index f41847bf35..8c5761ae18 100644
--- a/templates/design/app/components/design/code-workbench/CodeWorkbench.tsx
+++ b/templates/design/app/components/design/code-workbench/CodeWorkbench.tsx
@@ -350,9 +350,14 @@ function CodeWorkbenchInner({
       const onUp = () => {
         target.removeEventListener("pointermove", onMove);
         target.removeEventListener("pointerup", onUp);
+        target.removeEventListener("pointercancel", onUp);
       };
       target.addEventListener("pointermove", onMove);
       target.addEventListener("pointerup", onUp);
+      // A cancelled pointer (e.g. a dialog stealing capture mid-drag) would
+      // otherwise never fire pointerup, leaking these listeners onto the
+      // resize handle until the next drag piles more on top of them.
+      target.addEventListener("pointercancel", onUp);
     },
     [api],
   );
diff --git a/templates/design/app/components/design/code-workbench/editor/MonacoHost.tsx b/templates/design/app/components/design/code-workbench/editor/MonacoHost.tsx
index 7b41472ddf..bb231f8e24 100644
--- a/templates/design/app/components/design/code-workbench/editor/MonacoHost.tsx
+++ b/templates/design/app/components/design/code-workbench/editor/MonacoHost.tsx
@@ -9,6 +9,7 @@ import {
 } from "../../code-workbench-theme";
 import {
   dispatchKeybinding,
+  runCommand,
   type WorkbenchCommand,
   type WorkbenchCommandContext,
 } from "../commands";
@@ -93,11 +94,22 @@ export function MonacoHost({
     // Safety net: Monaco's own Cmd+S binding (if any) is not guaranteed, and
     // the root's capture-phase keydown handler already dispatches workbench
     // commands before Monaco sees them — this addCommand is a belt-and-
-    // braces fallback for save specifically.
+    // braces fallback for save specifically. It goes through the same
+    // `workbench.save` command (via runCommand) as every other invocation
+    // path, not a bare `api.save()` call, so a failed save (stale version,
+    // missing local write consent, network error) still surfaces a toast /
+    // consent-retry here instead of failing silently.
     editor.addCommand(
       monacoModule.KeyMod.CtrlCmd | monacoModule.KeyCode.KeyS,
       () => {
-        void commandContextRef.current.api.save();
+        const saveCommand = commandsRef.current.find(
+          (command) => command.id === "workbench.save",
+        );
+        if (saveCommand) {
+          void runCommand(saveCommand, commandContextRef.current);
+        } else {
+          void commandContextRef.current.api.save();
+        }
       },
     );
 
diff --git a/templates/design/app/components/design/code-workbench/explorer/FileTree.tsx b/templates/design/app/components/design/code-workbench/explorer/FileTree.tsx
index 0c86d8f2f4..d0bc6f09c7 100644
--- a/templates/design/app/components/design/code-workbench/explorer/FileTree.tsx
+++ b/templates/design/app/components/design/code-workbench/explorer/FileTree.tsx
@@ -93,6 +93,16 @@ export function FileTree({
     text: "",
     at: 0,
   });
+  // When Enter/Escape ends a rename or new-file input via setRenamingPath /
+  // setPendingNewFile, React unmounts the focused input as part of that same
+  // update. Removing a focused DOM node makes the browser fire a native blur
+  // on it, which our onBlur handler would otherwise treat as an independent
+  // commit — double-submitting on Enter (rename/create called twice) and
+  // silently committing the draft on Escape instead of discarding it. These
+  // refs let the key handler mark "I already resolved this input" so the
+  // resulting blur is a no-op.
+  const renameHandledRef = useRef(false);
+  const newFileHandledRef = useRef(false);
 
   const rows = flattenVisibleTree(nodes, expandedPaths);
 
@@ -121,6 +131,7 @@ export function FileTree({
   );
 
   const startRename = useCallback((node: TreeNode) => {
+    renameHandledRef.current = false;
     setRenamingPath(node.path);
     setRenameDraft(baseName(node.path));
   }, []);
@@ -293,6 +304,7 @@ export function FileTree({
               label="New File" /* i18n-ignore */
               icon={IconPlus}
               onClick={() => {
+                newFileHandledRef.current = false;
                 setPendingNewFile({ parentPath: "" });
                 setNewFileDraft("");
               }}
@@ -390,14 +402,25 @@ export function FileTree({
                       value={renameDraft}
                       onClick={(event) => event.stopPropagation()}
                       onChange={(event) => setRenameDraft(event.target.value)}
-                      onBlur={() => commitRename(row.node)}
+                      onBlur={() => {
+                        // Enter/Escape already resolved this input; the blur
+                        // firing right after is just the DOM node unmounting,
+                        // not a real "user clicked away" commit request.
+                        if (renameHandledRef.current) {
+                          renameHandledRef.current = false;
+                          return;
+                        }
+                        void commitRename(row.node);
+                      }}
                       onKeyDown={(event) => {
                         event.stopPropagation();
                         if (event.key === "Enter") {
                           event.preventDefault();
+                          renameHandledRef.current = true;
                           void commitRename(row.node);
                         } else if (event.key === "Escape") {
                           event.preventDefault();
+                          renameHandledRef.current = true;
                           setRenamingPath(null);
                         }
                       }}
@@ -418,6 +441,7 @@ export function FileTree({
                   <ContextMenuItem
                     className="text-[12px]"
                     onSelect={() => {
+                      newFileHandledRef.current = false;
                       toggleFolder(row.path, true);
                       setPendingNewFile({ parentPath: row.path });
                       setNewFileDraft("");
@@ -481,14 +505,25 @@ export function FileTree({
               value={newFileDraft}
               placeholder="filename.ext" /* i18n-ignore */
               onChange={(event) => setNewFileDraft(event.target.value)}
-              onBlur={() => commitNewFile()}
+              onBlur={() => {
+                // Enter/Escape already resolved this input; the blur firing
+                // right after is just the DOM node unmounting, not a real
+                // "user clicked away" commit request.
+                if (newFileHandledRef.current) {
+                  newFileHandledRef.current = false;
+                  return;
+                }
+                void commitNewFile();
+              }}
               onKeyDown={(event) => {
                 event.stopPropagation();
                 if (event.key === "Enter") {
                   event.preventDefault();
+                  newFileHandledRef.current = true;
                   void commitNewFile();
                 } else if (event.key === "Escape") {
                   event.preventDefault();
+                  newFileHandledRef.current = true;
                   setPendingNewFile(null);
                   setNewFileDraft("");
                 }
diff --git a/templates/design/app/components/design/code-workbench/format/format-on-open-guard.ts b/templates/design/app/components/design/code-workbench/format/format-on-open-guard.ts
new file mode 100644
index 0000000000..f7a723beb1
--- /dev/null
+++ b/templates/design/app/components/design/code-workbench/format/format-on-open-guard.ts
@@ -0,0 +1,25 @@
+/**
+ * Pure guard extracted from format-on-open.ts so it stays unit-testable
+ * without pulling in `../store` / `../model-registry` (and transitively
+ * `monaco-editor`, which requires a full browser environment and can't load
+ * under vitest's default node/jsdom setup) — same split used by
+ * status-bar-lang.ts for StatusBar.tsx.
+ */
+
+/**
+ * Decide whether a completed background format result is still safe to
+ * apply. `snapshotContent` is the buffer content that was actually sent to
+ * Prettier; formatting runs asynchronously (dynamic plugin imports + async
+ * format), so by the time the result comes back the user may have already
+ * started editing the live model. Applying the formatted text in that case
+ * would silently discard their in-progress edits, so we bail unless the
+ * model's current value still matches the snapshot that was formatted.
+ */
+export function shouldApplyFormatResult(
+  currentModelValue: string,
+  snapshotContent: string,
+  formatted: string,
+): boolean {
+  if (formatted === snapshotContent) return false;
+  return currentModelValue === snapshotContent;
+}
diff --git a/templates/design/app/components/design/code-workbench/format/format-on-open.test.ts b/templates/design/app/components/design/code-workbench/format/format-on-open.test.ts
new file mode 100644
index 0000000000..2f5b49fddc
--- /dev/null
+++ b/templates/design/app/components/design/code-workbench/format/format-on-open.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+
+// Import the pure guard directly from format-on-open-guard.ts, not from
+// format-on-open.ts — the latter also imports `../store` / `../model-registry`
+// (and transitively `monaco-editor`), which require a full browser
+// environment and can't load under vitest's default node environment. Same
+// split used by status-bar-lang.ts for StatusBar.tsx.
+import { shouldApplyFormatResult } from "./format-on-open-guard";
+
+describe("shouldApplyFormatResult", () => {
+  it("applies the result when the model is unchanged and formatting differs", () => {
+    expect(
+      shouldApplyFormatResult("const x=1", "const x=1", "const x = 1;"),
+    ).toBe(true);
+  });
+
+  it("skips when the formatted output is identical to the snapshot (no-op)", () => {
+    expect(
+      shouldApplyFormatResult("const x = 1;", "const x = 1;", "const x = 1;"),
+    ).toBe(false);
+  });
+
+  it("skips when the user edited the buffer while formatting was in flight", () => {
+    // The live model no longer matches the snapshot that was sent to
+    // Prettier — applying the stale formatted result would discard the
+    // user's in-progress edit.
+    expect(
+      shouldApplyFormatResult(
+        "const x=1\nconst y=2",
+        "const x=1",
+        "const x = 1;",
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/templates/design/app/components/design/code-workbench/format/format-on-open.ts b/templates/design/app/components/design/code-workbench/format/format-on-open.ts
index 6ccbb6b8f1..e0ec1aa966 100644
--- a/templates/design/app/components/design/code-workbench/format/format-on-open.ts
+++ b/templates/design/app/components/design/code-workbench/format/format-on-open.ts
@@ -3,8 +3,11 @@ import { useEffect } from "react";
 import { modelRegistry } from "../model-registry";
 import { useWorkbench, type BufferLoadedEvent } from "../store";
 import { providerKindFromKey } from "../workspace/types";
+import { shouldApplyFormatResult } from "./format-on-open-guard";
 import { formatWithPrettier, isFormattablePath } from "./prettier-format";
 
+export { shouldApplyFormatResult } from "./format-on-open-guard";
+
 /**
  * Auto-format-on-first-open policy: the design's SQL-backed (inline) files
  * are machine-generated, so the first time a formattable inline buffer is
@@ -42,10 +45,25 @@ export function useFormatOnFirstOpen({ enabled }: { enabled: boolean }): void {
       void (async () => {
         const result = await formatWithPrettier(event.read.content, event.path);
         if ("error" in result) return;
-        if (result.formatted === event.read.content) return;
 
         const entry = modelRegistry.get(event.uri);
         if (!entry || entry.model.isDisposed()) return;
+        // Formatting is async (dynamic plugin imports + Prettier itself), so
+        // the user may have started typing in the buffer while we were
+        // awaiting the result. Applying `result.formatted` — derived from the
+        // pre-format snapshot — over the model unconditionally would silently
+        // clobber those in-progress edits. Bail out if the live model no
+        // longer matches the snapshot that was formatted; a later save or
+        // manual format can pick it up.
+        if (
+          !shouldApplyFormatResult(
+            entry.model.getValue(),
+            event.read.content,
+            result.formatted,
+          )
+        ) {
+          return;
+        }
         // Push the formatted text without touching savedAltVersionId, so the
         // buffer becomes dirty (matches the "formatted but unsaved" state a
         // real edit would produce) — then save silently.
diff --git a/templates/design/app/components/design/code-workbench/model-registry.spec.ts b/templates/design/app/components/design/code-workbench/model-registry.spec.ts
new file mode 100644
index 0000000000..0f7dca1ce3
--- /dev/null
+++ b/templates/design/app/components/design/code-workbench/model-registry.spec.ts
@@ -0,0 +1,265 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * model-registry.ts owns dirty tracking + external content application for
+ * every open workbench buffer, but it does so against the real
+ * `monaco-editor` package, which cannot load under vitest's default `node`
+ * environment (see editor/StatusBar.test.ts for the same constraint). These
+ * tests fake just enough of the `monaco-editor` module surface that
+ * model-registry.ts touches — model creation/lookup, alternative version ids,
+ * `pushEditOperations`, and `onDidChangeContent` — to exercise the real
+ * dirty-tracking and external-content-replacement logic in isolation.
+ */
+
+interface FakeRange {
+  __range: true;
+}
+
+interface FakeEditOperation {
+  range: FakeRange;
+  text: string;
+}
+
+class FakeModel {
+  private value: string;
+  private altVersionId = 1;
+  private disposed = false;
+  private listeners = new Set<() => void>();
+  language: string;
+  readonly uri: { toString(): string };
+
+  constructor(value: string, language: string, uri: { toString(): string }) {
+    this.value = value;
+    this.language = language;
+    this.uri = uri;
+  }
+
+  getValue(): string {
+    return this.value;
+  }
+
+  getAlternativeVersionId(): number {
+    return this.altVersionId;
+  }
+
+  isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+
+  getFullModelRange(): FakeRange {
+    return { __range: true };
+  }
+
+  /** Mirrors real Monaco: applies the edit and fires listeners synchronously
+   *  before returning, all still inside the alt-version-id bump. */
+  pushEditOperations(
+    _selections: unknown,
+    edits: FakeEditOperation[],
+    _computeSelections: () => null,
+  ): null {
+    const nextValue = edits[0]?.text ?? this.value;
+    if (nextValue === this.value) return null;
+    this.value = nextValue;
+    this.altVersionId += 1;
+    for (const listener of this.listeners) listener();
+    return null;
+  }
+
+  /** Test helper simulating real user typing (bypasses pushEditOperations'
+   *  edit-list shape but fires the same synchronous notification contract). */
+  simulateUserEdit(nextValue: string): void {
+    this.value = nextValue;
+    this.altVersionId += 1;
+    for (const listener of this.listeners) listener();
+  }
+
+  onDidChangeContent(listener: () => void): { dispose(): void } {
+    this.listeners.add(listener);
+    return { dispose: () => this.listeners.delete(listener) };
+  }
+}
+
+const modelsByUri = new Map<string, FakeModel>();
+
+vi.mock("monaco-editor", () => {
+  return {
+    editor: {
+      getModel: (uri: { toString(): string }) =>
+        modelsByUri.get(uri.toString()),
+      createModel: (
+        content: string,
+        language: string,
+        uri: { toString(): string },
+      ) => {
+        const model = new FakeModel(content, language, uri);
+        modelsByUri.set(uri.toString(), model);
+        return model;
+      },
+      setModelLanguage: (model: FakeModel, language: string) => {
+        model.language = language;
+      },
+    },
+    Uri: {
+      from: (parts: { scheme: string; authority: string; path: string }) => ({
+        toString: () => `${parts.scheme}://${parts.authority}${parts.path}`,
+        ...parts,
+      }),
+    },
+  };
+});
+
+const { modelRegistry } = await import("./model-registry");
+
+function makeUri(name: string): string {
+  return `inline:test-design::${name}`;
+}
+
+describe("WorkbenchModelRegistry", () => {
+  beforeEach(() => {
+    modelsByUri.clear();
+    modelRegistry.disposeAll();
+  });
+  afterEach(() => {
+    modelRegistry.disposeAll();
+    modelsByUri.clear();
+  });
+
+  it("is clean immediately after creation and dirty after a user edit", () => {
+    const uri = makeUri("a.txt");
+    const entry = modelRegistry.ensureModel(uri, "hello", "plaintext");
+    expect(modelRegistry.isDirty(uri)).toBe(false);
+    (entry.model as unknown as FakeModel).simulateUserEdit("hello world");
+    expect(modelRegistry.isDirty(uri)).toBe(true);
+  });
+
+  it("markSaved clears dirty at the captured alternative version id", () => {
+    const uri = makeUri("b.txt");
+    const entry = modelRegistry.ensureModel(uri, "hello", "plaintext");
+    const model = entry.model as unknown as FakeModel;
+    model.simulateUserEdit("hello world");
+    expect(modelRegistry.isDirty(uri)).toBe(true);
+    modelRegistry.markSaved(uri, model.getAlternativeVersionId());
+    expect(modelRegistry.isDirty(uri)).toBe(false);
+  });
+
+  describe("applyExternalContent (stale-echo / agent-edit application)", () => {
+    it("leaves the buffer clean after applying new external content", () => {
+      const uri = makeUri("c.txt");
+      modelRegistry.ensureModel(uri, "hello", "plaintext");
+      modelRegistry.applyExternalContent(uri, "hello from the agent");
+      expect(modelRegistry.getContent(uri)).toBe("hello from the agent");
+      expect(modelRegistry.isDirty(uri)).toBe(false);
+    });
+
+    it("is a no-op when the content already matches (true echo)", () => {
+      const uri = makeUri("d.txt");
+      const entry = modelRegistry.ensureModel(uri, "hello", "plaintext");
+      const model = entry.model as unknown as FakeModel;
+      const before = model.getAlternativeVersionId();
+      modelRegistry.applyExternalContent(uri, "hello");
+      expect(model.getAlternativeVersionId()).toBe(before);
+      expect(modelRegistry.isDirty(uri)).toBe(false);
+    });
+
+    it("does not report dirty to a listener observing the synchronous pushEditOperations callback", () => {
+      // Regression test: Monaco's onDidChangeContent fires synchronously from
+      // inside pushEditOperations, before applyExternalContent updates
+      // savedAltVersionId on the next line. A dirty-tracking subscriber that
+      // ignores isApplyingExternalContent would see a stale isDirty()=true at
+      // that instant, even though the change was programmatic (an agent
+      // edit or a reload), not a real user edit. This is exactly the bug
+      // class that caused preview tabs to get incorrectly pinned when the
+      // agent edited a previewed file.
+      const uri = makeUri("e.txt");
+      const entry = modelRegistry.ensureModel(uri, "hello", "plaintext");
+      const model = entry.model as unknown as FakeModel;
+      const observedDirty: boolean[] = [];
+      model.onDidChangeContent(() => {
+        if (modelRegistry.isApplyingExternalContent(uri)) return;
+        observedDirty.push(modelRegistry.isDirty(uri));
+      });
+      modelRegistry.applyExternalContent(uri, "hello from the agent");
+      expect(observedDirty).toEqual([]);
+      expect(modelRegistry.isDirty(uri)).toBe(false);
+    });
+
+    it("still notifies a real user edit that happens to land right after an external update", () => {
+      const uri = makeUri("f.txt");
+      const entry = modelRegistry.ensureModel(uri, "hello", "plaintext");
+      const model = entry.model as unknown as FakeModel;
+      const observedDirty: boolean[] = [];
+      model.onDidChangeContent(() => {
+        if (modelRegistry.isApplyingExternalContent(uri)) return;
+        observedDirty.push(modelRegistry.isDirty(uri));
+      });
+      modelRegistry.applyExternalContent(uri, "hello from the agent");
+      // A fast keystroke landing immediately after the external update must
+      // still be recognized as a real, dirty edit — it must not be swallowed
+      // as if it were part of the echo.
+      model.simulateUserEdit("hello from the agent!");
+      expect(observedDirty).toEqual([true]);
+      expect(modelRegistry.isDirty(uri)).toBe(true);
+    });
+  });
+
+  describe("reloadContent (explicit discard-and-reload)", () => {
+    it("force-replaces content and clears dirty even when the buffer had local edits", () => {
+      const uri = makeUri("g.txt");
+      const entry = modelRegistry.ensureModel(uri, "hello", "plaintext");
+      const model = entry.model as unknown as FakeModel;
+      model.simulateUserEdit("hello, unsaved local edit");
+      expect(modelRegistry.isDirty(uri)).toBe(true);
+      modelRegistry.reloadContent(uri, "server content wins", "markdown");
+      expect(modelRegistry.getContent(uri)).toBe("server content wins");
+      expect(modelRegistry.isDirty(uri)).toBe(false);
+      expect(model.language).toBe("markdown");
+    });
+  });
+
+  describe("ensureModel", () => {
+    it("creates a model with the given content on first call", () => {
+      const uri = makeUri("h.txt");
+      const entry = modelRegistry.ensureModel(
+        uri,
+        "first content",
+        "plaintext",
+      );
+      expect(entry.model.getValue()).toBe("first content");
+    });
+
+    it("does not overwrite an already-open model's content on repeat calls", () => {
+      // ensureModel is a "get or create": once a model exists, later calls
+      // (e.g. re-opening an already-open tab) must never silently discard
+      // whatever is currently in the buffer — reloadContent is the only
+      // sanctioned way to force a content replacement.
+      const uri = makeUri("i.txt");
+      const entry = modelRegistry.ensureModel(
+        uri,
+        "first content",
+        "plaintext",
+      );
+      const model = entry.model as unknown as FakeModel;
+      model.simulateUserEdit("locally edited, unsaved");
+      modelRegistry.ensureModel(
+        uri,
+        "content from a stale caller",
+        "plaintext",
+      );
+      expect(modelRegistry.getContent(uri)).toBe("locally edited, unsaved");
+    });
+  });
+
+  it("dispose() removes the entry and marks the model disposed", () => {
+    const uri = makeUri("j.txt");
+    const entry = modelRegistry.ensureModel(uri, "hello", "plaintext");
+    modelRegistry.dispose(uri);
+    expect(entry.model.isDisposed()).toBe(true);
+    expect(modelRegistry.has(uri)).toBe(false);
+    expect(modelRegistry.isDirty(uri)).toBe(false);
+    expect(modelRegistry.getContent(uri)).toBeNull();
+  });
+});
diff --git a/templates/design/app/components/design/code-workbench/model-registry.ts b/templates/design/app/components/design/code-workbench/model-registry.ts
index 6a90a993a0..9d35180594 100644
--- a/templates/design/app/components/design/code-workbench/model-registry.ts
+++ b/templates/design/app/components/design/code-workbench/model-registry.ts
@@ -31,6 +31,16 @@ function monacoUriFor(uri: string): monaco.Uri {
 
 class WorkbenchModelRegistry {
   private entries = new Map<string, WorkbenchModelEntry>();
+  /**
+   * Uris currently inside an `applyExternalContent`/`reloadContent` call.
+   * Monaco fires `onDidChangeContent` synchronously from inside
+   * `pushEditOperations`, before this class can update `savedAltVersionId` to
+   * the post-edit version — so a dirty-tracking subscriber reading
+   * `isDirty()` from that callback would see a stale "dirty" result for an
+   * edit nobody typed. Callers (store.tsx's dirty-tracking subscription) use
+   * `isApplyingExternalContent` to skip acting on that spurious notification.
+   */
+  private externalContentUris = new Set<string>();
 
   get(uri: string): WorkbenchModelEntry | undefined {
     return this.entries.get(uri);
@@ -75,6 +85,15 @@ class WorkbenchModelRegistry {
     return entry.model.getAlternativeVersionId() !== entry.savedAltVersionId;
   }
 
+  /**
+   * True while `uri`'s content is being replaced by `applyExternalContent`.
+   * Dirty-tracking subscribers must ignore `onDidChangeContent` notifications
+   * that fire while this is true — see the field comment above.
+   */
+  isApplyingExternalContent(uri: string): boolean {
+    return this.externalContentUris.has(uri);
+  }
+
   /**
    * Replace buffer content from an external change (agent edit, canvas edit)
    * while preserving the undo stack.
@@ -87,14 +106,33 @@ class WorkbenchModelRegistry {
       entry.savedAltVersionId = model.getAlternativeVersionId();
       return;
     }
-    model.pushEditOperations(
-      null,
-      [{ range: model.getFullModelRange(), text: content }],
-      () => null,
-    );
+    this.externalContentUris.add(uri);
+    try {
+      model.pushEditOperations(
+        null,
+        [{ range: model.getFullModelRange(), text: content }],
+        () => null,
+      );
+    } finally {
+      this.externalContentUris.delete(uri);
+    }
     entry.savedAltVersionId = model.getAlternativeVersionId();
   }
 
+  /**
+   * Force an already-open buffer to match freshly read content + language,
+   * discarding any local edits. Used only for explicit user-initiated reload
+   * (e.g. the "File changed elsewhere — reload latest" conflict action) —
+   * the caller has already decided to discard unsaved edits, so unlike
+   * `applyExternalContent`'s callers this does not gate on dirty state.
+   */
+  reloadContent(uri: string, content: string, language: string) {
+    const entry = this.entries.get(uri);
+    if (!entry || entry.model.isDisposed()) return;
+    monaco.editor.setModelLanguage(entry.model, language);
+    this.applyExternalContent(uri, content);
+  }
+
   /** Mark the buffer clean as of the given alternative version id. */
   markSaved(uri: string, altVersionId: number) {
     const entry = this.entries.get(uri);
diff --git a/templates/design/app/components/design/code-workbench/search/SearchView.tsx b/templates/design/app/components/design/code-workbench/search/SearchView.tsx
index da78eef5ff..2155ae4943 100644
--- a/templates/design/app/components/design/code-workbench/search/SearchView.tsx
+++ b/templates/design/app/components/design/code-workbench/search/SearchView.tsx
@@ -79,6 +79,21 @@ export function SearchView({ searchSeed }: SearchViewProps) {
   const [replaceAllFailures, setReplaceAllFailures] = useState(0);
   const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const abortRef = useRef<AbortController | null>(null);
+  // `providers` is recreated with a new array/object identity on every
+  // unrelated design poll tick (it flows through the design's SWR-polled
+  // `files` query, which has no structural-sharing guard), even when the
+  // actual set of workspace sources hasn't changed. Depending on `providers`
+  // directly would re-run the search effect on every poll tick, silently
+  // resetting `dismissed` (bringing back results the user just dismissed)
+  // and `replaceAllFailures`. Keep the latest providers in a ref for the
+  // debounced search to read, and key the effect off a stable signature of
+  // provider identities instead so it only re-runs when the source set
+  // actually changes.
+  const providersRef = useRef(providers);
+  providersRef.current = providers;
+  const providersSignature = providers
+    .map((provider) => provider.key)
+    .join(",");
 
   useEffect(() => {
     if (searchSeed.token === 0) return;
@@ -102,7 +117,7 @@ export function SearchView({ searchSeed }: SearchViewProps) {
       setDismissed({ files: new Set(), matches: new Set() });
       setReplaceAllFailures(0);
       searchWorkspace({
-        providers,
+        providers: providersRef.current,
         query,
         matchCase,
         wholeWord,
@@ -121,7 +136,17 @@ export function SearchView({ searchSeed }: SearchViewProps) {
       if (debounceRef.current) clearTimeout(debounceRef.current);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [query, matchCase, wholeWord, regex, providers]);
+  }, [query, matchCase, wholeWord, regex, providersSignature]);
+
+  // Safety net: abort any in-flight search when the view unmounts (it
+  // normally stays mounted-but-hidden per SideBar, but can genuinely unmount
+  // when the workbench itself closes) so a late `setResults` never fires
+  // against a torn-down component.
+  useEffect(() => {
+    return () => {
+      abortRef.current?.abort();
+    };
+  }, []);
 
   const visibleFiles = useMemo<FileSearchResult[]>(() => {
     if (!results) return [];
diff --git a/templates/design/app/components/design/code-workbench/search/search-engine.test.ts b/templates/design/app/components/design/code-workbench/search/search-engine.test.ts
index e92685ef08..a55612569b 100644
--- a/templates/design/app/components/design/code-workbench/search/search-engine.test.ts
+++ b/templates/design/app/components/design/code-workbench/search/search-engine.test.ts
@@ -271,4 +271,18 @@ describe("replaceMatchesInText", () => {
     expect(content).toBe("world hello");
     expect(count).toBe(1);
   });
+
+  it("supports backreferences when the pattern has named capture groups", () => {
+    // A named-group regex makes String.replace pass an extra trailing
+    // `groups` object to the callback; group-index backreferences ($1, $2)
+    // must still resolve to the real capture values, not the match offset.
+    const { content, count } = replaceMatchesInText(
+      "hello world",
+      "(?<first>\\w+) (?<second>\\w+)",
+      "$2 $1",
+      { matchCase: true, wholeWord: false, regex: true },
+    );
+    expect(content).toBe("world hello");
+    expect(count).toBe(1);
+  });
 });
diff --git a/templates/design/app/components/design/code-workbench/search/search-engine.ts b/templates/design/app/components/design/code-workbench/search/search-engine.ts
index a5e39ec449..e36a0397da 100644
--- a/templates/design/app/components/design/code-workbench/search/search-engine.ts
+++ b/templates/design/app/components/design/code-workbench/search/search-engine.ts
@@ -268,7 +268,16 @@ export function replaceMatchesInText(
     count += 1;
     if (options.regex) {
       // Support $1, $2, ... backreferences the way String.replace does.
-      const groups = matchArgs.slice(1, -2);
+      // The callback args are (match, ...captureGroups, offset, string[,
+      // namedGroups]) — `namedGroups` is only appended when the pattern has
+      // named capture groups, so it must be dropped before slicing off the
+      // trailing offset/string pair, or a `$N` beyond the real group count
+      // would silently resolve to the match offset instead of "".
+      let rest = matchArgs.slice(1);
+      if (typeof rest[rest.length - 1] === "object") {
+        rest = rest.slice(0, -1);
+      }
+      const groups = rest.slice(0, -2);
       return replacement.replace(/\$(\d+)/g, (_all, index) => {
         const groupIndex = Number(index) - 1;
         return typeof groups[groupIndex] === "string" ? groups[groupIndex] : "";
diff --git a/templates/design/app/components/design/code-workbench/store.spec.tsx b/templates/design/app/components/design/code-workbench/store.spec.tsx
new file mode 100644
index 0000000000..df8617ed20
--- /dev/null
+++ b/templates/design/app/components/design/code-workbench/store.spec.tsx
@@ -0,0 +1,269 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { WorkspaceProvider, WorkspaceReadResult } from "./workspace/types";
+
+(
+  globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+/**
+ * store.tsx transitively imports model-registry.ts, which requires the real
+ * `monaco-editor` package (window/canvas-heavy, can't load under vitest — see
+ * model-registry.spec.ts and editor/StatusBar.test.ts for the same
+ * constraint). These tests fake the model-registry module surface instead, so
+ * the store's reducer/dispatch wiring — dirty tracking, stale-echo handling,
+ * preview-tab pinning, reload-buffer — can be exercised end to end through
+ * `WorkbenchProvider` + `useWorkbench()` with real React state.
+ */
+
+interface FakeModelEntry {
+  content: string;
+  savedContent: string;
+  language: string;
+  disposed: boolean;
+}
+
+const models = new Map<string, FakeModelEntry>();
+let applyingExternal = new Set<string>();
+
+vi.mock("./model-registry", () => {
+  const modelRegistry = {
+    has: (uri: string) => models.has(uri),
+    get: (uri: string) => {
+      const entry = models.get(uri);
+      if (!entry) return undefined;
+      return {
+        model: {
+          isDisposed: () => entry.disposed,
+          getValue: () => entry.content,
+          getAlternativeVersionId: () => 0,
+          // store.tsx's subscribeDirtyTracking attaches a listener here on
+          // every model it sees; the store-level tests below drive dirty
+          // state directly through api.markDirty/applyExternalRead instead
+          // of simulating Monaco's synchronous edit-event firing (that
+          // exact race is covered at the model-registry level in
+          // model-registry.spec.ts), so this only needs to exist, not fire.
+          onDidChangeContent: () => ({ dispose: () => {} }),
+        },
+        savedAltVersionId: 0,
+        viewState: null,
+      };
+    },
+    ensureModel: (uri: string, content: string, language: string) => {
+      const existing = models.get(uri);
+      if (existing && !existing.disposed) return existing;
+      const entry: FakeModelEntry = {
+        content,
+        savedContent: content,
+        language,
+        disposed: false,
+      };
+      models.set(uri, entry);
+      return entry;
+    },
+    getContent: (uri: string) => models.get(uri)?.content ?? null,
+    isDirty: (uri: string) => {
+      const entry = models.get(uri);
+      if (!entry || entry.disposed) return false;
+      return entry.content !== entry.savedContent;
+    },
+    isApplyingExternalContent: (uri: string) => applyingExternal.has(uri),
+    applyExternalContent: (uri: string, content: string) => {
+      const entry = models.get(uri);
+      if (!entry || entry.disposed) return;
+      if (entry.content === content) {
+        entry.savedContent = entry.content;
+        return;
+      }
+      applyingExternal.add(uri);
+      entry.content = content;
+      applyingExternal.delete(uri);
+      entry.savedContent = content;
+    },
+    reloadContent: (uri: string, content: string, language: string) => {
+      const entry = models.get(uri);
+      if (!entry || entry.disposed) return;
+      entry.language = language;
+      modelRegistry.applyExternalContent(uri, content);
+    },
+    markSaved: (uri: string) => {
+      const entry = models.get(uri);
+      if (entry) entry.savedContent = entry.content;
+    },
+    saveViewState: () => {},
+    getViewState: () => null,
+    dispose: (uri: string) => {
+      const entry = models.get(uri);
+      if (entry) entry.disposed = true;
+      models.delete(uri);
+    },
+    disposeAll: () => {
+      models.clear();
+    },
+  };
+  return { modelRegistry };
+});
+
+const { WorkbenchProvider, useWorkbench } = await import("./store");
+type WorkbenchApi = ReturnType<typeof useWorkbench>["api"];
+type WorkbenchState = ReturnType<typeof useWorkbench>["state"];
+
+function makeProvider(overrides: { content: string; versionHash: string }): {
+  provider: WorkspaceProvider;
+  setRead: (read: WorkspaceReadResult) => void;
+} {
+  let current: WorkspaceReadResult = {
+    content: overrides.content,
+    versionHash: overrides.versionHash,
+  };
+  const provider: WorkspaceProvider = {
+    key: "inline:test",
+    kind: "inline",
+    label: "Design files",
+    capabilities: { write: true, create: true, rename: true, delete: true },
+    listFiles: async () => [],
+    readFile: async () => current,
+    writeFile: async () => ({ versionHash: "saved-1" }),
+  };
+  return {
+    provider,
+    setRead: (read) => {
+      current = read;
+    },
+  };
+}
+
+let root: Root | null = null;
+let container: HTMLDivElement | null = null;
+
+afterEach(() => {
+  if (root && container) {
+    act(() => root!.unmount());
+  }
+  root = null;
+  container = null;
+  models.clear();
+  applyingExternal = new Set();
+});
+
+function mount(providers: WorkspaceProvider[]) {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  let latest: { state: WorkbenchState; api: WorkbenchApi } | null = null;
+  function Capture() {
+    const { state, api } = useWorkbench();
+    latest = { state, api };
+    return null;
+  }
+  act(() => {
+    root!.render(
+      <WorkbenchProvider providers={providers}>
+        <Capture />
+      </WorkbenchProvider>,
+    );
+  });
+  return {
+    get: () => latest!,
+  };
+}
+
+describe("WorkbenchProvider", () => {
+  it("does not pin a preview tab when an external (agent/poll) edit lands on it", async () => {
+    // Regression test for the store↔model-registry dirty-tracking race: an
+    // external content replacement used to synchronously report the buffer
+    // as dirty (see model-registry.spec.ts), which store.tsx's markDirty
+    // then treated as a real user edit and pinned the preview tab. Agent
+    // edits arriving on a previewed file must never silently convert it into
+    // a pinned tab.
+    const { provider } = makeProvider({
+      content: "<h1>hello</h1>",
+      versionHash: "v1",
+    });
+    const harness = mount([provider]);
+
+    await act(async () => {
+      await harness.get().api.openFile(provider.key, "index.html", {
+        preview: true,
+      });
+    });
+
+    const uri = harness.get().state.tabs[0]?.uri;
+    expect(uri).toBeDefined();
+    expect(harness.get().state.tabs[0]?.preview).toBe(true);
+    expect(harness.get().state.buffers[uri!]?.dirty).toBe(false);
+
+    act(() => {
+      harness.get().api.applyExternalRead(uri!, {
+        content: "<h1>hello from the agent</h1>",
+        versionHash: "v2",
+      });
+    });
+
+    expect(harness.get().state.buffers[uri!]?.dirty).toBe(false);
+    // The core regression: the tab must still be a preview tab (italic,
+    // replaced by the next preview open) — not silently pinned.
+    expect(harness.get().state.tabs[0]?.preview).toBe(true);
+  });
+
+  it("still marks the buffer dirty and pins the preview tab on a real user edit", async () => {
+    const { provider } = makeProvider({
+      content: "<h1>hi</h1>",
+      versionHash: "v1",
+    });
+    const harness = mount([provider]);
+
+    await act(async () => {
+      await harness.get().api.openFile(provider.key, "index.html", {
+        preview: true,
+      });
+    });
+    const uri = harness.get().state.tabs[0]!.uri;
+
+    act(() => {
+      // Simulate a real keystroke: mutate the fake model directly, then
+      // report it the same way the real onDidChangeContent subscriber would.
+      const entry = models.get(uri)!;
+      entry.content = "<h1>hi, edited by hand</h1>";
+      harness.get().api.markDirty(uri, true);
+    });
+
+    expect(harness.get().state.buffers[uri]?.dirty).toBe(true);
+    expect(harness.get().state.tabs[0]?.preview).toBe(false);
+  });
+
+  it("reloadBuffer force-replaces content on an already-open buffer (conflict 'reload latest')", async () => {
+    // Regression test: reloadBuffer used to call the initial-load path,
+    // which is deliberately a content no-op once a model already exists —
+    // so clicking "reload latest" after a conflict silently did nothing.
+    const { provider, setRead } = makeProvider({
+      content: "original content",
+      versionHash: "v1",
+    });
+    const harness = mount([provider]);
+
+    await act(async () => {
+      await harness.get().api.openFile(provider.key, "notes.md");
+    });
+    const uri = harness.get().state.tabs[0]!.uri;
+    expect(harness.get().state.buffers[uri]?.savedVersionHash).toBe("v1");
+
+    // Simulate a local dirty edit, then the server having moved on (a
+    // conflict), then the user explicitly choosing to reload latest.
+    models.get(uri)!.content = "local unsaved edit";
+    setRead({ content: "content from someone else", versionHash: "v2" });
+
+    await act(async () => {
+      await harness.get().api.reloadBuffer(uri);
+    });
+
+    expect(models.get(uri)?.content).toBe("content from someone else");
+    expect(harness.get().state.buffers[uri]?.dirty).toBe(false);
+    expect(harness.get().state.buffers[uri]?.conflict).toBe(false);
+    expect(harness.get().state.buffers[uri]?.savedVersionHash).toBe("v2");
+  });
+});
diff --git a/templates/design/app/components/design/code-workbench/store.tsx b/templates/design/app/components/design/code-workbench/store.tsx
index 3c58492b66..954c2cf87f 100644
--- a/templates/design/app/components/design/code-workbench/store.tsx
+++ b/templates/design/app/components/design/code-workbench/store.tsx
@@ -341,6 +341,12 @@ export function WorkbenchProvider({
     if (dirtySubscribedModelsRef.current.has(entry.model)) return;
     dirtySubscribedModelsRef.current.add(entry.model);
     entry.model.onDidChangeContent(() => {
+      // Programmatic content replacement (agent edit, external reload) fires
+      // this synchronously before the model registry updates its saved
+      // version marker; treating that as a real edit would incorrectly mark
+      // the buffer dirty (and pin a preview tab) for a change the user never
+      // made. See modelRegistry.isApplyingExternalContent.
+      if (modelRegistry.isApplyingExternalContent(uri)) return;
       apiRef.current?.markDirty(uri, modelRegistry.isDirty(uri));
     });
   }, []);
@@ -369,7 +375,18 @@ export function WorkbenchProvider({
       try {
         const read = await provider.readFile(path);
         const language = read.language ?? languageForPath(path);
-        modelRegistry.ensureModel(uri, read.content, language);
+        // loadBuffer is also used by reloadBuffer to force an already-open
+        // buffer back to the latest server content (e.g. the "File changed
+        // elsewhere — reload latest" conflict action). `ensureModel` is
+        // intentionally a no-op on content when a model already exists (so
+        // the initial-open path here never clobbers a buffer someone is
+        // mid-edit on) — reloadContent is the explicit, caller-opted-in
+        // discard-local-edits path for that case.
+        if (modelRegistry.has(uri)) {
+          modelRegistry.reloadContent(uri, read.content, language);
+        } else {
+          modelRegistry.ensureModel(uri, read.content, language);
+        }
         subscribeDirtyTracking(uri);
         rememberVersionHash(uri, read.versionHash);
         const firstLoad = !loadedOnceRef.current.has(uri);
@@ -382,7 +399,7 @@ export function WorkbenchProvider({
             dirty: modelRegistry.isDirty(uri),
             conflict: false,
             saving: false,
-            readonly: read.readonly ?? false,
+            readonly: read.readonly ?? existingMeta?.readonly ?? false,
             language,
             fileId: read.fileId,
             savedVersionHash: read.versionHash,
diff --git a/templates/design/app/components/design/design-canvas/annotation-snapshot.test.ts b/templates/design/app/components/design/design-canvas/annotation-snapshot.test.ts
new file mode 100644
index 0000000000..c5e28e55aa
--- /dev/null
+++ b/templates/design/app/components/design/design-canvas/annotation-snapshot.test.ts
@@ -0,0 +1,260 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { DrawAnnotation } from "@/components/visual-editor";
+
+const callAction = vi.fn();
+
+vi.mock("@agent-native/core/client", () => ({
+  callAction: (...args: unknown[]) => callAction(...args),
+}));
+
+// Imported after the mock so the module under test picks up the mocked
+// `callAction` binding.
+const { captureAnnotatedScreenshot, drawAnnotationsOnContext } =
+  await import("./annotation-snapshot");
+
+function strokeAnnotation(
+  overrides: Partial<DrawAnnotation> = {},
+): DrawAnnotation {
+  return {
+    id: "s1",
+    type: "path",
+    pathData: "M10,10 L20,20",
+    color: "#ef4444",
+    lineWidth: 4,
+    position: { x: 0, y: 0 },
+    ...overrides,
+  };
+}
+
+function textAnnotation(
+  overrides: Partial<DrawAnnotation> = {},
+): DrawAnnotation {
+  return {
+    id: "t1",
+    type: "text",
+    text: "Move this button",
+    color: "#3b82f6",
+    lineWidth: 4,
+    position: { x: 40, y: 60 },
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// drawAnnotationsOnContext — pure rasterization, no real canvas needed since
+// it only depends on a handful of CanvasRenderingContext2D methods/setters.
+// ---------------------------------------------------------------------------
+
+describe("drawAnnotationsOnContext", () => {
+  function fakeCtx() {
+    return {
+      save: vi.fn(),
+      restore: vi.fn(),
+      beginPath: vi.fn(),
+      moveTo: vi.fn(),
+      lineTo: vi.fn(),
+      stroke: vi.fn(),
+      fillText: vi.fn(),
+      strokeStyle: "",
+      fillStyle: "",
+      lineWidth: 0,
+      lineCap: "",
+      lineJoin: "",
+      font: "",
+      textBaseline: "",
+    };
+  }
+
+  it("strokes a path annotation with its color and width", () => {
+    const ctx = fakeCtx();
+    drawAnnotationsOnContext(ctx as never, [strokeAnnotation()]);
+    expect(ctx.moveTo).toHaveBeenCalledWith(10, 10);
+    expect(ctx.lineTo).toHaveBeenCalledWith(20, 20);
+    expect(ctx.stroke).toHaveBeenCalledOnce();
+    expect(ctx.strokeStyle).toBe("#ef4444");
+    expect(ctx.lineWidth).toBe(4);
+    expect(ctx.save).toHaveBeenCalledOnce();
+    expect(ctx.restore).toHaveBeenCalledOnce();
+  });
+
+  it("draws a text annotation at its serialized position", () => {
+    const ctx = fakeCtx();
+    drawAnnotationsOnContext(ctx as never, [textAnnotation()]);
+    expect(ctx.fillText).toHaveBeenCalledWith("Move this button", 40, 60);
+    expect(ctx.fillStyle).toBe("#3b82f6");
+  });
+
+  it("draws multiple annotations in order and skips empty ones", () => {
+    const ctx = fakeCtx();
+    drawAnnotationsOnContext(ctx as never, [
+      strokeAnnotation({ id: "s1" }),
+      { ...textAnnotation({ id: "t-empty" }), text: "" },
+      textAnnotation({ id: "t2", text: "Label" }),
+    ]);
+    expect(ctx.stroke).toHaveBeenCalledOnce();
+    expect(ctx.fillText).toHaveBeenCalledOnce();
+    expect(ctx.fillText).toHaveBeenCalledWith("Label", 40, 60);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// captureAnnotatedScreenshot — orchestration + graceful-degradation contract
+// ---------------------------------------------------------------------------
+
+describe("captureAnnotatedScreenshot", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    callAction.mockReset();
+  });
+
+  const baseOptions = {
+    designId: "design-1",
+    fileId: "file-1",
+    annotations: [strokeAnnotation()],
+    canvasSize: { width: 1024, height: 768 },
+  };
+
+  it("returns null for localhost/fusion screens without calling take-design-screenshot", async () => {
+    const result = await captureAnnotatedScreenshot({
+      ...baseOptions,
+      sourceType: "localhost",
+    });
+    expect(result).toBeNull();
+    expect(callAction).not.toHaveBeenCalled();
+  });
+
+  it("returns null when neither designId nor fileId is available", async () => {
+    const result = await captureAnnotatedScreenshot({
+      ...baseOptions,
+      designId: undefined,
+      fileId: undefined,
+    });
+    expect(result).toBeNull();
+    expect(callAction).not.toHaveBeenCalled();
+  });
+
+  it("returns null when the canvas size is too small to be a real screen", async () => {
+    const result = await captureAnnotatedScreenshot({
+      ...baseOptions,
+      canvasSize: { width: 10, height: 10 },
+    });
+    expect(result).toBeNull();
+    expect(callAction).not.toHaveBeenCalled();
+  });
+
+  it("returns null when document is unavailable (SSR-like environment)", async () => {
+    vi.stubGlobal("document", undefined);
+    const result = await captureAnnotatedScreenshot(baseOptions);
+    expect(result).toBeNull();
+  });
+
+  it("falls back to null when take-design-screenshot reports no Chromium available", async () => {
+    vi.stubGlobal("document", { createElement: vi.fn() });
+    callAction.mockResolvedValueOnce({
+      ok: false,
+      reason: "no chromium available",
+    });
+    const result = await captureAnnotatedScreenshot(baseOptions);
+    expect(result).toBeNull();
+    expect(callAction).toHaveBeenCalledTimes(1);
+    expect(callAction).toHaveBeenCalledWith(
+      "take-design-screenshot",
+      expect.objectContaining({
+        fileId: "file-1",
+        widths: [1024],
+        heights: [768],
+      }),
+    );
+  });
+
+  it("falls back to null when the screenshot fetch fails", async () => {
+    vi.stubGlobal("document", { createElement: vi.fn() });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({ ok: false, status: 500 }),
+    );
+    callAction.mockResolvedValueOnce({
+      ok: true,
+      screenshots: [{ url: "https://cdn.example.com/shot.png" }],
+    });
+    const result = await captureAnnotatedScreenshot(baseOptions);
+    expect(result).toBeNull();
+    // Never reaches the upload-image call once compositing fails.
+    expect(callAction).toHaveBeenCalledTimes(1);
+  });
+
+  it("composites the screenshot with annotations and uploads the result", async () => {
+    const fakeCtx = {
+      save: vi.fn(),
+      restore: vi.fn(),
+      beginPath: vi.fn(),
+      moveTo: vi.fn(),
+      lineTo: vi.fn(),
+      stroke: vi.fn(),
+      fillText: vi.fn(),
+      drawImage: vi.fn(),
+      strokeStyle: "",
+      fillStyle: "",
+      lineWidth: 0,
+      lineCap: "",
+      lineJoin: "",
+      font: "",
+      textBaseline: "",
+    };
+    const fakeCanvas = {
+      width: 0,
+      height: 0,
+      getContext: vi.fn().mockReturnValue(fakeCtx),
+      toDataURL: vi.fn().mockReturnValue("data:image/png;base64,composited"),
+    };
+    vi.stubGlobal("document", {
+      createElement: vi.fn().mockReturnValue(fakeCanvas),
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        blob: vi.fn().mockResolvedValue({}),
+      }),
+    );
+    vi.stubGlobal("URL", {
+      createObjectURL: vi.fn().mockReturnValue("blob:fake"),
+      revokeObjectURL: vi.fn(),
+    });
+    class FakeImage {
+      onload: (() => void) | null = null;
+      onerror: (() => void) | null = null;
+      set src(_value: string) {
+        // Resolve asynchronously like a real Image decode.
+        queueMicrotask(() => this.onload?.());
+      }
+    }
+    vi.stubGlobal("Image", FakeImage);
+
+    callAction.mockImplementation((name: string) => {
+      if (name === "take-design-screenshot") {
+        return Promise.resolve({
+          ok: true,
+          screenshots: [{ url: "https://cdn.example.com/shot.png" }],
+        });
+      }
+      if (name === "upload-image") {
+        return Promise.resolve({
+          url: "https://cdn.example.com/annotated-shot.png",
+        });
+      }
+      throw new Error(`unexpected action ${name}`);
+    });
+
+    const result = await captureAnnotatedScreenshot(baseOptions);
+
+    expect(result).toBe("https://cdn.example.com/annotated-shot.png");
+    expect(fakeCtx.drawImage).toHaveBeenCalledOnce();
+    expect(fakeCtx.stroke).toHaveBeenCalledOnce();
+    expect(callAction).toHaveBeenCalledWith(
+      "upload-image",
+      expect.objectContaining({ data: "data:image/png;base64,composited" }),
+    );
+  });
+});
diff --git a/templates/design/app/components/design/design-canvas/annotation-snapshot.ts b/templates/design/app/components/design/design-canvas/annotation-snapshot.ts
new file mode 100644
index 0000000000..76e550b152
--- /dev/null
+++ b/templates/design/app/components/design/design-canvas/annotation-snapshot.ts
@@ -0,0 +1,265 @@
+import { callAction } from "@agent-native/core/client";
+
+import type { DrawAnnotation } from "@/components/visual-editor";
+
+/**
+ * Draw-to-agent visual capture.
+ *
+ * DrawOverlay's `onSend` still hands the caller a text summary of stroke
+ * paths and text labels (see DesignCanvas's `onSend` wiring) — that stays,
+ * because raw coordinates remain useful for precision edits. This module
+ * additionally rasterizes the annotated screen into ONE PNG the agent can
+ * actually see, mirroring the Claude-design-style "draw over a screenshot"
+ * flow instead of forcing the agent to reconstruct a picture from
+ * coordinates alone.
+ *
+ * Pipeline: reuse `take-design-screenshot` (already renders the live screen
+ * server-side via headless Chromium — see that action's docblock) at the
+ * exact on-screen rect the user drew on, composite the serialized
+ * strokes/text on top client-side, then hand the finished PNG to the shared
+ * `upload-image` core action so only a durable URL — never base64 — reaches
+ * the agent chat message or any persisted state.
+ *
+ * Every step degrades silently to `null` (no thrown errors): a missing
+ * Chromium binary in hosted/serverless deploys, a slow render, a network
+ * blip fetching the screenshot, or an unconfigured upload provider should
+ * never block the user's drawing from reaching the agent as text — see
+ * `captureAnnotatedScreenshot`'s caller in DesignCanvas.tsx, which always
+ * falls through to the text-only summary.
+ */
+
+/** Bounds the whole capture pipeline so a slow/hung Chromium render or
+ * upload never leaves the user waiting indefinitely to see their message
+ * land in chat. Generous enough for a local Playwright cold start. */
+const CAPTURE_TIMEOUT_MS = 9000;
+
+const MIN_DIMENSION_PX = 200;
+const MAX_WIDTH_PX = 3840;
+const MAX_HEIGHT_PX = 4096;
+
+interface TakeDesignScreenshotResult {
+  ok: boolean;
+  reason?: string;
+  screenshots?: Array<{ url?: string }>;
+}
+
+interface UploadImageResult {
+  url?: string;
+  error?: string;
+}
+
+export interface CaptureAnnotatedScreenshotOptions {
+  /** Stable design id — used as fallback screen lookup and upload filename. */
+  designId?: string;
+  /** Specific design_files.id for the annotated screen. Preferred lookup key. */
+  fileId?: string;
+  /** Filename fallback when `fileId` is not available (paired with `designId`). */
+  filename?: string;
+  /** Only inline (SQL-backed HTML) screens can be rendered by take-design-screenshot. */
+  sourceType?: "inline" | "localhost" | "fusion";
+  annotations: DrawAnnotation[];
+  /** Layout-space canvas size the annotations were serialized against. */
+  canvasSize: { width: number; height: number };
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(`annotation screenshot capture timed out after ${ms}ms`),
+      );
+    }, ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+function loadImageFromUrl(url: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const image = new Image();
+    image.onload = () => resolve(image);
+    image.onerror = () =>
+      reject(new Error("Failed to decode screenshot image"));
+    image.src = url;
+  });
+}
+
+/**
+ * Draw one annotation (a stroke path or a text label) onto a 2D canvas
+ * context, in the same layout-pixel coordinate space DrawOverlay used when
+ * it serialized `pathData`/`position` in its own `send()` — see
+ * DrawOverlay.tsx's coordinate-model docblock. Parses the "M x,y L x,y ..."
+ * syntax with a small regex instead of `new Path2D(...)`: this is the exact
+ * (and only) format DrawOverlay's `send()` emits, and avoiding Path2D keeps
+ * this rasterizer testable against a plain fake context object — Path2D
+ * isn't implemented in jsdom/happy-dom, only real browsers. Exported for unit
+ * testing against a fake context (canvas 2D isn't implemented in jsdom).
+ */
+export function drawAnnotationsOnContext(
+  ctx: Pick<
+    CanvasRenderingContext2D,
+    | "save"
+    | "restore"
+    | "beginPath"
+    | "moveTo"
+    | "lineTo"
+    | "stroke"
+    | "fillText"
+    | "strokeStyle"
+    | "fillStyle"
+    | "lineWidth"
+    | "lineCap"
+    | "lineJoin"
+    | "font"
+    | "textBaseline"
+  >,
+  annotations: DrawAnnotation[],
+): void {
+  for (const annotation of annotations) {
+    if (annotation.type === "path" && annotation.pathData) {
+      const points = parsePathDataPoints(annotation.pathData);
+      if (points.length < 2) continue;
+      ctx.save();
+      ctx.strokeStyle = annotation.color;
+      ctx.lineWidth = annotation.lineWidth;
+      ctx.lineCap = "round";
+      ctx.lineJoin = "round";
+      ctx.beginPath();
+      ctx.moveTo(points[0].x, points[0].y);
+      for (let i = 1; i < points.length; i++) {
+        ctx.lineTo(points[i].x, points[i].y);
+      }
+      ctx.stroke();
+      ctx.restore();
+    } else if (annotation.type === "text" && annotation.text) {
+      ctx.save();
+      ctx.fillStyle = annotation.color;
+      ctx.font = `600 ${14 + annotation.lineWidth}px sans-serif`;
+      ctx.textBaseline = "top";
+      ctx.fillText(
+        annotation.text,
+        annotation.position.x,
+        annotation.position.y,
+      );
+      ctx.restore();
+    }
+  }
+}
+
+const PATH_DATA_POINT_RE = /[ML]\s*(-?[\d.]+),(-?[\d.]+)/g;
+
+/** Parse DrawOverlay's `"M x,y L x,y L x,y"` path syntax into raw points. */
+function parsePathDataPoints(
+  pathData: string,
+): Array<{ x: number; y: number }> {
+  const points: Array<{ x: number; y: number }> = [];
+  for (const match of pathData.matchAll(PATH_DATA_POINT_RE)) {
+    points.push({ x: Number(match[1]), y: Number(match[2]) });
+  }
+  return points;
+}
+
+/** Fetch the screenshot bytes (avoids canvas cross-origin tainting — a
+ * same-process `fetch` + `Blob` object URL is never "foreign" to the canvas,
+ * regardless of the storage provider's CORS headers) and composite the
+ * annotations on top at the exact requested pixel size. */
+async function compositeScreenshotWithAnnotations(
+  screenshotUrl: string,
+  annotations: DrawAnnotation[],
+  size: { width: number; height: number },
+): Promise<string | null> {
+  const response = await fetch(screenshotUrl);
+  if (!response.ok) return null;
+  const blob = await response.blob();
+  const objectUrl = URL.createObjectURL(blob);
+  try {
+    const image = await loadImageFromUrl(objectUrl);
+    const canvas = document.createElement("canvas");
+    canvas.width = size.width;
+    canvas.height = size.height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return null;
+    ctx.drawImage(image, 0, 0, size.width, size.height);
+    drawAnnotationsOnContext(ctx, annotations);
+    return canvas.toDataURL("image/png");
+  } finally {
+    URL.revokeObjectURL(objectUrl);
+  }
+}
+
+/**
+ * Best-effort: render the annotated screen, composite the drawing on top,
+ * and upload the result. Returns the durable image URL, or `null` on ANY
+ * failure (missing Chromium, no upload provider configured, network error,
+ * unsupported source type, timeout) — callers must treat `null` as "fall
+ * back to the text-only summary", never as a reason to drop the annotation.
+ */
+export async function captureAnnotatedScreenshot(
+  options: CaptureAnnotatedScreenshotOptions,
+): Promise<string | null> {
+  const { designId, fileId, filename, sourceType, annotations, canvasSize } =
+    options;
+
+  // take-design-screenshot renders stored SQL/collab HTML content; localhost
+  // and fusion screens hold a URL, not renderable HTML, so skip straight to
+  // the text-only fallback for those instead of paying for a doomed render.
+  if (sourceType && sourceType !== "inline") return null;
+  if (!fileId && !designId) return null;
+  if (typeof document === "undefined") return null;
+  if (
+    !Number.isFinite(canvasSize.width) ||
+    !Number.isFinite(canvasSize.height) ||
+    canvasSize.width < MIN_DIMENSION_PX ||
+    canvasSize.height < MIN_DIMENSION_PX
+  ) {
+    return null;
+  }
+
+  const widthPx = Math.min(MAX_WIDTH_PX, Math.round(canvasSize.width));
+  const heightPx = Math.min(MAX_HEIGHT_PX, Math.round(canvasSize.height));
+
+  try {
+    return await withTimeout(
+      (async () => {
+        const shot = await callAction<TakeDesignScreenshotResult>(
+          "take-design-screenshot",
+          {
+            ...(fileId ? { fileId } : { designId, filename }),
+            widths: [widthPx],
+            heights: [heightPx],
+          },
+        );
+        const screenshotUrl = shot?.ok ? shot.screenshots?.[0]?.url : undefined;
+        if (!screenshotUrl) return null;
+
+        const compositeDataUrl = await compositeScreenshotWithAnnotations(
+          screenshotUrl,
+          annotations,
+          { width: widthPx, height: heightPx },
+        );
+        if (!compositeDataUrl) return null;
+
+        const uploaded = await callAction<UploadImageResult>("upload-image", {
+          data: compositeDataUrl,
+          filename: `design-annotation-${designId ?? fileId}-${Date.now()}.png`,
+        });
+        return uploaded?.url ?? null;
+      })(),
+      CAPTURE_TIMEOUT_MS,
+    );
+  } catch (error) {
+    console.warn(
+      "[DesignCanvas] annotated screenshot capture failed; falling back to text-only:",
+      error,
+    );
+    return null;
+  }
+}
diff --git a/templates/design/app/components/design/design-canvas/annotation-submit.test.ts b/templates/design/app/components/design/design-canvas/annotation-submit.test.ts
index 4a9eb4711b..a56da43977 100644
--- a/templates/design/app/components/design/design-canvas/annotation-submit.test.ts
+++ b/templates/design/app/components/design/design-canvas/annotation-submit.test.ts
@@ -3,13 +3,13 @@ import { describe, expect, it, vi } from "vitest";
 import { submitDesignAnnotations } from "./annotation-submit";
 
 describe("submitDesignAnnotations", () => {
-  it("commits queued pins and exits draw mode after chat accepts the batch", () => {
+  it("commits queued pins and exits draw mode after chat accepts the batch", async () => {
     const send = vi.fn();
     const markQueuedPinsSubmitted = vi.fn();
     const exitDrawMode = vi.fn();
     const onError = vi.fn();
 
-    expect(
+    await expect(
       submitDesignAnnotations({
         message: "annotate this",
         hasQueuedPins: true,
@@ -18,20 +18,49 @@ describe("submitDesignAnnotations", () => {
         exitDrawMode,
         onError,
       }),
-    ).toBe(true);
+    ).resolves.toBe(true);
     expect(send).toHaveBeenCalledWith("annotate this");
     expect(markQueuedPinsSubmitted).toHaveBeenCalledOnce();
     expect(exitDrawMode).toHaveBeenCalledOnce();
     expect(onError).not.toHaveBeenCalled();
   });
 
-  it("keeps queued pins and draw mode intact when chat handoff fails", () => {
+  it("does not clear annotation work while delivery confirmation is pending", async () => {
+    let confirmDelivery!: () => void;
+    const send = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          confirmDelivery = resolve;
+        }),
+    );
+    const markQueuedPinsSubmitted = vi.fn();
+    const exitDrawMode = vi.fn();
+    const onError = vi.fn();
+
+    const submission = submitDesignAnnotations({
+      message: "annotate this",
+      hasQueuedPins: true,
+      send,
+      markQueuedPinsSubmitted,
+      exitDrawMode,
+      onError,
+    });
+    expect(markQueuedPinsSubmitted).not.toHaveBeenCalled();
+    expect(exitDrawMode).not.toHaveBeenCalled();
+
+    confirmDelivery();
+    await expect(submission).resolves.toBe(true);
+    expect(markQueuedPinsSubmitted).toHaveBeenCalledOnce();
+    expect(exitDrawMode).toHaveBeenCalledOnce();
+  });
+
+  it("keeps queued pins and draw mode intact when chat handoff throws synchronously", async () => {
     const error = new Error("chat unavailable");
     const markQueuedPinsSubmitted = vi.fn();
     const exitDrawMode = vi.fn();
     const onError = vi.fn();
 
-    expect(
+    await expect(
       submitDesignAnnotations({
         message: "annotate this",
         hasQueuedPins: true,
@@ -42,9 +71,36 @@ describe("submitDesignAnnotations", () => {
         exitDrawMode,
         onError,
       }),
-    ).toBe(false);
+    ).resolves.toBe(false);
     expect(markQueuedPinsSubmitted).not.toHaveBeenCalled();
     expect(exitDrawMode).not.toHaveBeenCalled();
     expect(onError).toHaveBeenCalledWith(error);
   });
+
+  it("keeps queued pins and draw mode intact when delivery is not confirmed (silent drop)", async () => {
+    // Mirrors sendToAgentChatAndConfirm resolving `delivered: false` (e.g. no
+    // LLM/agent engine configured) — the caller turns that into a rejection
+    // instead of resolving silently, so the annotation work is never lost.
+    const markQueuedPinsSubmitted = vi.fn();
+    const exitDrawMode = vi.fn();
+    const onError = vi.fn();
+
+    await expect(
+      submitDesignAnnotations({
+        message: "annotate this",
+        hasQueuedPins: true,
+        send: async () => {
+          throw new Error(
+            "Message was not delivered to the agent chat (missing-engine)",
+          );
+        },
+        markQueuedPinsSubmitted,
+        exitDrawMode,
+        onError,
+      }),
+    ).resolves.toBe(false);
+    expect(markQueuedPinsSubmitted).not.toHaveBeenCalled();
+    expect(exitDrawMode).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledOnce();
+  });
 });
diff --git a/templates/design/app/components/design/design-canvas/annotation-submit.ts b/templates/design/app/components/design/design-canvas/annotation-submit.ts
index 5c7859c9f5..26fb6be3f5 100644
--- a/templates/design/app/components/design/design-canvas/annotation-submit.ts
+++ b/templates/design/app/components/design/design-canvas/annotation-submit.ts
@@ -1,7 +1,14 @@
 interface SubmitDesignAnnotationsOptions {
   message: string;
   hasQueuedPins: boolean;
-  send: (message: string) => void;
+  /**
+   * Deliver the message to the agent chat. Must reject (or throw) when
+   * delivery is not confirmed — e.g. `sendToAgentChatAndConfirm` resolving
+   * `delivered: false` should be turned into a thrown/rejected error here.
+   * A `send` that only fires-and-forgets (never throws on silent drops) will
+   * make this function report success even though nothing reached the agent.
+   */
+  send: (message: string) => void | Promise<void>;
   markQueuedPinsSubmitted: () => void;
   exitDrawMode: () => void;
   onError: (error: unknown) => void;
@@ -11,18 +18,22 @@ interface SubmitDesignAnnotationsOptions {
  * Submit a drawing/comment batch as one atomic UI transition.
  *
  * The overlay and queued pins must remain intact when chat handoff fails so the
- * user can retry without recreating their annotation work.
+ * user can retry without recreating their annotation work. `send` is awaited
+ * so a caller using an ack-confirmed delivery (e.g.
+ * `sendToAgentChatAndConfirm`) can reject when the message was silently
+ * dropped (no LLM/agent engine configured, panel never mounted, etc.) — the
+ * pins/draw-mode teardown below only runs once delivery is confirmed.
  */
-export function submitDesignAnnotations({
+export async function submitDesignAnnotations({
   message,
   hasQueuedPins,
   send,
   markQueuedPinsSubmitted,
   exitDrawMode,
   onError,
-}: SubmitDesignAnnotationsOptions): boolean {
+}: SubmitDesignAnnotationsOptions): Promise<boolean> {
   try {
-    send(message);
+    await send(message);
   } catch (error) {
     onError(error);
     return false;
diff --git a/templates/design/app/components/design/design-canvas/coordinate-transforms.test.ts b/templates/design/app/components/design/design-canvas/coordinate-transforms.test.ts
new file mode 100644
index 0000000000..8220af7c48
--- /dev/null
+++ b/templates/design/app/components/design/design-canvas/coordinate-transforms.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+
+import { getScreenContentPointFromClient } from "./coordinate-transforms";
+
+describe("getScreenContentPointFromClient — scrollOffset", () => {
+  it("defaults to {left: 0, top: 0} when omitted (pre-existing unscrolled behavior)", () => {
+    const point = getScreenContentPointFromClient(
+      150,
+      220,
+      { left: 100, top: 50, width: 800, height: 600 },
+      { width: 800, height: 600 },
+    );
+    expect(point).toEqual({ x: 50, y: 170 });
+  });
+
+  it("adds an unscaled scroll offset directly, NOT divided/multiplied by scale", () => {
+    // 50% host zoom: the iframe's rendered rect is half its own content
+    // (iframe.clientWidth/Height) box, so scaleX = scaleY = 0.5. The screen
+    // is scrolled 600px down internally. A click at the iframe's visible top
+    // edge (rendered content y offset = 0) must land at content y = 600 —
+    // not 1200 (mistakenly dividing the scroll by scale) and not 300
+    // (mistakenly multiplying the scroll by scale). The scroll offset is
+    // already expressed in the iframe's own unscaled content pixels — the
+    // same units `iframeContentSize` and the return value use — so it must
+    // be added as-is, after the scale division has already been applied to
+    // the client-to-rect delta.
+    const point = getScreenContentPointFromClient(
+      100, // clientX === iframeRect.left (visible left edge)
+      50, // clientY === iframeRect.top (visible top edge)
+      { left: 100, top: 50, width: 400, height: 300 },
+      { width: 800, height: 600 },
+      { left: 0, top: 600 },
+    );
+    expect(point).toEqual({ x: 0, y: 600 });
+  });
+
+  it("combines a non-zero rendered offset with scroll (50% zoom)", () => {
+    // 200px into the rendered (zoomed) rect at 50% scale = 400 unscaled
+    // content px, plus a 600px vertical scroll and 50px horizontal scroll.
+    const point = getScreenContentPointFromClient(
+      100 + 200,
+      50 + 150,
+      { left: 100, top: 50, width: 400, height: 300 },
+      { width: 800, height: 600 },
+      { left: 50, top: 600 },
+    );
+    expect(point).toEqual({ x: 400 + 50, y: 300 + 600 });
+  });
+
+  it("adds scroll unchanged at 100% zoom (rect matches content size)", () => {
+    const point = getScreenContentPointFromClient(
+      150,
+      220,
+      { left: 100, top: 50, width: 800, height: 600 },
+      { width: 800, height: 600 },
+      { left: 10, top: 20 },
+    );
+    expect(point).toEqual({ x: 50 + 10, y: 170 + 20 });
+  });
+
+  it("adds scroll unchanged even when content size is zero/unknown (scale falls back to 1)", () => {
+    const point = getScreenContentPointFromClient(
+      140,
+      95,
+      { left: 40, top: 45, width: 0, height: 0 },
+      { width: 0, height: 0 },
+      { left: 5, top: 5 },
+    );
+    expect(point).toEqual({ x: 100 + 5, y: 50 + 5 });
+  });
+
+  it("undoes a zoomed-in outer transform (rect larger than content size) with scroll", () => {
+    // A 200% zoom wrapper renders the iframe's rect at double its content
+    // size, so scale = 2. 100 rendered px at 200% scale = 50 content px.
+    const point = getScreenContentPointFromClient(
+      10 + 100,
+      20 + 60,
+      { left: 10, top: 20, width: 1600, height: 1200 },
+      { width: 800, height: 600 },
+      { left: 30, top: 40 },
+    );
+    expect(point).toEqual({ x: 50 + 30, y: 30 + 40 });
+  });
+});
diff --git a/templates/design/app/components/design/design-canvas/coordinate-transforms.ts b/templates/design/app/components/design/design-canvas/coordinate-transforms.ts
index 5dd490007d..5c7d7e8a8b 100644
--- a/templates/design/app/components/design/design-canvas/coordinate-transforms.ts
+++ b/templates/design/app/components/design/design-canvas/coordinate-transforms.ts
@@ -1,11 +1,25 @@
 /**
  * Converts a viewport point into the iframe's unscaled content coordinates.
+ *
+ * `scrollOffset` is the embedded screen's own internal document scroll
+ * (`iframe.contentWindow.scrollX/scrollY`), already expressed in the iframe's
+ * own unscaled content pixels — the SAME units as `iframeContentSize` and the
+ * function's return value. It is folded in AFTER the scale division, never
+ * multiplied/divided by `scaleX`/`scaleY`: the outer `scaleX`/`scaleY` factor
+ * only undoes the *host* canvas's zoom transform (which maps `iframeRect`,
+ * a host-viewport rect, onto `iframeContentSize`, the iframe's own layout
+ * box) and has nothing to do with how far the iframe's own document has been
+ * scrolled internally. Concretely: at 50% host zoom (scaleX = 0.5) with the
+ * embedded screen scrolled 600px down, a click at the iframe's visible top
+ * edge (rendered content y = 0) must land at content y = 600 — not 1200 (a
+ * mistaken `600 / 0.5`) and not 300 (a mistaken `600 * 0.5`).
  */
 export function getScreenContentPointFromClient(
   clientX: number,
   clientY: number,
   iframeRect: { left: number; top: number; width: number; height: number },
   iframeContentSize: { width: number; height: number },
+  scrollOffset: { left: number; top: number } = { left: 0, top: 0 },
 ): { x: number; y: number } {
   const scaleX =
     iframeContentSize.width > 0
@@ -16,8 +30,8 @@ export function getScreenContentPointFromClient(
       ? iframeRect.height / iframeContentSize.height
       : 1;
   return {
-    x: (clientX - iframeRect.left) / (scaleX || 1),
-    y: (clientY - iframeRect.top) / (scaleY || 1),
+    x: (clientX - iframeRect.left) / (scaleX || 1) + scrollOffset.left,
+    y: (clientY - iframeRect.top) / (scaleY || 1) + scrollOffset.top,
   };
 }
 
diff --git a/templates/design/app/components/design/design-canvas/embedded-frame.ts b/templates/design/app/components/design/design-canvas/embedded-frame.ts
index a53c7dd905..18500035a5 100644
--- a/templates/design/app/components/design/design-canvas/embedded-frame.ts
+++ b/templates/design/app/components/design/design-canvas/embedded-frame.ts
@@ -25,9 +25,14 @@ export function getEmbeddedIframeBackgroundColor(args: {
     : (args.embeddedFrameBackground ?? "transparent");
 }
 
-export function embeddedContentOffsetStyle(x: number, y: number): string {
+export function embeddedContentOffsetCss(x: number, y: number): string {
   if (x === 0 && y === 0) return "";
-  return `<style data-agent-native-content-offset>body > [data-agent-native-node-id]{translate:${Math.round(x)}px ${Math.round(y)}px;}</style>`;
+  return `body > [data-agent-native-node-id]{translate:${Math.round(x)}px ${Math.round(y)}px;}`;
+}
+
+export function embeddedContentOffsetStyle(x: number, y: number): string {
+  const css = embeddedContentOffsetCss(x, y);
+  return css ? `<style data-agent-native-content-offset>${css}</style>` : "";
 }
 
 function injectEmbeddedFrameStyle(content: string, style: string): string {
diff --git a/templates/design/app/components/design/design-canvas/iframe-events.ts b/templates/design/app/components/design/design-canvas/iframe-events.ts
index ea2fb02c07..5500c6afba 100644
--- a/templates/design/app/components/design/design-canvas/iframe-events.ts
+++ b/templates/design/app/components/design/design-canvas/iframe-events.ts
@@ -1,4 +1,4 @@
-import type { ElementInfo } from "../types";
+import type { CanvasLayerHitCandidate, ElementInfo } from "../types";
 
 export interface IframeHotkeyPayload {
   key: string;
@@ -15,9 +15,11 @@ export interface IframeFigmaClipboardPastePayload {
 }
 
 export interface IframeContextMenuPayload {
+  screenId?: string;
   clientX: number;
   clientY: number;
   viewportClientX?: number;
   viewportClientY?: number;
   info?: ElementInfo | null;
+  layerCandidates?: CanvasLayerHitCandidate[];
 }
diff --git a/templates/design/app/components/design/edit-panel/code-inspect-helpers.spec.ts b/templates/design/app/components/design/edit-panel/code-inspect-helpers.spec.ts
new file mode 100644
index 0000000000..741d33f815
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/code-inspect-helpers.spec.ts
@@ -0,0 +1,236 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  alpineDataValueLiteral,
+  canRebuildAlpineDataLosslessly,
+  elementHtmlPreview,
+  formatInspectCodeOpeningTag,
+  isBooleanPropValue,
+  openingTagOf,
+  parseAlpineDataObject,
+  replaceAlpineDataKeyValue,
+  serializeAlpineDataObject,
+  truncateOpeningTag,
+} from "./code-inspect-helpers";
+
+// ---------------------------------------------------------------------------
+// parseAlpineDataObject — regression guard for the escaped-quote bug: a
+// string value containing a backslash-escaped quote (e.g. Alpine data like
+// `{ label: 'it\'s ok' }`, a very ordinary English-text prop value) used to
+// truncate at the escaped quote, silently dropping the remainder of the
+// string instead of decoding it back to the literal apostrophe.
+// ---------------------------------------------------------------------------
+
+describe("parseAlpineDataObject", () => {
+  it("parses simple flat string/boolean/number literals", () => {
+    expect(
+      parseAlpineDataObject("{ variant: 'outline', size: 'lg', open: false }"),
+    ).toEqual({ variant: "outline", size: "lg", open: "false" });
+  });
+
+  it("decodes a backslash-escaped single quote inside a single-quoted value", () => {
+    expect(parseAlpineDataObject("{ label: 'it\\'s ok' }")).toEqual({
+      label: "it's ok",
+    });
+  });
+
+  it("decodes a backslash-escaped double quote inside a double-quoted value", () => {
+    expect(parseAlpineDataObject('{ label: "she said \\"hi\\"" }')).toEqual({
+      label: 'she said "hi"',
+    });
+  });
+
+  it("does not require escaping the opposite quote style", () => {
+    // A single-quoted value may contain a literal double quote (and vice
+    // versa) with no escaping at all — only the matching quote needs escapes.
+    expect(parseAlpineDataObject("{ label: 'she said \"hi\"' }")).toEqual({
+      label: 'she said "hi"',
+    });
+  });
+
+  it("returns null for a value richer than a flat literal (nested object)", () => {
+    expect(parseAlpineDataObject("{ config: { a: 1 } }")).toBeNull();
+  });
+
+  it("returns null when the literal isn't an object at all", () => {
+    expect(parseAlpineDataObject("notAnObject")).toBeNull();
+    expect(parseAlpineDataObject(null)).toBeNull();
+    expect(parseAlpineDataObject(undefined)).toBeNull();
+  });
+
+  it("returns an empty object for an empty literal", () => {
+    expect(parseAlpineDataObject("{}")).toEqual({});
+  });
+});
+
+describe("serializeAlpineDataObject / alpineDataValueLiteral", () => {
+  it("round-trips a value containing an apostrophe through escape/unescape", () => {
+    const original = "it's ok";
+    const literal = alpineDataValueLiteral(original);
+    expect(literal).toBe("'it\\'s ok'");
+    const serialized = serializeAlpineDataObject({ label: original });
+    expect(parseAlpineDataObject(serialized)).toEqual({ label: original });
+  });
+
+  it("keeps booleans and numbers unquoted", () => {
+    expect(serializeAlpineDataObject({ open: "true", count: "3" })).toBe(
+      "{ open: true, count: 3 }",
+    );
+  });
+});
+
+describe("canRebuildAlpineDataLosslessly", () => {
+  it("is true for an absent or empty literal", () => {
+    expect(canRebuildAlpineDataLosslessly(undefined)).toBe(true);
+    expect(canRebuildAlpineDataLosslessly(null)).toBe(true);
+    expect(canRebuildAlpineDataLosslessly("{}")).toBe(true);
+    expect(canRebuildAlpineDataLosslessly("{ }")).toBe(true);
+  });
+
+  it("is true for a flat object of simple literals", () => {
+    expect(
+      canRebuildAlpineDataLosslessly(
+        "{ variant: 'outline', size: 'lg', open: false, count: 3 }",
+      ),
+    ).toBe(true);
+  });
+
+  it("is true for a flat object whose only string value contains an escaped quote (no longer a false positive from truncation — the value now decodes and re-encodes to the exact same source)", () => {
+    expect(canRebuildAlpineDataLosslessly("{ label: 'it\\'s ok' }")).toBe(true);
+  });
+
+  it("is false when the literal holds a method (richer than simple literals)", () => {
+    expect(
+      canRebuildAlpineDataLosslessly(
+        "{ open: false, toggle() { this.open = !this.open } }",
+      ),
+    ).toBe(false);
+  });
+
+  it("is false when the literal holds a nested object", () => {
+    expect(canRebuildAlpineDataLosslessly("{ config: { a: 1 } }")).toBe(false);
+  });
+
+  it("is false when the literal isn't a `{ … }` object at all", () => {
+    expect(canRebuildAlpineDataLosslessly("someExpression()")).toBe(false);
+  });
+});
+
+describe("replaceAlpineDataKeyValue", () => {
+  it("surgically replaces one key's value, preserving everything else", () => {
+    expect(
+      replaceAlpineDataKeyValue(
+        "{ variant: 'outline', toggle() { this.open = !this.open } }",
+        "variant",
+        "solid",
+      ),
+    ).toBe("{ variant: 'solid', toggle() { this.open = !this.open } }");
+  });
+
+  it("returns null when the key's current value is not a simple literal", () => {
+    expect(
+      replaceAlpineDataKeyValue("{ config: { a: 1 } }", "config", "x"),
+    ).toBeNull();
+  });
+
+  it("handles an escaped quote inside the ORIGINAL value while locating it", () => {
+    // The target value itself contains an escaped quote before the key we're
+    // replacing — the walk must skip over it correctly rather than getting
+    // confused by the embedded quote.
+    expect(
+      replaceAlpineDataKeyValue(
+        "{ label: 'it\\'s ok', variant: 'outline' }",
+        "variant",
+        "solid",
+      ),
+    ).toBe("{ label: 'it\\'s ok', variant: 'solid' }");
+  });
+});
+
+describe("isBooleanPropValue", () => {
+  it("is true for true/false, case-insensitively", () => {
+    expect(isBooleanPropValue("true")).toBe(true);
+    expect(isBooleanPropValue("FALSE")).toBe(true);
+    expect(isBooleanPropValue(" True ")).toBe(true);
+  });
+
+  it("is false for any other string, including boolean-suggestive text", () => {
+    expect(isBooleanPropValue("yes")).toBe(false);
+    expect(isBooleanPropValue("1")).toBe(false);
+    expect(isBooleanPropValue("")).toBe(false);
+  });
+});
+
+describe("openingTagOf / truncateOpeningTag / elementHtmlPreview", () => {
+  it("extracts the opening tag including attributes", () => {
+    expect(openingTagOf('<main class="hero" data-x="y">body</main>')).toBe(
+      '<main class="hero" data-x="y">',
+    );
+  });
+
+  it("returns null when no tag can be parsed", () => {
+    expect(openingTagOf("plain text")).toBeNull();
+    expect(openingTagOf(null)).toBeNull();
+    expect(openingTagOf(undefined)).toBeNull();
+  });
+
+  it("truncates a long attribute value while preserving surrounding quotes", () => {
+    const openTag =
+      '<div class="a-really-long-class-name-that-goes-on-and-on-and-on">';
+    const truncated = truncateOpeningTag(openTag, 10);
+    expect(truncated.startsWith('<div class="')).toBe(true);
+    expect(truncated.endsWith('…">')).toBe(true);
+  });
+
+  it("strips runtime and style attributes before measuring the inline tag", () => {
+    expect(
+      formatInspectCodeOpeningTag(
+        '<button data-agent-native-node-id="cta" data-agent-native-layer-name="Primary CTA" style="padding: 12px" type="button">',
+      ),
+    ).toBe('<button type="button">');
+  });
+
+  it("wraps retained attributes onto indented lines when the clean tag is long", () => {
+    expect(
+      formatInspectCodeOpeningTag(
+        '<button id="checkout-call-to-action" class="button button-primary" aria-label="Continue to checkout">',
+      ),
+    ).toBe(
+      '<button\n  id="checkout-call-to-action"\n  class="button button-primary"\n  aria-label="Continue to checkout">',
+    );
+  });
+
+  it("keeps short retained attributes inline", () => {
+    expect(formatInspectCodeOpeningTag('<input disabled name="email">')).toBe(
+      '<input disabled name="email">',
+    );
+  });
+
+  it("builds a fallback opening tag from metadata when there is no HTML", () => {
+    expect(
+      elementHtmlPreview({
+        html: null,
+        tagName: "button",
+        id: "cta",
+        classes: ["btn", "btn-primary"],
+      }),
+    ).toBe('<button id="cta" class="btn btn-primary">\n  ...\n</button>');
+  });
+
+  it("returns null when there is neither HTML nor any fallback metadata", () => {
+    expect(
+      elementHtmlPreview({ html: null, tagName: null, id: null, classes: [] }),
+    ).toBeNull();
+  });
+
+  it("renders a self-closing void tag without a closing-tag suffix", () => {
+    expect(
+      elementHtmlPreview({
+        html: '<img src="a.png">',
+        tagName: "img",
+        id: null,
+        classes: [],
+      }),
+    ).toBe('<img src="a.png">');
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/code-inspect-helpers.tsx b/templates/design/app/components/design/edit-panel/code-inspect-helpers.tsx
index 6c0ae1ba3a..9e7353d19e 100644
--- a/templates/design/app/components/design/edit-panel/code-inspect-helpers.tsx
+++ b/templates/design/app/components/design/edit-panel/code-inspect-helpers.tsx
@@ -19,6 +19,14 @@ const VOID_HTML_TAGS = new Set([
   "wbr",
 ]);
 
+const INSPECT_CODE_MAX_INLINE_TAG_LENGTH = 48;
+
+interface ParsedOpeningTag {
+  tagName: string;
+  attributes: string[];
+  closing: ">" | "/>";
+}
+
 export function normalizedElementTagName(
   tagName: string | null | undefined,
 ): string {
@@ -72,6 +80,58 @@ export function truncateOpeningTag(openTag: string, max = 32): string {
   );
 }
 
+function parseInspectCodeOpeningTag(openTag: string): ParsedOpeningTag | null {
+  const tagMatch = /^<([a-zA-Z][\w:-]*)([\s\S]*?)(\/?>)$/.exec(openTag.trim());
+  if (!tagMatch?.[1] || (tagMatch[3] !== ">" && tagMatch[3] !== "/>")) {
+    return null;
+  }
+
+  const attributes: string[] = [];
+  const attributePattern =
+    /\s+([^\s=/>]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s"'=<>`]+))?/g;
+  for (const match of (tagMatch[2] ?? "").matchAll(attributePattern)) {
+    const name = match[1];
+    if (!name) continue;
+    const normalizedName = name.toLowerCase();
+    if (
+      normalizedName === "style" ||
+      normalizedName.startsWith("data-agent-native-")
+    ) {
+      continue;
+    }
+    attributes.push(`${name}${match[2] ? `=${match[2]}` : ""}`);
+  }
+
+  return {
+    tagName: tagMatch[1],
+    attributes,
+    closing: tagMatch[3],
+  };
+}
+
+/**
+ * Remove Design's runtime-only attributes, then format retained attributes to
+ * fit the Inspect Code popover without routine horizontal scrolling.
+ */
+export function formatInspectCodeOpeningTag(
+  openTag: string,
+  maxInlineLength = INSPECT_CODE_MAX_INLINE_TAG_LENGTH,
+): string {
+  const parsed = parseInspectCodeOpeningTag(openTag);
+  if (!parsed) return openTag;
+
+  const inline = `<${parsed.tagName}${
+    parsed.attributes.length ? ` ${parsed.attributes.join(" ")}` : ""
+  }${parsed.closing}`;
+  if (!parsed.attributes.length || inline.length <= maxInlineLength) {
+    return inline;
+  }
+
+  return `<${parsed.tagName}\n  ${parsed.attributes.join("\n  ")}${
+    parsed.closing
+  }`;
+}
+
 function tagNameFromOpeningTag(openTag: string): string | null {
   const match = /^<\/?\s*([a-zA-Z][\w:-]*)/.exec(openTag.trim());
   return match?.[1]?.toLowerCase() ?? null;
@@ -113,7 +173,9 @@ export function elementHtmlPreview(
     data.classes?.some((item) => item.trim()),
   );
   if (!openingTag && !hasFallbackMetadata) return null;
-  const previewOpeningTag = openingTag ?? fallbackOpeningTag(data);
+  const previewOpeningTag = formatInspectCodeOpeningTag(
+    openingTag ?? fallbackOpeningTag(data),
+  );
   const tagName =
     tagNameFromOpeningTag(previewOpeningTag) ??
     normalizedElementTagName(data.tagName);
@@ -229,20 +291,28 @@ export function parseAlpineDataObject(
 
   const out: Record<string, string> = {};
   // Split on top-level commas only (no nesting / quotes inside values here).
+  // The quoted-value alternatives allow backslash-escaped quotes (`\\.`)
+  // inside the literal — without that, a value like `'it\'s ok'` truncates
+  // at the escaped quote (matching only `'it\'`), silently dropping the rest
+  // of the string. That mismatch used to slip past `canRebuildAlpineDataLosslessly`
+  // as a false positive: the truncated value round-tripped "stably" (in the
+  // sense of parse -> serialize -> parse staying self-consistent) while still
+  // being wrong relative to the original source.
   const pairRe =
-    /(?:^|,)\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$]*))\s*:\s*('[^']*'|"[^"]*"|true|false|-?\d+(?:\.\d+)?)/g;
+    /(?:^|,)\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$]*))\s*:\s*('(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"|true|false|-?\d+(?:\.\d+)?)/g;
   let m: RegExpExecArray | null;
   let matched = false;
   while ((m = pairRe.exec(inner)) !== null) {
     matched = true;
     const key = m[1] ?? m[2] ?? m[3];
     let raw = m[4]!;
-    // Unwrap quotes for string literals; keep booleans / numbers verbatim.
-    if (
-      (raw.startsWith("'") && raw.endsWith("'")) ||
-      (raw.startsWith('"') && raw.endsWith('"'))
-    ) {
-      raw = raw.slice(1, -1);
+    // Unwrap quotes for string literals, un-escaping backslash-escaped quotes
+    // back to their literal form (the inverse of the escaping
+    // `serializeAlpineDataObject` applies); keep booleans / numbers verbatim.
+    if (raw.startsWith("'") && raw.endsWith("'")) {
+      raw = raw.slice(1, -1).replace(/\\'/g, "'");
+    } else if (raw.startsWith('"') && raw.endsWith('"')) {
+      raw = raw.slice(1, -1).replace(/\\"/g, '"');
     }
     if (key) out[key] = raw;
   }
diff --git a/templates/design/app/components/design/edit-panel/component-section.spec.ts b/templates/design/app/components/design/edit-panel/component-section.spec.ts
new file mode 100644
index 0000000000..b57e5c10d7
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/component-section.spec.ts
@@ -0,0 +1,54 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+
+import { isMessageFromOwnPreviewIframe } from "./component-section";
+
+// ---------------------------------------------------------------------------
+// isMessageFromOwnPreviewIframe — message.source validation for the
+// "element-select" listener (Bug: component-section's window "message"
+// listener trusted event.data with zero event.source/event.origin
+// validation, unlike every other bridge listener in the app).
+// ---------------------------------------------------------------------------
+
+describe("isMessageFromOwnPreviewIframe", () => {
+  function appendPreviewIframe(): HTMLIFrameElement {
+    const iframe = document.createElement("iframe");
+    iframe.setAttribute("data-design-preview-iframe", "");
+    document.body.appendChild(iframe);
+    return iframe;
+  }
+
+  it("returns false when there is no source window", () => {
+    expect(isMessageFromOwnPreviewIframe(null)).toBe(false);
+  });
+
+  it("returns false when the source is not one of our own preview iframes", () => {
+    appendPreviewIframe();
+    const otherIframe = document.createElement("iframe");
+    document.body.appendChild(otherIframe);
+
+    expect(isMessageFromOwnPreviewIframe(otherIframe.contentWindow)).toBe(
+      false,
+    );
+
+    document.body.removeChild(otherIframe);
+    document.querySelectorAll("iframe").forEach((el) => el.remove());
+  });
+
+  it("returns true when the source matches a design-preview iframe's contentWindow", () => {
+    const iframe = appendPreviewIframe();
+
+    expect(isMessageFromOwnPreviewIframe(iframe.contentWindow)).toBe(true);
+
+    document.querySelectorAll("iframe").forEach((el) => el.remove());
+  });
+
+  it("returns true when multiple preview iframes are present and the source matches any of them", () => {
+    appendPreviewIframe();
+    const second = appendPreviewIframe();
+
+    expect(isMessageFromOwnPreviewIframe(second.contentWindow)).toBe(true);
+
+    document.querySelectorAll("iframe").forEach((el) => el.remove());
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/component-section.tsx b/templates/design/app/components/design/edit-panel/component-section.tsx
index ab9a3ae7ff..b4e779ac87 100644
--- a/templates/design/app/components/design/edit-panel/component-section.tsx
+++ b/templates/design/app/components/design/edit-panel/component-section.tsx
@@ -1,18 +1,30 @@
-import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+import {
+  useActionMutation,
+  useActionQuery,
+  useT,
+} from "@agent-native/core/client";
 import { propNameToDataAttribute } from "@shared/component-model";
 import {
   IconArrowRight,
+  IconArrowsLeftRight,
   IconCode,
+  IconComponents,
   IconExternalLink,
   IconLoader2,
+  IconUnlink,
 } from "@tabler/icons-react";
 import { useQueryClient } from "@tanstack/react-query";
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
 import {
   Select,
   SelectContent,
@@ -91,6 +103,7 @@ function MakeItRealCard({
    */
   featureLabel: string;
 }) {
+  const t = useT();
   const { data, isLoading } = useActionQuery<ConnectBuilderAppResult>(
     "connect-builder-app",
     { designId },
@@ -160,7 +173,7 @@ function MakeItRealCard({
           rel="noopener noreferrer"
           className="inline-flex h-6 shrink-0 items-center gap-1 rounded-md px-1.5 text-[10px] font-semibold text-[var(--design-editor-accent-color)] hover:bg-[var(--design-editor-panel-raised-bg)]"
         >
-          {"Open" /* i18n-ignore make-it-real card */}
+          {t("designEditor.makeItRealCard.open")}
           <IconExternalLink className="size-2.5" />
         </a>
       </div>
@@ -173,8 +186,8 @@ function MakeItRealCard({
       : `Connect Builder to enable ${featureLabel}.`;
   const primaryLabel =
     cta.kind === "configure-project"
-      ? "Choose" /* i18n-ignore make-it-real card */
-      : "Connect"; /* i18n-ignore make-it-real card */
+      ? t("designEditor.makeItRealCard.choose")
+      : t("designEditor.makeItRealCard.connect");
 
   return (
     <div className="space-y-1">
@@ -213,10 +226,10 @@ function MakeItRealCard({
             {isPending ? (
               <>
                 <IconLoader2 className="size-2.5 animate-spin" />
-                {"Generating" /* i18n-ignore make-it-real card */}
+                {t("designEditor.makeItRealCard.generating")}
               </>
             ) : (
-              <>{"Generate" /* i18n-ignore make-it-real card */}</>
+              <>{t("designEditor.makeItRealCard.generate")}</>
             )}
           </Button>
         )}
@@ -225,7 +238,7 @@ function MakeItRealCard({
         <p className="px-2 text-[10px] text-destructive">
           {migrateError instanceof Error
             ? migrateError.message
-            : /* i18n-ignore make-it-real card */ "Migration failed. Please try again."}
+            : t("designEditor.makeItRealCard.migrationFailed")}
         </p>
       ) : null}
     </div>
@@ -260,6 +273,150 @@ interface ComponentDetailsResult {
   };
 }
 
+/** Shape returned by `go-to-main-component`. */
+interface GoToMainComponentResult {
+  isMain?: boolean;
+  ctaRequired?: boolean;
+  ctaMessage?: string;
+  note?: string;
+}
+
+/** Shape returned by `swap-component-instance`. */
+interface SwapComponentInstanceResult {
+  swapped?: boolean;
+  conflict?: boolean;
+  ctaRequired?: boolean;
+  ctaMessage?: string;
+  error?: string;
+  note?: string;
+  fromComponent?: string;
+  toComponent?: string;
+  fileId?: string;
+  content?: string;
+  updatedAt?: string;
+}
+
+/** Shape returned by `detach-component-instance`. */
+interface DetachComponentInstanceResult {
+  detached?: boolean;
+  conflict?: boolean;
+  ctaRequired?: boolean;
+  ctaMessage?: string;
+  error?: string;
+  note?: string;
+  fileId?: string;
+  content?: string;
+  updatedAt?: string;
+}
+
+/** Each editable row: name + current value + how it persists + its options. */
+export type PropRow = {
+  name: string;
+  value: string;
+  /** Variant/enum options when the prop is a known group. */
+  options?: string[];
+  /** Persist surface for this prop. */
+  surface: "alpineData" | "attribute";
+};
+
+/**
+ * Build the editable prop rows for a component instance from
+ * `get-component-details`'s response: Alpine `x-data` keys first (they drive
+ * the live variant/state), then observed `data-agent-native-prop-*`
+ * attributes not already covered by x-data, then any persisted variant group
+ * that has never been observed on this instance at all (seeded to its first
+ * option).
+ *
+ * Pure — exported for tests.
+ */
+export function buildComponentPropRows(data: {
+  instance?: { alpineData?: string | null } | null;
+  observedProps: Array<{ name: string; value: string }>;
+  persistedVariants: Record<string, string[]>;
+}): PropRow[] {
+  const { observedProps, persistedVariants, instance } = data;
+  const alpineData = parseAlpineDataObject(instance?.alpineData);
+
+  const rows: PropRow[] = [];
+  const seen = new Set<string>();
+
+  // 1) Alpine x-data keys come first — they drive the live variant/state.
+  if (alpineData) {
+    for (const [key, value] of Object.entries(alpineData)) {
+      rows.push({
+        name: key,
+        value,
+        options: persistedVariants[key],
+        surface: "alpineData",
+      });
+      seen.add(key);
+    }
+  }
+
+  // 2) data-agent-native-prop-* attributes not already covered by x-data.
+  for (const prop of observedProps) {
+    if (seen.has(prop.name)) continue;
+    rows.push({
+      name: prop.name,
+      value: prop.value,
+      options: persistedVariants[prop.name],
+      surface: "attribute",
+    });
+    seen.add(prop.name);
+  }
+
+  // 3) persistedVariant groups with no observed value yet (default to first).
+  // Surface is always "attribute" here, NOT "alpineData" even when this
+  // instance's x-data happens to be non-empty for other keys: x-data blocks
+  // for a real component instance are written with every prop the component
+  // declares initialized up front (e.g. `{ variant: 'solid', size: 'md' }`),
+  // so a group that never showed up in step 1 was never a x-data key on this
+  // instance in the first place — it is attribute-driven. Guessing
+  // "alpineData" from unrelated sibling keys used to route the very first
+  // edit of such a prop into a surgical/rebuild x-data write that either
+  // silently wrote a key nothing in the template reads, or hit the "can't
+  // safely edit this prop inline" bail-out when the sibling x-data content
+  // was too complex to rebuild — even though the plain attribute write would
+  // have worked fine.
+  for (const [group, options] of Object.entries(persistedVariants)) {
+    if (seen.has(group)) continue;
+    rows.push({
+      name: group,
+      value: options[0] ?? "",
+      options,
+      surface: "attribute",
+    });
+    seen.add(group);
+  }
+
+  return rows;
+}
+
+/**
+ * True when a "message" event's source window matches one of this document's
+ * own embedded design-preview iframes.
+ *
+ * `postMessage` has no origin/source check built in, so without this any
+ * window — including a spoofed one from a compromised/unrelated frame — could
+ * post `{ type: "element-select" }` at the parent and force this section to
+ * refetch. Mirrors the DOM-identity check DesignCanvas's
+ * `isTrustedCanvasBridgeMessage` and MultiScreenCanvas's cross-screen-drag
+ * handler use: trust comes from matching `iframe.contentWindow` against
+ * `event.source`, not from anything in the message payload.
+ *
+ * Exported for tests.
+ */
+export function isMessageFromOwnPreviewIframe(
+  source: MessageEventSource | null,
+): boolean {
+  if (typeof document === "undefined" || !source) return false;
+  return Array.from(
+    document.querySelectorAll<HTMLIFrameElement>(
+      "iframe[data-design-preview-iframe]",
+    ),
+  ).some((iframe) => iframe.contentWindow === source);
+}
+
 /**
  * Contextual COMPONENT section rendered inside the Design tab when the
  * selected element is a component instance (carries
@@ -279,6 +436,7 @@ export function ComponentSection({
   activeContent,
   activeFileUpdatedAt,
   nodeId,
+  swapPickerRequest = 0,
   onComponentPropApplied,
   sourceCapabilities = [],
 }: {
@@ -287,6 +445,8 @@ export function ComponentSection({
   activeContent?: string;
   activeFileUpdatedAt?: string | null;
   nodeId: string;
+  /** Increment to open the Swap instance picker from another UI entry point. */
+  swapPickerRequest?: number;
   onComponentPropApplied?: (
     fileId: string,
     content: string,
@@ -295,6 +455,7 @@ export function ComponentSection({
   /** Capability names advertised by the current source. */
   sourceCapabilities?: string[];
 }) {
+  const t = useT();
   const queryClient = useQueryClient();
   const detailsParams = { designId, nodeId, ...(fileId ? { fileId } : {}) };
   const detailsKey = ["action", "get-component-details", detailsParams];
@@ -322,6 +483,153 @@ export function ComponentSection({
 
   const openSourceMutation = useActionMutation("open-component-source");
   const applyPropMutation = useActionMutation("apply-component-prop-edit");
+  const goToMainMutation = useActionMutation("go-to-main-component");
+  const detachMutation = useActionMutation("detach-component-instance");
+  const swapMutation = useActionMutation("swap-component-instance");
+
+  // ── Swap instance picker (searchable popover) ─────────────────────────────
+  const [swapPickerOpen, setSwapPickerOpen] = useState(false);
+  const [swapQuery, setSwapQuery] = useState("");
+  useEffect(() => {
+    if (swapPickerRequest > 0) setSwapPickerOpen(true);
+  }, [swapPickerRequest]);
+  const componentName = data?.name;
+  const { data: swapCatalog, isLoading: swapCatalogLoading } = useActionQuery(
+    "list-design-components",
+    { designId, excludeName: componentName },
+    { enabled: swapPickerOpen && Boolean(componentName) },
+  );
+  const swapCandidates = (swapCatalog?.components ?? []).filter((c) =>
+    c.name.toLowerCase().includes(swapQuery.trim().toLowerCase()),
+  );
+
+  // Refresh the component section + design canvas after a detach/swap
+  // mutates the design file, mirroring persistPropEdit's onSettled below.
+  // Plain function (not memoized) — matches this file's existing
+  // persistPropEdit/commitProp convention of re-creating handlers per render
+  // rather than threading useCallback dependency arrays through them.
+  const refreshAfterInstanceMutation = (result: {
+    fileId?: string;
+    content?: string;
+    updatedAt?: string;
+  }) => {
+    if (
+      typeof result.fileId === "string" &&
+      typeof result.content === "string"
+    ) {
+      latestSourceRef.current = {
+        content: result.content,
+        revision: result.updatedAt ?? latestSourceRef.current.revision,
+      };
+      onComponentPropApplied?.(result.fileId, result.content, result.updatedAt);
+    }
+    void queryClient.invalidateQueries({ queryKey: ["action", "get-design"] });
+    void queryClient.invalidateQueries({ queryKey: detailsKey });
+    void refetch();
+  };
+
+  const sourceForMutation = () => {
+    const latestSource = latestSourceRef.current;
+    return latestSource.content
+      ? {
+          currentContent: latestSource.content,
+          ...(latestSource.revision ? { revision: latestSource.revision } : {}),
+        }
+      : undefined;
+  };
+
+  const handleGoToMainComponent = () => {
+    goToMainMutation.mutate(
+      { designId, nodeId, ...(fileId ? { fileId } : {}) },
+      {
+        onSuccess: (result: GoToMainComponentResult) => {
+          if (result.ctaRequired) {
+            toast.error(
+              result.ctaMessage ??
+                t("designEditor.componentInstances.goToMainUnavailable"),
+            );
+            return;
+          }
+          if (result.isMain) {
+            toast(
+              result.note ??
+                t("designEditor.componentInstances.onlyKnownInstance"),
+            );
+          }
+        },
+        onError: () =>
+          toast.error(t("designEditor.componentInstances.resolveMainFailed")),
+      },
+    );
+  };
+
+  const handleDetachInstance = () => {
+    const source = sourceForMutation();
+    detachMutation.mutate(
+      {
+        designId,
+        nodeId,
+        ...(fileId ? { fileId } : {}),
+        ...(source ? { source } : {}),
+      },
+      {
+        onSuccess: (result: DetachComponentInstanceResult) => {
+          if (result.conflict || result.ctaRequired) {
+            toast.error(
+              result.error ??
+                result.ctaMessage ??
+                t("designEditor.componentInstances.detachFailed"),
+            );
+            return;
+          }
+          if (result.detached) {
+            toast(result.note ?? t("designEditor.componentInstances.detached"));
+            refreshAfterInstanceMutation(result);
+          }
+        },
+        onError: () =>
+          toast.error(t("designEditor.componentInstances.detachFailed")),
+      },
+    );
+  };
+
+  const handleSwapInstance = (targetComponentName: string) => {
+    const source = sourceForMutation();
+    swapMutation.mutate(
+      {
+        designId,
+        nodeId,
+        ...(fileId ? { fileId } : {}),
+        targetComponentName,
+        ...(source ? { source } : {}),
+      },
+      {
+        onSuccess: (result: SwapComponentInstanceResult) => {
+          if (result.conflict || result.ctaRequired) {
+            toast.error(
+              result.error ??
+                result.ctaMessage ??
+                t("designEditor.componentInstances.swapFailed"),
+            );
+            return;
+          }
+          if (result.swapped) {
+            toast(
+              result.note ??
+                t("designEditor.componentInstances.swappedFor", {
+                  name: targetComponentName,
+                }),
+            );
+            setSwapPickerOpen(false);
+            setSwapQuery("");
+            refreshAfterInstanceMutation(result);
+          }
+        },
+        onError: () =>
+          toast.error(t("designEditor.componentInstances.swapFailed")),
+      },
+    );
+  };
 
   const postComponentPropPreview = useCallback(
     (attribute: string, value: string) => {
@@ -428,10 +736,12 @@ export function ComponentSection({
 
     const handleMessage = (event: MessageEvent) => {
       if (
-        (event.data as { type?: unknown } | null)?.type === "element-select"
+        (event.data as { type?: unknown } | null)?.type !== "element-select"
       ) {
-        void refetch();
+        return;
       }
+      if (!isMessageFromOwnPreviewIframe(event.source)) return;
+      void refetch();
     };
     window.addEventListener("message", handleMessage);
     return () => {
@@ -479,55 +789,11 @@ export function ComponentSection({
   const editingEnabled = isInline && capabilities.canEditProps; // gated; real-app stays read-only for now
   const alpineData = parseAlpineDataObject(instance?.alpineData);
 
-  // Each editable row: name + current value + how it persists + its options.
-  type PropRow = {
-    name: string;
-    value: string;
-    /** Variant/enum options when the prop is a known group. */
-    options?: string[];
-    /** Persist surface for this prop. */
-    surface: "alpineData" | "attribute";
-  };
-
-  const rows: PropRow[] = [];
-  const seen = new Set<string>();
-
-  // 1) Alpine x-data keys come first — they drive the live variant/state.
-  if (alpineData) {
-    for (const [key, value] of Object.entries(alpineData)) {
-      rows.push({
-        name: key,
-        value,
-        options: persistedVariants[key],
-        surface: "alpineData",
-      });
-      seen.add(key);
-    }
-  }
-
-  // 2) data-agent-native-prop-* attributes not already covered by x-data.
-  for (const prop of observedProps) {
-    if (seen.has(prop.name)) continue;
-    rows.push({
-      name: prop.name,
-      value: prop.value,
-      options: persistedVariants[prop.name],
-      surface: "attribute",
-    });
-    seen.add(prop.name);
-  }
-
-  // 3) persistedVariant groups with no observed value yet (default to first).
-  for (const [group, options] of Object.entries(persistedVariants)) {
-    if (seen.has(group)) continue;
-    rows.push({
-      name: group,
-      value: options[0] ?? "",
-      options,
-      surface: alpineData ? "alpineData" : "attribute",
-    });
-    seen.add(group);
-  }
+  const rows: PropRow[] = buildComponentPropRows({
+    instance,
+    observedProps,
+    persistedVariants,
+  });
 
   const hasRows = rows.length > 0;
 
@@ -559,10 +825,7 @@ export function ComponentSection({
         // can't rewrite for this key without dropping it. Fail safe: skip the
         // edit rather than persist a lossy rewrite, and tell the user why so
         // the change doesn't silently vanish.
-        toast.error(
-          // i18n-ignore
-          "Can’t safely edit this prop inline — this component’s Alpine state is too complex. Edit the source instead.",
-        );
+        toast.error(t("designEditor.componentProps.alpineTooComplexToEdit"));
         return;
       }
 
@@ -625,6 +888,125 @@ export function ComponentSection({
         <h3 className="min-w-0 flex-1 truncate !text-[11px] font-semibold text-foreground">
           {name}
         </h3>
+        {/* Instance operations: Go to main component / Swap instance /
+            Detach instance (Figma's instance-only affordances). Inline/Alpine
+            designs only — the underlying actions fail closed for real-app
+            sources, so hide them entirely there rather than show a
+            perpetually-disabled button. */}
+        {isInline && (
+          <>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon"
+                  className="size-6 rounded-md text-muted-foreground hover:text-foreground disabled:cursor-not-allowed disabled:opacity-40"
+                  disabled={goToMainMutation.isPending}
+                  aria-label={t("designEditor.componentInstances.goToMain")}
+                  onClick={handleGoToMainComponent}
+                >
+                  <IconComponents className="size-3.5" />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent>
+                {t("designEditor.componentInstances.goToMain")}
+              </TooltipContent>
+            </Tooltip>
+
+            <Popover
+              open={swapPickerOpen}
+              onOpenChange={(open) => {
+                setSwapPickerOpen(open);
+                if (!open) setSwapQuery("");
+              }}
+            >
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <PopoverTrigger asChild>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="icon"
+                      className="size-6 rounded-md text-muted-foreground hover:text-foreground disabled:cursor-not-allowed disabled:opacity-40"
+                      disabled={!editingEnabled || swapMutation.isPending}
+                      aria-label={t("designEditor.componentInstances.swap")}
+                    >
+                      <IconArrowsLeftRight className="size-3.5" />
+                    </Button>
+                  </PopoverTrigger>
+                </TooltipTrigger>
+                <TooltipContent>
+                  {t("designEditor.componentInstances.swap")}
+                </TooltipContent>
+              </Tooltip>
+              <PopoverContent
+                align="end"
+                className="w-56 rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-panel-bg)] p-1.5 text-[11px]"
+              >
+                <Input
+                  autoFocus
+                  value={swapQuery}
+                  onChange={(e) => setSwapQuery(e.target.value)}
+                  placeholder={t(
+                    "designEditor.componentInstances.searchComponents",
+                  )}
+                  className="mb-1.5 h-7 !text-[11px]"
+                />
+                <div className="max-h-52 overflow-y-auto">
+                  {swapCatalogLoading ? (
+                    <div className="px-2 py-1.5 text-muted-foreground">
+                      {t("designEditor.componentInstances.loading")}
+                    </div>
+                  ) : swapCandidates.length === 0 ? (
+                    <div className="px-2 py-1.5 text-muted-foreground">
+                      {t("designEditor.componentInstances.noOtherComponents")}
+                    </div>
+                  ) : (
+                    swapCandidates.map((candidate) => (
+                      <button
+                        key={candidate.name}
+                        type="button"
+                        disabled={swapMutation.isPending}
+                        onClick={() => handleSwapInstance(candidate.name)}
+                        className="flex w-full items-center justify-between gap-2 rounded-[4px] px-2 py-1.5 text-left hover:bg-[var(--design-editor-selection-color)] hover:text-white disabled:cursor-wait disabled:opacity-60"
+                      >
+                        <span className="min-w-0 flex-1 truncate">
+                          {candidate.name}
+                        </span>
+                        <span className="shrink-0 text-[10px] text-muted-foreground">
+                          {candidate.instanceCount}
+                        </span>
+                      </button>
+                    ))
+                  )}
+                </div>
+              </PopoverContent>
+            </Popover>
+
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon"
+                  className="size-6 rounded-md text-muted-foreground hover:text-foreground disabled:cursor-not-allowed disabled:opacity-40"
+                  disabled={!editingEnabled || detachMutation.isPending}
+                  aria-label={t("designEditor.componentInstances.detach")}
+                  onClick={handleDetachInstance}
+                >
+                  <IconUnlink className="size-3.5" />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent>
+                {t("designEditor.componentInstances.detach")}
+                <span className="ms-1.5 text-muted-foreground/70">
+                  {"⌥⌘B" /* i18n-ignore keyboard shortcut */}
+                </span>
+              </TooltipContent>
+            </Tooltip>
+          </>
+        )}
         {/* Jump-to-source action */}
         <Tooltip>
           <TooltipTrigger asChild>
@@ -634,9 +1016,7 @@ export function ComponentSection({
               size="icon"
               className="size-6 rounded-md text-muted-foreground hover:text-foreground disabled:cursor-not-allowed disabled:opacity-40"
               disabled={!canJumpToSource}
-              aria-label={
-                "Edit component source" /* i18n-ignore design inspector action */
-              }
+              aria-label={t("designEditor.componentSource.editSource")}
               onClick={() => {
                 openSourceMutation.mutate({
                   designId,
@@ -649,12 +1029,10 @@ export function ComponentSection({
             </Button>
           </TooltipTrigger>
           <TooltipContent>
-            {
-              canJumpToSource
-                ? "Edit component source" /* i18n-ignore design inspector action */
-                : (capabilities.ctaMessage ??
-                  "Source jump needs a connected app") /* i18n-ignore design inspector tooltip */
-            }
+            {canJumpToSource
+              ? t("designEditor.componentSource.editSource")
+              : (capabilities.ctaMessage ??
+                t("designEditor.componentSource.needsConnectedApp"))}
           </TooltipContent>
         </Tooltip>
       </div>
@@ -680,7 +1058,7 @@ export function ComponentSection({
         {hasRows && (
           <div className="space-y-1">
             <p className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/70">
-              {"Props" /* i18n-ignore design inspector label */}
+              {t("designEditor.componentProps.label")}
             </p>
             {rows.map((row) => {
               const hasOptions = (row.options?.length ?? 0) > 0;
diff --git a/templates/design/app/components/design/edit-panel/document-colors.ts b/templates/design/app/components/design/edit-panel/document-colors.ts
index 927605e266..2690bdcb84 100644
--- a/templates/design/app/components/design/edit-panel/document-colors.ts
+++ b/templates/design/app/components/design/edit-panel/document-colors.ts
@@ -74,10 +74,18 @@ export function selectionColorValues(
   return rawValues
     .map((color) => ({ ...color, value: color.value?.trim() }))
     .filter((color): color is SelectionColorValue => Boolean(color.value))
-    .filter(
-      (color) =>
-        color.value !== "transparent" && color.value !== "rgba(0, 0, 0, 0)",
-    )
+    .filter((color) => {
+      // Skip fully transparent colors — not a meaningful "selection color"
+      // swatch (matches extractDocumentColorPalette's same alpha check
+      // below). Parsed via parseCssColor rather than compared against the
+      // two literal spellings "transparent"/"rgba(0, 0, 0, 0)" — a border/
+      // outline color can be zero-alpha in many other forms (e.g.
+      // "rgba(255, 0, 0, 0)", "hsla(0, 0%, 0%, 0)", no-space formatting)
+      // and those previously slipped through as a bogus opaque-looking
+      // swatch instead of being hidden like every other invisible color.
+      const parsed = parseCssColor(color.value);
+      return !parsed || parsed.a > 0;
+    })
     .filter((color) => {
       const key = color.value.toLowerCase();
       if (seen.has(key)) return false;
diff --git a/templates/design/app/components/design/edit-panel/effects-properties.mixed.test.ts b/templates/design/app/components/design/edit-panel/effects-properties.mixed.test.ts
new file mode 100644
index 0000000000..9fc31a82e6
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/effects-properties.mixed.test.ts
@@ -0,0 +1,143 @@
+/**
+ * Effects-section bug-hunt fixes (Figma-parity pass).
+ *
+ * 1. `effectsSelectionIsMixed` — Effects had no multi-select "Mixed" handling
+ *    at all, unlike Fill/Stroke. `parseShadowLayers("Mixed")` would parse the
+ *    literal sentinel string as a bogus single shadow layer (color: "Mixed"),
+ *    and editing any of its fields would commit an invalid
+ *    `box-shadow: ... Mixed` to every selected element. The section now gates
+ *    on this predicate and shows a "Click + to replace" hint instead, same as
+ *    Fill/Stroke.
+ * 2. The hidden-effect stash (used by the eye-toggle on shadows/layer-blur/
+ *    backdrop-blur) was keyed by `elementIdentityKey`, which folds in the
+ *    element's bounding rect and therefore changes on every resize/move.
+ *    Hiding an effect, then resizing/moving the element, then showing it
+ *    again silently lost the stashed original value and fell back to a
+ *    generic default instead. Fixed by keying the stash with
+ *    `elementStableKey` (element-identity.ts) instead — the same helper
+ *    `useAspectRatioLock` uses for the identical reason. This file
+ *    previously carried its own local copy of that helper
+ *    (`stableEffectElementKey`) with a `??`-vs-`||` bug matching the one
+ *    fixed in element-identity.ts (an empty-string `sourceId` — the bridge's
+ *    reported value for non-source-backed elements — short-circuited past
+ *    `id`/`selector` under `??`, collapsing every such element to the same
+ *    key); it now imports the shared, already-fixed helper instead of
+ *    duplicating it.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { ElementInfo } from "../types";
+import { effectsSelectionIsMixed } from "./effects-properties";
+import { elementStableKey } from "./element-identity";
+
+function elementWithRect(
+  overrides: Partial<ElementInfo> & {
+    boundingRect: ElementInfo["boundingRect"];
+  },
+): ElementInfo {
+  return {
+    tagName: "div",
+    selector: "div.card",
+    computedStyles: {},
+    inlineStyles: {},
+    classes: [],
+    ...overrides,
+  } as ElementInfo;
+}
+
+describe("effectsSelectionIsMixed", () => {
+  it("is false when every effects-relevant style agrees across the selection", () => {
+    expect(
+      effectsSelectionIsMixed({
+        boxShadow: "0px 4px 12px 0px rgba(0,0,0,0.25)",
+        filter: "none",
+        backdropFilter: "none",
+      }),
+    ).toBe(false);
+  });
+
+  it("is true when box-shadow differs across a multi-selection (Mixed sentinel)", () => {
+    expect(
+      effectsSelectionIsMixed({
+        boxShadow: "Mixed",
+        filter: "none",
+      }),
+    ).toBe(true);
+  });
+
+  it("is true when filter (layer blur) differs across a multi-selection", () => {
+    expect(effectsSelectionIsMixed({ filter: "Mixed" })).toBe(true);
+  });
+
+  it("is true when either backdrop-filter alias differs across a multi-selection", () => {
+    expect(effectsSelectionIsMixed({ backdropFilter: "Mixed" })).toBe(true);
+    expect(effectsSelectionIsMixed({ webkitBackdropFilter: "Mixed" })).toBe(
+      true,
+    );
+  });
+
+  it('does not false-positive on a real value that merely contains the word "mixed"', () => {
+    // isMixedValue only matches the exact sentinel string "Mixed", not any
+    // value that happens to contain it as a substring.
+    expect(
+      effectsSelectionIsMixed({ boxShadow: "0px 0px 0px 0px Mixed City" }),
+    ).toBe(false);
+  });
+});
+
+describe("elementStableKey (used by the effects hidden-effect stash)", () => {
+  it("stays identical across a resize/move of the same element", () => {
+    const before = elementWithRect({
+      sourceId: "node-42",
+      boundingRect: { x: 0, y: 0, width: 100, height: 40 },
+    });
+    const afterResize = elementWithRect({
+      sourceId: "node-42",
+      boundingRect: { x: 250, y: 80, width: 340, height: 96 },
+    });
+    expect(elementStableKey(before)).toBe(elementStableKey(afterResize));
+  });
+
+  it("falls back through sourceId -> id -> selector -> tagName", () => {
+    const bySourceId = elementWithRect({
+      sourceId: "src-1",
+      id: "dom-1",
+      selector: "#dom-1",
+      boundingRect: { x: 0, y: 0, width: 1, height: 1 },
+    });
+    expect(elementStableKey(bySourceId)).toBe("src-1");
+
+    const byId = elementWithRect({
+      id: "dom-1",
+      selector: "#dom-1",
+      boundingRect: { x: 0, y: 0, width: 1, height: 1 },
+    });
+    expect(elementStableKey(byId)).toBe("dom-1");
+
+    const bySelector = elementWithRect({
+      selector: "#dom-1",
+      boundingRect: { x: 0, y: 0, width: 1, height: 1 },
+    });
+    expect(elementStableKey(bySelector)).toBe("#dom-1");
+
+    const byTagName = elementWithRect({
+      tagName: "section",
+      selector: undefined,
+      boundingRect: { x: 0, y: 0, width: 1, height: 1 },
+    });
+    expect(elementStableKey(byTagName)).toBe("section");
+  });
+
+  it("differs between two genuinely different elements at the same position", () => {
+    const a = elementWithRect({
+      sourceId: "node-a",
+      boundingRect: { x: 0, y: 0, width: 50, height: 50 },
+    });
+    const b = elementWithRect({
+      sourceId: "node-b",
+      boundingRect: { x: 0, y: 0, width: 50, height: 50 },
+    });
+    expect(elementStableKey(a)).not.toBe(elementStableKey(b));
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/effects-properties.persistence.test.ts b/templates/design/app/components/design/edit-panel/effects-properties.persistence.test.ts
new file mode 100644
index 0000000000..ed8ea3aa8d
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/effects-properties.persistence.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  parseShadowLayers,
+  readBlurFilter,
+  remapIndexedShadowStash,
+  removeBlurFilterValue,
+  serializeShadowLayers,
+  setBlurFilterValue,
+} from "./effects-properties";
+
+describe("effect CSS persistence", () => {
+  it("adds layer blur without deleting sibling filter effects", () => {
+    expect(setBlurFilterValue("brightness(1.2) contrast(90%)", 4)).toBe(
+      "brightness(1.2) contrast(90%) blur(4px)",
+    );
+  });
+
+  it("updates an existing blur in place without disturbing filter order", () => {
+    expect(
+      setBlurFilterValue("brightness(1.2) blur(4px) saturate(80%)", 6.5),
+    ).toBe("brightness(1.2) blur(6.5px) saturate(80%)");
+  });
+
+  it("removes only blur and preserves sibling filters", () => {
+    expect(
+      removeBlurFilterValue(
+        "brightness(1.2) blur(6.5px) drop-shadow(0 2px 4px #0008)",
+      ),
+    ).toBe("brightness(1.2) drop-shadow(0 2px 4px #0008)");
+    expect(removeBlurFilterValue("blur(4px)")).toBe("none");
+  });
+
+  it("keeps one-decimal blur precision and clamps negative blur", () => {
+    expect(readBlurFilter("blur(.5px)")).toBe(0.5);
+    expect(setBlurFilterValue("blur(4px)", 2.56)).toBe("blur(2.6px)");
+    expect(setBlurFilterValue("blur(4px)", -2)).toBe("blur(0px)");
+  });
+
+  it("round-trips fractional and negative shadow geometry", () => {
+    const serialized = serializeShadowLayers([
+      {
+        id: "shadow-0",
+        x: -1.25,
+        y: 2.55,
+        blur: 3.45,
+        spread: -4.25,
+        color: "rgba(0, 0, 0, 0.25)",
+        inset: false,
+      },
+    ]);
+
+    expect(serialized).toBe("-1.2px 2.6px 3.5px -4.2px rgba(0, 0, 0, 0.25)");
+    expect(parseShadowLayers(serialized)[0]).toMatchObject({
+      x: -1.2,
+      y: 2.6,
+      blur: 3.5,
+      spread: -4.2,
+      color: "rgba(0, 0, 0, 0.25)",
+    });
+  });
+
+  it("clamps only shadow blur while keeping negative spread valid", () => {
+    expect(
+      serializeShadowLayers([
+        {
+          id: "shadow-0",
+          x: 0,
+          y: 0,
+          blur: -3,
+          spread: -7.5,
+          color: "#000000",
+          inset: true,
+        },
+      ]),
+    ).toBe("inset 0px 0px 0px -7.5px #000000");
+  });
+
+  it("keeps a hidden shadow's original alpha attached through reorder", () => {
+    const stash = {
+      "node-1:shadow:shadow-1": "rgba(0, 0, 0, 0.6)",
+      "node-1:filter:blur": "8",
+    };
+    const reordered = remapIndexedShadowStash(stash, "node-1", [
+      { id: "shadow-1" },
+      { id: "shadow-0" },
+    ]);
+
+    expect(reordered).toEqual({
+      "node-1:shadow:shadow-0": "rgba(0, 0, 0, 0.6)",
+      "node-1:filter:blur": "8",
+    });
+  });
+
+  it("shifts a hidden shadow's stash when an earlier layer is removed", () => {
+    expect(
+      remapIndexedShadowStash(
+        { "node-1:shadow:shadow-1": "rgba(1, 2, 3, 0.7)" },
+        "node-1",
+        [{ id: "shadow-1" }],
+      ),
+    ).toEqual({ "node-1:shadow:shadow-0": "rgba(1, 2, 3, 0.7)" });
+  });
+
+  it("drops a removed hidden layer's stale stash", () => {
+    expect(
+      remapIndexedShadowStash(
+        {
+          "node-1:shadow:shadow-0": "rgba(1, 2, 3, 0.7)",
+          "node-1:filter:blur": "4",
+        },
+        "node-1",
+        [],
+      ),
+    ).toEqual({ "node-1:filter:blur": "4" });
+  });
+
+  it("preserves state identity when indexed stashes already match", () => {
+    const stash = { "node-1:shadow:shadow-0": "rgba(1, 2, 3, 0.7)" };
+    expect(remapIndexedShadowStash(stash, "node-1", [{ id: "shadow-0" }])).toBe(
+      stash,
+    );
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/effects-properties.tsx b/templates/design/app/components/design/edit-panel/effects-properties.tsx
index 8b45d55e6b..820e424361 100644
--- a/templates/design/app/components/design/edit-panel/effects-properties.tsx
+++ b/templates/design/app/components/design/edit-panel/effects-properties.tsx
@@ -37,7 +37,7 @@ import {
   type GlslShaderPanelContext,
 } from "../inspector/GlslShaderPanel";
 import type { ElementInfo } from "../types";
-import { elementIdentityKey } from "./element-identity";
+import { elementStableKey } from "./element-identity";
 import { FieldTrailer } from "./field-primitives";
 import { splitCssLayers } from "./fill-gradient-helpers";
 import {
@@ -50,8 +50,10 @@ import {
   colorHasVisibleAlpha,
   compactCssValue,
   cssColorOrFallback,
+  roundToOneDecimal,
   swatchStyle,
 } from "./position-helpers";
+import { isMixedValue } from "./selection-helpers";
 import type {
   MotionKeyframeFieldContext,
   StyleChangeHandler,
@@ -59,7 +61,7 @@ import type {
   StylesChangeHandler,
 } from "./style-change-types";
 
-interface ShadowLayer {
+export interface ShadowLayer {
   id: string;
   x: number;
   y: number;
@@ -81,7 +83,7 @@ function defaultDropShadowLayer(index: number): ShadowLayer {
   };
 }
 
-function parseShadowLayers(value: string | undefined): ShadowLayer[] {
+export function parseShadowLayers(value: string | undefined): ShadowLayer[] {
   return splitCssLayers(value || "")
     .filter((layer) => layer && layer !== "none")
     .map((layer, index) => parseShadowLayer(layer, index));
@@ -133,18 +135,18 @@ function splitCssTokens(value: string): string[] {
   return tokens;
 }
 
-function serializeShadowLayers(layers: ShadowLayer[]) {
+export function serializeShadowLayers(layers: ShadowLayer[]) {
   if (!layers.length) return "none";
   return layers
     .map((layer) =>
       [
         layer.inset ? "inset" : "",
-        `${Math.round(layer.x)}px`,
-        `${Math.round(layer.y)}px`,
-        `${Math.max(0, Math.round(layer.blur))}px`,
+        `${roundToOneDecimal(layer.x)}px`,
+        `${roundToOneDecimal(layer.y)}px`,
+        `${Math.max(0, roundToOneDecimal(layer.blur))}px`,
         // Spread radius may legitimately be negative for either inset or
         // drop shadows — only blur-radius is clamped to >= 0 in CSS.
-        `${Math.round(layer.spread)}px`,
+        `${roundToOneDecimal(layer.spread)}px`,
         layer.color,
       ]
         .filter(Boolean)
@@ -153,8 +155,8 @@ function serializeShadowLayers(layers: ShadowLayer[]) {
     .join(", ");
 }
 
-function readBlurFilter(value: string | undefined): number {
-  const match = value?.match(/blur\((-?\d+(?:\.\d+)?)px\)/);
+export function readBlurFilter(value: string | undefined): number {
+  const match = value?.match(/blur\((-?(?:\d+(?:\.\d+)?|\.\d+))px\)/);
   return match ? Math.max(0, Number(match[1])) : 0;
 }
 
@@ -162,12 +164,62 @@ function hasBlurFilter(value: string | undefined): boolean {
   return /blur\(/.test(value || "");
 }
 
-function setBlurFilterValue(value: string | undefined, blur: number): string {
-  const blurFn = `blur(${Math.max(0, Math.round(blur))}px)`;
+export function setBlurFilterValue(
+  value: string | undefined,
+  blur: number,
+): string {
+  const blurFn = `blur(${Math.max(0, roundToOneDecimal(blur))}px)`;
   const existing = compactCssValue(value, "");
   return existing.includes("blur(")
     ? existing.replace(/blur\([^)]*\)/, blurFn)
-    : blurFn;
+    : existing && existing !== "none"
+      ? `${existing} ${blurFn}`
+      : blurFn;
+}
+
+/** Remove only the layer/background blur function, preserving every sibling
+ * CSS filter (brightness, contrast, drop-shadow, etc.). Figma models layer
+ * blur as one effect row; deleting that row must not delete the other effects
+ * that happen to share CSS's `filter`/`backdrop-filter` declaration. */
+export function removeBlurFilterValue(value: string | undefined): string {
+  const existing = compactCssValue(value, "");
+  if (!existing || existing === "none") return "none";
+  const remaining = existing
+    .replace(/blur\([^)]*\)/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return remaining || "none";
+}
+
+/** Keep the transient original-opacity stash attached to the same shadow when
+ * positional CSS layers are reordered or removed. Parsed shadow ids are
+ * necessarily index-based (`shadow-0`, `shadow-1`, …); after a reorder the
+ * next computed-style read regenerates those ids in the new order. Without
+ * remapping, a hidden shadow's saved alpha stays at its old index and the eye
+ * button restores the wrong layer (or falls back to 25%). */
+export function remapIndexedShadowStash(
+  stash: Record<string, string>,
+  elementKey: string,
+  nextLayers: readonly Pick<ShadowLayer, "id">[],
+): Record<string, string> {
+  const prefix = `${elementKey}:shadow:`;
+  const moved = nextLayers.flatMap((layer, index) => {
+    const value = stash[`${prefix}${layer.id}`];
+    return value === undefined ? [] : [[`${prefix}shadow-${index}`, value]];
+  });
+  if (!Object.keys(stash).some((key) => key.startsWith(prefix))) return stash;
+  const next = Object.fromEntries(
+    Object.entries(stash).filter(([key]) => !key.startsWith(prefix)),
+  );
+  for (const [key, value] of moved) next[key] = value;
+  const stashEntries = Object.entries(stash);
+  if (
+    stashEntries.length === Object.keys(next).length &&
+    stashEntries.every(([key, value]) => next[key] === value)
+  ) {
+    return stash;
+  }
+  return next;
 }
 
 function shadowColorWithOpacity(color: string, opacity: number): string {
@@ -179,6 +231,33 @@ function shadowColorWithOpacity(color: string, opacity: number): string {
       : color;
 }
 
+/**
+ * True when the current multi-selection has differing box-shadow, filter,
+ * or backdrop-filter values (the synthetic mixed-selection ElementInfo
+ * reports the `MIXED_VALUE`/"Mixed" sentinel for any style property that
+ * disagrees across the selection — see selection-helpers.ts). Effects had no
+ * mixed-selection handling at all: `parseShadowLayers("Mixed")` would parse
+ * the literal sentinel string as a bogus single shadow layer (color:
+ * "Mixed", the rest defaulted), and editing any of its fields would commit
+ * an invalid `box-shadow: ... Mixed` to every selected element. Fill and
+ * Stroke both already gate their sections on an equivalent mixed check and
+ * show a "Click + to replace" hint instead of rendering broken per-field
+ * controls; Effects needs the same gate.
+ */
+export function effectsSelectionIsMixed(styles: {
+  boxShadow?: string;
+  filter?: string;
+  backdropFilter?: string;
+  webkitBackdropFilter?: string;
+}): boolean {
+  return [
+    styles.boxShadow,
+    styles.filter,
+    styles.backdropFilter,
+    styles.webkitBackdropFilter,
+  ].some(isMixedValue);
+}
+
 function ShadowEffectRow({
   layer,
   index,
@@ -376,22 +455,37 @@ export function EffectsProperties({
   const t = useT();
   const [shaderPickerOpen, setShaderPickerOpen] = useState(false);
   const styles = element.computedStyles;
-  const blurValue = readBlurFilter(styles.filter);
-  const filterHasBlur = hasBlurFilter(styles.filter);
   // M5 · Background (backdrop) blur is a distinct design effect type, backed by
   // CSS `backdrop-filter: blur()` (vs layer blur's `filter: blur()`).
   const backdropFilterValue =
     styles.backdropFilter || styles.webkitBackdropFilter;
-  const backdropFilterHasBlur = hasBlurFilter(backdropFilterValue);
+  // Differing box-shadow/filter/backdrop-filter across a multi-selection —
+  // gates the whole section to a "Click + to replace" hint below, same as
+  // Fill/Stroke, instead of parsing the "Mixed" sentinel as real CSS.
+  const effectsAreMixed = effectsSelectionIsMixed({
+    boxShadow: styles.boxShadow,
+    filter: styles.filter,
+    backdropFilter: styles.backdropFilter,
+    webkitBackdropFilter: styles.webkitBackdropFilter,
+  });
+  const blurValue = readBlurFilter(styles.filter);
+  const filterHasBlur = !effectsAreMixed && hasBlurFilter(styles.filter);
+  const backdropFilterHasBlur =
+    !effectsAreMixed && hasBlurFilter(backdropFilterValue);
   const backdropBlurValue = readBlurFilter(backdropFilterValue);
   const [hiddenEffectStash, setHiddenEffectStash] = useState<
     Record<string, string>
   >({});
-  const effectStashKey = elementIdentityKey(element);
+  const effectStashKey = elementStableKey(element);
   const layerBlurStashKey = `${effectStashKey}:filter:blur`;
   const backdropBlurStashKey = `${effectStashKey}:backdrop-filter:blur`;
-  const shadowLayers = parseShadowLayers(styles.boxShadow);
+  const shadowLayers = effectsAreMixed
+    ? []
+    : parseShadowLayers(styles.boxShadow);
   const setShadowLayers = (layers: ShadowLayer[], meta?: StyleChangeMeta) => {
+    setHiddenEffectStash((stash) =>
+      remapIndexedShadowStash(stash, effectStashKey, layers),
+    );
     const boxShadow = serializeShadowLayers(layers);
     if (onStylesChange) onStylesChange({ boxShadow }, meta);
     else onStyleChange("boxShadow", boxShadow, meta);
@@ -401,8 +495,10 @@ export function EffectsProperties({
       ...shadowLayers,
       defaultDropShadowLayer(shadowLayers.length),
     ]);
-  const addLayerBlur = () => onStyleChange("filter", "blur(4px)");
-  const addBackgroundBlur = () => onStyleChange("backdropFilter", "blur(8px)");
+  const addLayerBlur = () =>
+    onStyleChange("filter", setBlurFilterValue(styles.filter, 4));
+  const addBackgroundBlur = () =>
+    onStyleChange("backdropFilter", setBlurFilterValue(backdropFilterValue, 8));
   const reorderShadowLayers = (from: number, to: number) => {
     const next = [...shadowLayers];
     const [moved] = next.splice(from, 1);
@@ -443,6 +539,7 @@ export function EffectsProperties({
   // `!effectMount && !pickerOpen` early-return so opening the picker doesn't
   // get swallowed by this outer gate before it can render itself.
   const hasEffectsContent =
+    effectsAreMixed ||
     shadowLayers.length > 0 ||
     filterHasBlur ||
     backdropFilterHasBlur ||
@@ -506,262 +603,291 @@ export function EffectsProperties({
     >
       {hasEffectsContent ? (
         <>
-          {shadowLayers.length ? (
-            <div className="space-y-1.5">
-              {shadowLayers.map((layer, index) => (
-                <ShadowEffectRow
-                  key={layer.id}
-                  layer={layer}
-                  index={index}
-                  dragHandleLabel={t("editPanel.labels.reorderLayer")}
-                  dropIndicator={
-                    shadowDrag.dragIndex != null &&
-                    shadowDrag.overIndex === index
-                      ? shadowDrag.overIndex > shadowDrag.dragIndex
-                        ? "after"
-                        : "before"
-                      : null
-                  }
-                  rowProps={shadowDrag.getRowProps(index)}
-                  handleProps={shadowDrag.getHandleProps(index)}
-                  onChange={(patch, meta) => {
-                    const next = shadowLayers.map((candidate) =>
-                      candidate.id === layer.id
-                        ? { ...candidate, ...patch }
-                        : candidate,
-                    );
-                    setShadowLayers(next, meta);
-                  }}
-                  onToggleVisibility={() => {
-                    const visible = colorHasVisibleAlpha(layer.color);
-                    const shadowStashKey = `${effectStashKey}:shadow:${layer.id}`;
-                    if (visible) {
-                      setHiddenEffectStash((prev) => ({
-                        ...prev,
-                        [shadowStashKey]: layer.color,
-                      }));
-                      const next = shadowLayers.map((candidate) =>
-                        candidate.id === layer.id
-                          ? {
-                              ...candidate,
-                              color: shadowColorWithOpacity(candidate.color, 0),
-                            }
-                          : candidate,
-                      );
-                      setShadowLayers(next);
-                      return;
-                    }
+          {effectsAreMixed ? (
+            <p className="px-1.5 py-2 !text-[11px] text-muted-foreground">
+              {
+                "Click + to replace mixed content" /* i18n-ignore figma mixed effects hint */
+              }
+            </p>
+          ) : (
+            <>
+              {shadowLayers.length ? (
+                <div className="space-y-1.5">
+                  {shadowLayers.map((layer, index) => (
+                    <ShadowEffectRow
+                      key={layer.id}
+                      layer={layer}
+                      index={index}
+                      dragHandleLabel={t("editPanel.labels.reorderLayer")}
+                      dropIndicator={
+                        shadowDrag.dragIndex != null &&
+                        shadowDrag.overIndex === index
+                          ? shadowDrag.overIndex > shadowDrag.dragIndex
+                            ? "after"
+                            : "before"
+                          : null
+                      }
+                      rowProps={shadowDrag.getRowProps(index)}
+                      handleProps={shadowDrag.getHandleProps(index)}
+                      onChange={(patch, meta) => {
+                        const next = shadowLayers.map((candidate) =>
+                          candidate.id === layer.id
+                            ? { ...candidate, ...patch }
+                            : candidate,
+                        );
+                        setShadowLayers(next, meta);
+                      }}
+                      onToggleVisibility={() => {
+                        const visible = colorHasVisibleAlpha(layer.color);
+                        const shadowStashKey = `${effectStashKey}:shadow:${layer.id}`;
+                        if (visible) {
+                          setHiddenEffectStash((prev) => ({
+                            ...prev,
+                            [shadowStashKey]: layer.color,
+                          }));
+                          const next = shadowLayers.map((candidate) =>
+                            candidate.id === layer.id
+                              ? {
+                                  ...candidate,
+                                  color: shadowColorWithOpacity(
+                                    candidate.color,
+                                    0,
+                                  ),
+                                }
+                              : candidate,
+                          );
+                          setShadowLayers(next);
+                          return;
+                        }
 
-                    const restored =
-                      hiddenEffectStash[shadowStashKey] ??
-                      shadowColorWithOpacity(layer.color, 25);
-                    setHiddenEffectStash((prev) => {
-                      const next = { ...prev };
-                      delete next[shadowStashKey];
-                      return next;
-                    });
-                    const next = shadowLayers.map((candidate) =>
-                      candidate.id === layer.id
-                        ? { ...candidate, color: restored }
-                        : candidate,
-                    );
-                    setShadowLayers(next);
-                  }}
-                  onRemove={() =>
-                    setShadowLayers(
-                      shadowLayers.filter(
-                        (candidate) => candidate.id !== layer.id,
-                      ),
-                    )
-                  }
-                  element={element}
-                  motionKeyframeContext={motionKeyframeContext}
-                />
-              ))}
-            </div>
-          ) : null}
-          {filterHasBlur ? (
-            /* design effect row for layer blur: flat row matching shadow rows */
-            <Popover>
-              <div className="group flex items-center gap-1.5">
-                <PopoverTrigger asChild>
-                  <button
-                    type="button"
-                    className="flex h-6 min-w-0 flex-1 items-center gap-1.5 rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-left !text-[11px] hover:bg-[var(--design-editor-panel-raised-bg)]"
-                  >
-                    <span className="min-w-0 flex-1 truncate font-medium text-foreground">
-                      {t("editPanel.labels.layerBlur")}
-                    </span>
-                    <span className="shrink-0 tabular-nums text-muted-foreground">
-                      {Math.round(blurValue)}px
-                    </span>
-                  </button>
-                </PopoverTrigger>
-                <SectionIconButton
-                  label={
-                    blurValue > 0
-                      ? t("editPanel.labels.hideLayer")
-                      : t("editPanel.labels.showLayer")
-                  }
-                  onClick={() => {
-                    if (blurValue > 0) {
-                      setHiddenEffectStash((prev) => ({
-                        ...prev,
-                        [layerBlurStashKey]: String(blurValue),
-                      }));
-                      onStyleChange(
-                        "filter",
-                        setBlurFilterValue(styles.filter, 0),
-                      );
-                      return;
-                    }
+                        const restored =
+                          hiddenEffectStash[shadowStashKey] ??
+                          shadowColorWithOpacity(layer.color, 25);
+                        setHiddenEffectStash((prev) => {
+                          const next = { ...prev };
+                          delete next[shadowStashKey];
+                          return next;
+                        });
+                        const next = shadowLayers.map((candidate) =>
+                          candidate.id === layer.id
+                            ? { ...candidate, color: restored }
+                            : candidate,
+                        );
+                        setShadowLayers(next);
+                      }}
+                      onRemove={() =>
+                        setShadowLayers(
+                          shadowLayers.filter(
+                            (candidate) => candidate.id !== layer.id,
+                          ),
+                        )
+                      }
+                      element={element}
+                      motionKeyframeContext={motionKeyframeContext}
+                    />
+                  ))}
+                </div>
+              ) : null}
+              {filterHasBlur ? (
+                /* design effect row for layer blur: flat row matching shadow rows */
+                <Popover>
+                  <div className="group flex items-center gap-1.5">
+                    <PopoverTrigger asChild>
+                      <button
+                        type="button"
+                        className="flex h-6 min-w-0 flex-1 items-center gap-1.5 rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-left !text-[11px] hover:bg-[var(--design-editor-panel-raised-bg)]"
+                      >
+                        <span className="min-w-0 flex-1 truncate font-medium text-foreground">
+                          {t("editPanel.labels.layerBlur")}
+                        </span>
+                        <span className="shrink-0 tabular-nums text-muted-foreground">
+                          {roundToOneDecimal(blurValue)}px
+                        </span>
+                      </button>
+                    </PopoverTrigger>
+                    <SectionIconButton
+                      label={
+                        blurValue > 0
+                          ? t("editPanel.labels.hideLayer")
+                          : t("editPanel.labels.showLayer")
+                      }
+                      onClick={() => {
+                        if (blurValue > 0) {
+                          setHiddenEffectStash((prev) => ({
+                            ...prev,
+                            [layerBlurStashKey]: String(blurValue),
+                          }));
+                          onStyleChange(
+                            "filter",
+                            setBlurFilterValue(styles.filter, 0),
+                          );
+                          return;
+                        }
 
-                    const restored = Number(
-                      hiddenEffectStash[layerBlurStashKey],
-                    );
-                    const nextBlur =
-                      Number.isFinite(restored) && restored > 0 ? restored : 4;
-                    setHiddenEffectStash((prev) => {
-                      const next = { ...prev };
-                      delete next[layerBlurStashKey];
-                      return next;
-                    });
-                    onStyleChange(
-                      "filter",
-                      setBlurFilterValue(styles.filter, nextBlur),
-                    );
-                  }}
-                >
-                  {blurValue > 0 ? (
-                    <IconEye className="size-3.5" />
-                  ) : (
-                    <IconEyeOff className="size-3.5" />
-                  )}
-                </SectionIconButton>
-                <SectionIconButton
-                  label={t("editPanel.labels.removeLayer")}
-                  onClick={() => onStyleChange("filter", "none")}
-                  disabled={!filterHasBlur}
-                >
-                  <IconMinus className="size-3.5" />
-                </SectionIconButton>
-              </div>
-              <PopoverContent
-                side="left"
-                align="start"
-                sideOffset={8}
-                className="w-56 p-3"
-              >
-                <ScrubInput
-                  label={t("editPanel.labels.blur")}
-                  value={blurValue}
-                  onChange={(value, meta) =>
-                    onStyleChange(
-                      "filter",
-                      setBlurFilterValue(styles.filter, value),
-                      meta,
-                    )
-                  }
-                  unit="px"
-                  min={0}
-                  precision={1}
-                  labelClassName="w-16"
-                  inputClassName="h-6"
-                />
-              </PopoverContent>
-            </Popover>
-          ) : null}
-          {backdropFilterHasBlur ? (
-            /* M5 · Background (backdrop) blur effect row — mirrors the layer-blur row */
-            <Popover>
-              <div className="group flex items-center gap-1.5">
-                <PopoverTrigger asChild>
-                  <button
-                    type="button"
-                    className="flex h-6 min-w-0 flex-1 items-center gap-1.5 rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-left !text-[11px] hover:bg-[var(--design-editor-panel-raised-bg)]"
+                        const restored = Number(
+                          hiddenEffectStash[layerBlurStashKey],
+                        );
+                        const nextBlur =
+                          Number.isFinite(restored) && restored > 0
+                            ? restored
+                            : 4;
+                        setHiddenEffectStash((prev) => {
+                          const next = { ...prev };
+                          delete next[layerBlurStashKey];
+                          return next;
+                        });
+                        onStyleChange(
+                          "filter",
+                          setBlurFilterValue(styles.filter, nextBlur),
+                        );
+                      }}
+                    >
+                      {blurValue > 0 ? (
+                        <IconEye className="size-3.5" />
+                      ) : (
+                        <IconEyeOff className="size-3.5" />
+                      )}
+                    </SectionIconButton>
+                    <SectionIconButton
+                      label={t("editPanel.labels.removeLayer")}
+                      onClick={() =>
+                        onStyleChange(
+                          "filter",
+                          removeBlurFilterValue(styles.filter),
+                        )
+                      }
+                      disabled={!filterHasBlur}
+                    >
+                      <IconMinus className="size-3.5" />
+                    </SectionIconButton>
+                  </div>
+                  <PopoverContent
+                    side="left"
+                    align="start"
+                    sideOffset={8}
+                    className="w-56 p-3"
                   >
-                    <span className="min-w-0 flex-1 truncate font-medium text-foreground">
-                      {"Background blur" /* i18n-ignore design effect type */}
-                    </span>
-                    <span className="shrink-0 tabular-nums text-muted-foreground">
-                      {Math.round(backdropBlurValue)}px
-                    </span>
-                  </button>
-                </PopoverTrigger>
-                <SectionIconButton
-                  label={
-                    backdropBlurValue > 0
-                      ? t("editPanel.labels.hideLayer")
-                      : t("editPanel.labels.showLayer")
-                  }
-                  onClick={() => {
-                    if (backdropBlurValue > 0) {
-                      setHiddenEffectStash((prev) => ({
-                        ...prev,
-                        [backdropBlurStashKey]: String(backdropBlurValue),
-                      }));
-                      onStyleChange(
-                        "backdropFilter",
-                        setBlurFilterValue(backdropFilterValue, 0),
-                      );
-                      return;
-                    }
+                    <ScrubInput
+                      label={t("editPanel.labels.blur")}
+                      value={blurValue}
+                      onChange={(value, meta) =>
+                        onStyleChange(
+                          "filter",
+                          setBlurFilterValue(styles.filter, value),
+                          meta,
+                        )
+                      }
+                      unit="px"
+                      min={0}
+                      precision={1}
+                      labelClassName="w-16"
+                      inputClassName="h-6"
+                    />
+                  </PopoverContent>
+                </Popover>
+              ) : null}
+              {backdropFilterHasBlur ? (
+                /* M5 · Background (backdrop) blur effect row — mirrors the layer-blur row */
+                <Popover>
+                  <div className="group flex items-center gap-1.5">
+                    <PopoverTrigger asChild>
+                      <button
+                        type="button"
+                        className="flex h-6 min-w-0 flex-1 items-center gap-1.5 rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 text-left !text-[11px] hover:bg-[var(--design-editor-panel-raised-bg)]"
+                      >
+                        <span className="min-w-0 flex-1 truncate font-medium text-foreground">
+                          {
+                            "Background blur" /* i18n-ignore design effect type */
+                          }
+                        </span>
+                        <span className="shrink-0 tabular-nums text-muted-foreground">
+                          {roundToOneDecimal(backdropBlurValue)}px
+                        </span>
+                      </button>
+                    </PopoverTrigger>
+                    <SectionIconButton
+                      label={
+                        backdropBlurValue > 0
+                          ? t("editPanel.labels.hideLayer")
+                          : t("editPanel.labels.showLayer")
+                      }
+                      onClick={() => {
+                        if (backdropBlurValue > 0) {
+                          setHiddenEffectStash((prev) => ({
+                            ...prev,
+                            [backdropBlurStashKey]: String(backdropBlurValue),
+                          }));
+                          onStyleChange(
+                            "backdropFilter",
+                            setBlurFilterValue(backdropFilterValue, 0),
+                          );
+                          return;
+                        }
 
-                    const restored = Number(
-                      hiddenEffectStash[backdropBlurStashKey],
-                    );
-                    const nextBlur =
-                      Number.isFinite(restored) && restored > 0 ? restored : 8;
-                    setHiddenEffectStash((prev) => {
-                      const next = { ...prev };
-                      delete next[backdropBlurStashKey];
-                      return next;
-                    });
-                    onStyleChange(
-                      "backdropFilter",
-                      setBlurFilterValue(backdropFilterValue, nextBlur),
-                    );
-                  }}
-                >
-                  {backdropBlurValue > 0 ? (
-                    <IconEye className="size-3.5" />
-                  ) : (
-                    <IconEyeOff className="size-3.5" />
-                  )}
-                </SectionIconButton>
-                <SectionIconButton
-                  label={t("editPanel.labels.removeLayer")}
-                  onClick={() => onStyleChange("backdropFilter", "none")}
-                  disabled={!backdropFilterHasBlur}
-                >
-                  <IconMinus className="size-3.5" />
-                </SectionIconButton>
-              </div>
-              <PopoverContent
-                side="left"
-                align="start"
-                sideOffset={8}
-                className="w-56 p-3"
-              >
-                <ScrubInput
-                  label={t("editPanel.labels.blur")}
-                  value={backdropBlurValue}
-                  onChange={(value, meta) =>
-                    onStyleChange(
-                      "backdropFilter",
-                      setBlurFilterValue(backdropFilterValue, value),
-                      meta,
-                    )
-                  }
-                  unit="px"
-                  min={0}
-                  precision={1}
-                  labelClassName="w-16"
-                  inputClassName="h-6"
-                />
-              </PopoverContent>
-            </Popover>
-          ) : null}
+                        const restored = Number(
+                          hiddenEffectStash[backdropBlurStashKey],
+                        );
+                        const nextBlur =
+                          Number.isFinite(restored) && restored > 0
+                            ? restored
+                            : 8;
+                        setHiddenEffectStash((prev) => {
+                          const next = { ...prev };
+                          delete next[backdropBlurStashKey];
+                          return next;
+                        });
+                        onStyleChange(
+                          "backdropFilter",
+                          setBlurFilterValue(backdropFilterValue, nextBlur),
+                        );
+                      }}
+                    >
+                      {backdropBlurValue > 0 ? (
+                        <IconEye className="size-3.5" />
+                      ) : (
+                        <IconEyeOff className="size-3.5" />
+                      )}
+                    </SectionIconButton>
+                    <SectionIconButton
+                      label={t("editPanel.labels.removeLayer")}
+                      onClick={() =>
+                        onStyleChange(
+                          "backdropFilter",
+                          removeBlurFilterValue(backdropFilterValue),
+                        )
+                      }
+                      disabled={!backdropFilterHasBlur}
+                    >
+                      <IconMinus className="size-3.5" />
+                    </SectionIconButton>
+                  </div>
+                  <PopoverContent
+                    side="left"
+                    align="start"
+                    sideOffset={8}
+                    className="w-56 p-3"
+                  >
+                    <ScrubInput
+                      label={t("editPanel.labels.blur")}
+                      value={backdropBlurValue}
+                      onChange={(value, meta) =>
+                        onStyleChange(
+                          "backdropFilter",
+                          setBlurFilterValue(backdropFilterValue, value),
+                          meta,
+                        )
+                      }
+                      unit="px"
+                      min={0}
+                      precision={1}
+                      labelClassName="w-16"
+                      inputClassName="h-6"
+                    />
+                  </PopoverContent>
+                </Popover>
+              ) : null}
+            </>
+          )}
           {glslShaderContext?.nodeId ? (
             /* Code-backed GLSL shader effect — overlay canvas above the
            element's content, persisted as editable GLSL in the screen HTML
diff --git a/templates/design/app/components/design/edit-panel/element-classification.test.ts b/templates/design/app/components/design/edit-panel/element-classification.test.ts
index 540a5fe998..0531d44f30 100644
--- a/templates/design/app/components/design/edit-panel/element-classification.test.ts
+++ b/templates/design/app/components/design/edit-panel/element-classification.test.ts
@@ -14,7 +14,11 @@
 import { describe, expect, it, vi } from "vitest";
 
 import type { ElementInfo } from "../types";
-import { commitElementMinMax, isTextElement } from "./element-classification";
+import {
+  commitElementMinMax,
+  isContainerElement,
+  isTextElement,
+} from "./element-classification";
 
 function makeElement(overrides: Partial<ElementInfo> = {}): ElementInfo {
   return {
@@ -126,6 +130,94 @@ describe("isTextElement — B5-12 nested board text regression", () => {
   });
 });
 
+describe("isContainerElement — primitive inspector layout semantics", () => {
+  it("treats empty rectangle and frame primitives as containers", () => {
+    expect(
+      isContainerElement(
+        makeElement({
+          primitiveKind: "rectangle",
+          sourceId: "draft-rect-1",
+          childElementCount: 0,
+        }),
+      ),
+    ).toBe(true);
+    expect(
+      isContainerElement(
+        makeElement({
+          primitiveKind: "frame",
+          sourceId: "draft-frame-1",
+          childElementCount: 0,
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("does not mistake a flex-backed T-tool primitive for a container", () => {
+    expect(
+      isContainerElement(
+        makeElement({
+          primitiveKind: "text",
+          sourceId: "draft-text-1",
+          isFlexContainer: true,
+          childElementCount: 0,
+          textContent: "Label",
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it("keeps div-backed non-container drawing primitives as leaves", () => {
+    for (const primitiveKind of [
+      "ellipse",
+      "line",
+      "arrow",
+      "polygon",
+      "star",
+      "path",
+    ]) {
+      expect(
+        isContainerElement(
+          makeElement({ primitiveKind, childElementCount: 0 }),
+        ),
+      ).toBe(false);
+    }
+  });
+
+  // Regression: the `isTextElement(element)) return false` short-circuit
+  // added to fix the flex-backed T-tool text primitive case above (a real
+  // `primitiveKind: "text"` marker) was too broad — it also ran
+  // `isTextElement`'s generic childless-div-with-text fallback, which has
+  // nothing to do with the T-tool and matches any ordinary content div with
+  // no primitive/tag/id marker at all. That silently stripped the
+  // Flow/Padding/Auto-layout sections from ordinary Tailwind pill/badge/
+  // button-label divs — ubiquitous in generated markup — even though they
+  // hit `isFlexContainer`/`CONTAINER_TAGS` and were correctly treated as
+  // containers before that short-circuit existed.
+  it("still treats a childless flex div with its own text as a container (no primitive markers at all)", () => {
+    expect(
+      isContainerElement(
+        makeElement({
+          isFlexContainer: true,
+          childElementCount: 0,
+          textContent: "3 new",
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("still treats a plain childless div with its own text and container-ish classes as a container", () => {
+    expect(
+      isContainerElement(
+        makeElement({
+          classes: ["inline-flex", "items-center", "rounded-full", "px-3"],
+          childElementCount: 0,
+          textContent: "Badge label",
+        }),
+      ),
+    ).toBe(true);
+  });
+});
+
 // ─── commitElementMinMax — scrub gesture meta threading (B5-14 follow-up) ────
 //
 // Min/max constraint fields are ScrubInputs; dropping their gesture meta on
diff --git a/templates/design/app/components/design/edit-panel/element-classification.ts b/templates/design/app/components/design/edit-panel/element-classification.ts
index a197a2a314..cbd7e0095c 100644
--- a/templates/design/app/components/design/edit-panel/element-classification.ts
+++ b/templates/design/app/components/design/edit-panel/element-classification.ts
@@ -152,6 +152,27 @@ const LEAF_TAGS = new Set([
   "iframe",
 ]);
 
+/**
+ * Explicit, unambiguous signals that an element IS a text object: a real
+ * text tag, an authoritative `primitiveKind === "text"` marker, or a
+ * `draft-text-*` tool-drawn id. Deliberately excludes `isTextElement()`'s
+ * last-resort fallback for payloads with no primitive marker at all (a
+ * childless div with its own text content) — that heuristic exists to catch
+ * genuine T-tool text primitives whose payload happens to be missing
+ * `primitiveKind`, but it also matches ordinary content divs with no
+ * relation to the T-tool at all (Tailwind pill/badge/button-label markup is
+ * routinely a childless `<div>` with its own text). Used by
+ * `isContainerElement()` below, which must not misclassify those ordinary
+ * divs as text just because they're childless and have text content.
+ */
+function hasExplicitTextIdentity(element: ElementInfo): boolean {
+  const tag = (element.tagName || "").toLowerCase();
+  if (TEXT_TAGS.has(tag)) return true;
+  if (element.primitiveKind) return element.primitiveKind === "text";
+  const nodeId = element.sourceId || element.pendingNodeId || "";
+  return nodeId.startsWith("draft-text-");
+}
+
 /**
  * Whether the element should expose the Auto layout section. True for anything
  * already laid out with flexbox, or any block-level container tag that isn't a
@@ -159,6 +180,26 @@ const LEAF_TAGS = new Set([
  * children show the full Auto layout section the same way does.
  */
 export function isContainerElement(element: ElementInfo): boolean {
+  // T-tool text primitives are divs and use `display:flex` for vertical text
+  // alignment, but they are still leaf text layers rather than auto-layout
+  // containers, so check text identity before the flex/container shortcuts
+  // (fixing empty frame controls must not expose Flow/Padding on text
+  // layers). This short-circuit must only fire on an EXPLICIT text signal
+  // (see `hasExplicitTextIdentity`) rather than `isTextElement()`'s generic
+  // childless-div-with-text fallback: that fallback alone would also match
+  // ordinary text-only divs with no primitive/tag/id marker at all —
+  // ubiquitous in generated markup (Tailwind pills/badges/button-label
+  // divs) — stripping the Flow/Padding/Auto-layout sections from every one
+  // of them even though they're legitimate flex/block containers.
+  if (hasExplicitTextIdentity(element)) return false;
+  // Canvas primitive markers are authoritative. This code-backed editor lets
+  // rectangles act as lightweight containers (nest-on-drop promotes them to
+  // auto layout), and frames are containers by definition. Other drawn
+  // shapes remain leaves even though several are represented by a plain div.
+  const primitiveKind = element.primitiveKind?.trim().toLowerCase();
+  if (primitiveKind) {
+    return ["frame", "rectangle", "rect"].includes(primitiveKind);
+  }
   if (element.isFlexContainer || element.isGridContainer) return true;
   const tag = (element.tagName || "").toLowerCase();
   if (TEXT_TAGS.has(tag) || LEAF_TAGS.has(tag)) return false;
@@ -176,13 +217,6 @@ export function isParentGrid(element: ElementInfo): boolean {
   return Boolean(element.parentDisplay?.toLowerCase().includes("grid"));
 }
 
-export function elementHasLayoutChildren(element: ElementInfo): boolean {
-  if (typeof element.childElementCount === "number") {
-    return element.childElementCount > 0;
-  }
-  return Boolean(element.htmlContent?.match(/<\s*[a-zA-Z][^>]*>/));
-}
-
 export function parentFlexDirection(
   element: ElementInfo,
 ): AutoLayoutSizingAxis {
diff --git a/templates/design/app/components/design/edit-panel/element-identity.test.ts b/templates/design/app/components/design/edit-panel/element-identity.test.ts
new file mode 100644
index 0000000000..9eccb931b9
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/element-identity.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+
+import type { ElementInfo } from "../types";
+import {
+  deriveLockedAspectSize,
+  elementIdentityKey,
+  elementStableKey,
+} from "./element-identity";
+
+function element(overrides: Partial<ElementInfo> = {}): ElementInfo {
+  return {
+    tagName: "div",
+    classes: [],
+    computedStyles: {},
+    boundingRect: { x: 0, y: 0, width: 100, height: 50 },
+    isFlexChild: false,
+    isFlexContainer: false,
+    ...overrides,
+  } as ElementInfo;
+}
+
+describe("elementStableKey", () => {
+  it("prefers sourceId when present", () => {
+    expect(elementStableKey(element({ sourceId: "node-1", id: "el-1" }))).toBe(
+      "node-1",
+    );
+  });
+
+  it("falls through an empty-string sourceId to id/selector/tagName", () => {
+    // The bridge (editor-chrome.bridge.ts getElementInfo) reports
+    // sourceId: "" — not undefined — for any element that isn't
+    // source-backed (e.g. a runtime-only DOM node in a connected
+    // localhost/fusion screen). A `??` chain stops at "" (it isn't
+    // nullish), so it must be `||` throughout to actually skip it.
+    expect(
+      elementStableKey(
+        element({ sourceId: "", id: "", selector: ".card > .title" }),
+      ),
+    ).toBe(".card > .title");
+  });
+
+  it("does not collapse two different non-source-backed elements to the same key", () => {
+    // This is the concrete symptom of the `??` bug: two unrelated elements
+    // that both lack sourceId/id would otherwise both resolve to "" and
+    // share aspect-ratio-lock state (see useAspectRatioLock) even though
+    // they are completely different nodes.
+    const a = element({ sourceId: "", selector: ".card:nth-child(1)" });
+    const b = element({ sourceId: "", selector: ".card:nth-child(2)" });
+    expect(elementStableKey(a)).not.toBe(elementStableKey(b));
+  });
+
+  it("falls all the way through to tagName when nothing else is set", () => {
+    expect(
+      elementStableKey(element({ sourceId: "", id: "", selector: "" })),
+    ).toBe("div");
+  });
+});
+
+describe("elementIdentityKey", () => {
+  it("changes when the bounding rect changes, even for the same stable key", () => {
+    const a = elementIdentityKey(
+      element({
+        sourceId: "node-1",
+        boundingRect: { x: 0, y: 0, width: 10, height: 10 },
+      }),
+    );
+    const b = elementIdentityKey(
+      element({
+        sourceId: "node-1",
+        boundingRect: { x: 0, y: 0, width: 20, height: 10 },
+      }),
+    );
+    expect(a).not.toBe(b);
+  });
+
+  it("uses the same empty-string fall-through as elementStableKey", () => {
+    const key = elementIdentityKey(
+      element({
+        sourceId: "",
+        id: "",
+        selector: ".sidebar > .item",
+        boundingRect: { x: 1, y: 2, width: 3, height: 4 },
+      }),
+    );
+    expect(key).toBe(".sidebar > .item:1:2:3:4");
+  });
+});
+
+// deriveLockedAspectSize — W/H aspect-ratio lock: derives the paired
+// dimension from a captured width/height ratio. See EditPanel.inspectorHelpers.spec.ts
+// for the original coverage; duplicated narrowly here since element-identity.ts
+// is this file's home now.
+describe("deriveLockedAspectSize", () => {
+  it("derives height from width using the locked ratio", () => {
+    expect(deriveLockedAspectSize("width", 300, 2)).toBe(150);
+  });
+
+  it("derives width from height using the locked ratio", () => {
+    expect(deriveLockedAspectSize("height", 150, 2)).toBe(300);
+  });
+
+  it("rounds to one decimal place", () => {
+    expect(deriveLockedAspectSize("width", 100, 3)).toBe(33.3);
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/element-identity.ts b/templates/design/app/components/design/edit-panel/element-identity.ts
index 7ad954edda..3239363dd2 100644
--- a/templates/design/app/components/design/edit-panel/element-identity.ts
+++ b/templates/design/app/components/design/edit-panel/element-identity.ts
@@ -5,7 +5,7 @@ import { roundToOneDecimal } from "./position-helpers";
 
 export function elementIdentityKey(element: ElementInfo): string {
   return [
-    element.sourceId ?? element.id ?? element.selector ?? element.tagName,
+    elementStableKey(element),
     Math.round(element.boundingRect.x),
     Math.round(element.boundingRect.y),
     Math.round(element.boundingRect.width),
@@ -18,9 +18,22 @@ export function elementIdentityKey(element: ElementInfo): string {
  * resizing (unlike elementIdentityKey, which folds in the bounding rect and
  * therefore changes on every resize — exactly what an aspect-ratio lock needs
  * to persist across). Falls back through the same id chain.
+ *
+ * Uses `||`, not `??`, between the fallback candidates: the bridge
+ * (editor-chrome.bridge.ts getElementInfo) reports `sourceId` as the empty
+ * string `""` — not `undefined` — for any element that isn't source-backed
+ * (e.g. a runtime-only DOM node in a connected localhost/fusion screen). `??`
+ * only skips a nullish left-hand side, so an empty-string `sourceId` short-
+ * circuited the whole chain and every non-source-backed element collapsed to
+ * the SAME key ("" here, and just the rounded bounding rect in
+ * elementIdentityKey). For this hook that meant locking the aspect ratio on
+ * one such element silently applied its captured ratio to every other
+ * non-source-backed element too. `||` falls through empty strings the same
+ * way the bridge itself already does (`getSourceId(el) || getSelector(el)`),
+ * reaching the real per-element `selector` instead. Exported for tests.
  */
-function elementStableKey(element: ElementInfo): string {
-  return element.sourceId ?? element.id ?? element.selector ?? element.tagName;
+export function elementStableKey(element: ElementInfo): string {
+  return element.sourceId || element.id || element.selector || element.tagName;
 }
 
 /**
diff --git a/templates/design/app/components/design/edit-panel/field-primitives.tsx b/templates/design/app/components/design/edit-panel/field-primitives.tsx
index 2314d47eed..baaf0d2672 100644
--- a/templates/design/app/components/design/edit-panel/field-primitives.tsx
+++ b/templates/design/app/components/design/edit-panel/field-primitives.tsx
@@ -20,16 +20,29 @@ import {
   type ScrubInputChangeMeta,
 } from "../inspector";
 import type { ElementInfo } from "../types";
+import { roundToOneDecimal } from "./position-helpers";
 import { isMixedValue } from "./selection-helpers";
 import {
   resolveBreakpointOverride,
   type BreakpointOverrideFieldContext,
   type MotionKeyframeFieldContext,
+  type StyleChangeMeta,
   type StyleChangeHandler,
   type StylesChangeHandler,
 } from "./style-change-types";
 import { parseNumericValue, sidesAreLinked } from "./style-options";
 
+/**
+ * The CSS length DesignSpacingControl commits for one side's scrub/typed
+ * value. Rounds to one decimal place (not a whole pixel) to match the
+ * `precision={1}` the four per-side ScrubInput fields below advertise — see
+ * `roundToOneDecimal`'s docstring on why 0.5-unit values must survive the
+ * round trip. Exported so the precision contract is unit-testable directly.
+ */
+export function resolveSpacingSideValue(value: number): string {
+  return `${roundToOneDecimal(value)}px`;
+}
+
 export function DesignSpacingControl({
   label,
   values,
@@ -47,14 +60,19 @@ export function DesignSpacingControl({
     bottom: parseNumericValue(values.bottom || "0"),
     left: parseNumericValue(values.left || "0"),
   };
-  const linkedValue = Math.round(
+  const linkedValue = roundToOneDecimal(
     (numeric.top + numeric.right + numeric.bottom + numeric.left) / 4,
   );
   const setSide = (
     side: "Top" | "Right" | "Bottom" | "Left",
     value: number,
   ) => {
-    onChange(side, `${Math.round(value)}px`);
+    // Was `Math.round(value)`, which silently floored every typed/scrubbed
+    // 0.5px value to a whole pixel — contradicting the `precision={1}` these
+    // fields advertise (below) and diverging from every other ScrubInput
+    // commit site in this panel (position X/Y, stroke weight, font size all
+    // use roundToOneDecimal).
+    onChange(side, resolveSpacingSideValue(value));
   };
   const setAll = (value: number) => {
     (["Top", "Right", "Bottom", "Left"] as const).forEach((side) =>
@@ -98,6 +116,7 @@ export function DesignSpacingControl({
           onChange={setAll}
           unit="px"
           min={0}
+          precision={1}
           labelClassName="w-16"
           inputClassName="h-6"
         />
@@ -304,12 +323,13 @@ export function commitStylePatch(
   styles: Record<string, string>,
   onStyleChange: StyleChangeHandler,
   onStylesChange?: StylesChangeHandler,
+  meta?: StyleChangeMeta,
 ) {
   if (onStylesChange) {
-    onStylesChange(styles);
+    onStylesChange(styles, meta);
     return;
   }
   Object.entries(styles).forEach(([property, value]) => {
-    onStyleChange(property, value);
+    onStyleChange(property, value, meta);
   });
 }
diff --git a/templates/design/app/components/design/edit-panel/fill-gradient-helpers.spec.ts b/templates/design/app/components/design/edit-panel/fill-gradient-helpers.spec.ts
new file mode 100644
index 0000000000..b892601b49
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/fill-gradient-helpers.spec.ts
@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  imageFillChangePatch,
+  isLayerHiddenBySize,
+  setImageFillLayerPatch,
+  splitCssLayers,
+  withLayerSizeMarker,
+  type FillLayerArrays,
+} from "./fill-gradient-helpers";
+
+describe("setImageFillLayerPatch (IP: layer-index-aware image fill)", () => {
+  it("overwrites only the targeted layer's four values, preserving siblings", () => {
+    const layers: FillLayerArrays = {
+      backgroundImage: [
+        "linear-gradient(90deg, red 0%, blue 100%)",
+        'url("old.png")',
+      ],
+      backgroundSize: ["auto", "cover"],
+      backgroundRepeat: ["no-repeat", "no-repeat"],
+      backgroundPosition: ["0% 0%", "center"],
+    };
+    const patch = setImageFillLayerPatch(layers, 1, {
+      backgroundImage: 'url("new.png")',
+      backgroundSize: "contain",
+      backgroundRepeat: "no-repeat",
+      backgroundPosition: "center",
+    });
+
+    const imageLayers = splitCssLayers(patch.backgroundImage);
+    expect(imageLayers[0]).toBe("linear-gradient(90deg, red 0%, blue 100%)");
+    expect(imageLayers[1]).toBe('url("new.png")');
+    expect(splitCssLayers(patch.backgroundSize)).toEqual(["auto", "contain"]);
+    expect(splitCssLayers(patch.backgroundPosition)).toEqual([
+      "0% 0%",
+      "center",
+    ]);
+  });
+
+  it("appends a new layer when index is one past the current end, padding siblings with CSS defaults", () => {
+    const layers: FillLayerArrays = {
+      backgroundImage: ['url("a.png")'],
+      backgroundSize: ["cover"],
+      backgroundRepeat: ["no-repeat"],
+      backgroundPosition: ["center"],
+    };
+    const patch = setImageFillLayerPatch(layers, 1, {
+      backgroundImage: 'url("b.png")',
+      backgroundSize: "cover",
+      backgroundRepeat: "no-repeat",
+      backgroundPosition: "center",
+    });
+    expect(splitCssLayers(patch.backgroundImage)).toEqual([
+      'url("a.png")',
+      'url("b.png")',
+    ]);
+  });
+});
+
+describe("imageFillChangePatch (IP: base-fill Image switch preserves the layer stack)", () => {
+  it("replaces CSS-wide shorthand defaults instead of emitting an invalid comma layer", () => {
+    const patch = imageFillChangePatch(
+      {
+        backgroundImage: splitCssLayers("initial"),
+        backgroundSize: splitCssLayers("initial"),
+        backgroundRepeat: splitCssLayers("initial"),
+        backgroundPosition: splitCssLayers("initial"),
+      },
+      null,
+      {
+        backgroundImage: 'url("tile.png")',
+        backgroundSize: "auto",
+        backgroundRepeat: "repeat",
+        backgroundPosition: "top left",
+      },
+    );
+
+    expect(patch).toEqual({
+      backgroundImage: 'url("tile.png")',
+      backgroundSize: "auto",
+      backgroundRepeat: "repeat",
+      backgroundPosition: "top left",
+    });
+  });
+
+  it("prepends the image as a new layer instead of replacing the whole stack when no layer is selected", () => {
+    // Regression: switching the base solid/text fill row's paint type to
+    // Image used to call a single-layer `imageFillToBackgroundStyles` patch
+    // that overwrote backgroundImage/backgroundSize/backgroundRepeat/
+    // backgroundPosition wholesale, silently discarding any gradient/image
+    // layer already stacked below the base fill.
+    const existingLayers: FillLayerArrays = {
+      backgroundImage: ["linear-gradient(90deg, red 0%, blue 100%)"],
+      backgroundSize: ["auto"],
+      backgroundRepeat: ["no-repeat"],
+      backgroundPosition: ["0% 0%"],
+    };
+    const patch = imageFillChangePatch(existingLayers, null, {
+      backgroundImage: 'url("photo.png")',
+      backgroundSize: "cover",
+      backgroundRepeat: "no-repeat",
+      backgroundPosition: "center",
+    });
+
+    const imageLayers = splitCssLayers(patch.backgroundImage);
+    expect(imageLayers).toHaveLength(2);
+    expect(imageLayers[0]).toBe('url("photo.png")');
+    // The previously-existing gradient layer must survive, not be wiped.
+    expect(imageLayers[1]).toBe("linear-gradient(90deg, red 0%, blue 100%)");
+    expect(splitCssLayers(patch.backgroundSize)).toEqual(["cover", "auto"]);
+  });
+
+  it("delegates to setImageFillLayerPatch when a real layer index is selected", () => {
+    const existingLayers: FillLayerArrays = {
+      backgroundImage: ['url("old.png")', "linear-gradient(0deg, red, blue)"],
+      backgroundSize: ["cover", "auto"],
+      backgroundRepeat: ["no-repeat", "no-repeat"],
+      backgroundPosition: ["center", "0% 0%"],
+    };
+    const patch = imageFillChangePatch(existingLayers, 0, {
+      backgroundImage: 'url("new.png")',
+      backgroundSize: "contain",
+      backgroundRepeat: "no-repeat",
+      backgroundPosition: "top left",
+    });
+    const imageLayers = splitCssLayers(patch.backgroundImage);
+    expect(imageLayers[0]).toBe('url("new.png")');
+    expect(imageLayers[1]).toBe("linear-gradient(0deg, red, blue)");
+    expect(splitCssLayers(patch.backgroundSize)).toEqual(["contain", "auto"]);
+  });
+
+  it("produces a single-layer patch when there is no existing layer stack", () => {
+    const patch = imageFillChangePatch(
+      {
+        backgroundImage: [],
+        backgroundSize: [],
+        backgroundRepeat: [],
+        backgroundPosition: [],
+      },
+      null,
+      {
+        backgroundImage: 'url("solo.png")',
+        backgroundSize: "cover",
+        backgroundRepeat: "no-repeat",
+        backgroundPosition: "center",
+      },
+    );
+    expect(patch.backgroundImage).toBe('url("solo.png")');
+    expect(patch.backgroundSize).toBe("cover");
+  });
+});
+
+describe("withLayerSizeMarker restore value (IP: hide/show preserves custom size)", () => {
+  it("restores the stashed pre-hide size instead of always resetting to auto", () => {
+    // Regression: re-showing a hidden layer always reset its size to "auto",
+    // permanently discarding a custom cover/contain/percentage size that was
+    // set before it was hidden.
+    const shown = withLayerSizeMarker(
+      ["0px 0px", "auto"],
+      2,
+      0,
+      false,
+      "150% 150%",
+    );
+    expect(splitCssLayers(shown)).toEqual(["150% 150%", "auto"]);
+  });
+
+  it("still defaults to auto when no restore value is provided (back-compat)", () => {
+    const shown = withLayerSizeMarker(["0px 0px"], 1, 0, false);
+    expect(splitCssLayers(shown)).toEqual(["auto"]);
+    expect(isLayerHiddenBySize(splitCssLayers(shown)[0])).toBe(false);
+  });
+
+  it("still hides via the zero-size marker regardless of a restore value", () => {
+    const hidden = withLayerSizeMarker(["cover"], 1, 0, true, "cover");
+    expect(isLayerHiddenBySize(splitCssLayers(hidden)[0])).toBe(true);
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/fill-gradient-helpers.ts b/templates/design/app/components/design/edit-panel/fill-gradient-helpers.ts
index d32d9c7c6d..af6b0d32e0 100644
--- a/templates/design/app/components/design/edit-panel/fill-gradient-helpers.ts
+++ b/templates/design/app/components/design/edit-panel/fill-gradient-helpers.ts
@@ -11,7 +11,7 @@ import {
   type DesignGradientType,
   type ExportSettingsValue,
 } from "../inspector";
-import { cssColorOrFallback } from "./position-helpers";
+import { colorHasVisibleAlpha, cssColorOrFallback } from "./position-helpers";
 
 export const SOLID_FILL_ID = "solid";
 export const FILL_LAYER_PREFIX = "layer:";
@@ -113,24 +113,45 @@ export function isLayerHiddenBySize(sizeEntry: string | undefined): boolean {
  * Rewrites the background-size list so `index` is hidden/shown via the
  * zero-size marker, padding shorter lists with "auto" (the CSS default) so
  * every other layer keeps rendering at its current/default size.
+ *
+ * `restoreValue` is the size to bring back when un-hiding (`hidden: false`).
+ * Without it, re-showing always reset the layer to "auto", permanently
+ * discarding whatever custom cover/contain/percentage size the layer had
+ * before it was hidden — callers should capture the layer's own size entry
+ * before hiding it (it's about to be overwritten with the marker) and pass
+ * it back in here on the show path. Defaults to "auto" so existing callers
+ * that don't have a stashed value keep today's behavior.
  */
 export function withLayerSizeMarker(
   sizeLayers: string[],
   layerCount: number,
   index: number,
   hidden: boolean,
+  restoreValue?: string,
 ): string {
   const next = Array.from(
     { length: layerCount },
     (_, i) => sizeLayers[i] || "auto",
   );
-  next[index] = hidden ? HIDDEN_LAYER_SIZE_MARKER : "auto";
+  next[index] = hidden ? HIDDEN_LAYER_SIZE_MARKER : restoreValue || "auto";
   return joinCssLayers(next);
 }
 
 export function splitCssLayers(value: string): string[] {
   const trimmed = value.trim();
-  if (!trimmed || trimmed === "none") return [];
+  // CSS-wide keywords represent the property's default/inherited value as a
+  // whole; they are not real comma-stack layers and cannot legally be
+  // preserved beside a new gradient/image (`url(...), initial` invalidates
+  // the entire declaration). Shorthand-authored page backgrounds commonly
+  // surface as `initial` through CSSStyleDeclaration, so normalize these to
+  // an empty editable layer stack before adding a real fill.
+  if (
+    !trimmed ||
+    trimmed === "none" ||
+    /^(?:initial|inherit|unset|revert|revert-layer)$/i.test(trimmed)
+  ) {
+    return [];
+  }
   const layers: string[] = [];
   let depth = 0;
   let start = 0;
@@ -197,6 +218,189 @@ export function removeFillLayerAtIndex(
   };
 }
 
+/** One image-fill layer's four index-aligned CSS values. */
+export interface ImageFillLayerStyles {
+  backgroundImage: string;
+  backgroundSize: string;
+  backgroundRepeat: string;
+  backgroundPosition: string;
+}
+
+/**
+ * Sets one image-fill layer's four index-aligned CSS values at `index`,
+ * preserving every sibling layer's own image/size/repeat/position — the
+ * image-fill analog of `removeFillLayerAtIndex`/`reorderFillLayers`. `index`
+ * may be one past the current layer count to append a new layer. Shorter
+ * parallel arrays are padded with each property's CSS default (mirrors
+ * `addFillLayerPatch`'s defaults) so sibling layers keep rendering unchanged.
+ */
+export function setImageFillLayerPatch(
+  layers: FillLayerArrays,
+  index: number,
+  imageStyles: ImageFillLayerStyles,
+): Record<
+  | "backgroundImage"
+  | "backgroundSize"
+  | "backgroundRepeat"
+  | "backgroundPosition",
+  string
+> {
+  const layerCount = Math.max(layers.backgroundImage.length, index + 1);
+  const buildLayer = (existing: string[], fallback: string, override: string) =>
+    joinCssLayers(
+      Array.from({ length: layerCount }, (_, i) =>
+        i === index ? override : existing[i] || fallback,
+      ),
+    );
+  return {
+    backgroundImage: buildLayer(
+      layers.backgroundImage,
+      "none",
+      imageStyles.backgroundImage,
+    ),
+    backgroundSize: buildLayer(
+      layers.backgroundSize,
+      "auto",
+      imageStyles.backgroundSize,
+    ),
+    backgroundRepeat: buildLayer(
+      layers.backgroundRepeat,
+      "no-repeat",
+      imageStyles.backgroundRepeat,
+    ),
+    backgroundPosition: buildLayer(
+      layers.backgroundPosition,
+      "0% 0%",
+      imageStyles.backgroundPosition,
+    ),
+  };
+}
+
+/**
+ * Full patch-building logic behind `ColorInput`'s image-fill handler.
+ *
+ * Previously, editing the base fill row's image (via `ImageFillControls` ->
+ * `DesignColorPicker.onImageFillChange`) always replaced the *whole*
+ * `backgroundImage`/`backgroundSize`/`backgroundRepeat`/`backgroundPosition`
+ * properties with a single-layer patch (see `imageFillToBackgroundStyles`),
+ * silently discarding any other gradient/image layers already stacked below
+ * it — there was no layer-index-aware merge at all.
+ *
+ * When `layerIndex` is a real index (editing an existing layer's own image),
+ * only that layer's four values are overwritten, preserving every sibling —
+ * see `setImageFillLayerPatch`. When `layerIndex` is `null` (the base
+ * solid/text row switching its paint type to Image, with no layer selected
+ * yet), the image becomes a new layer PREPENDED above the existing layer
+ * stack — mirroring `solidToGradientPatch`'s solid -> gradient conversion —
+ * instead of clobbering the whole background stack.
+ */
+export function imageFillChangePatch(
+  layers: FillLayerArrays,
+  layerIndex: number | null,
+  imageStyles: ImageFillLayerStyles,
+): Record<
+  | "backgroundImage"
+  | "backgroundSize"
+  | "backgroundRepeat"
+  | "backgroundPosition",
+  string
+> {
+  if (layerIndex !== null) {
+    return setImageFillLayerPatch(layers, layerIndex, imageStyles);
+  }
+  return {
+    backgroundImage: joinCssLayers([
+      imageStyles.backgroundImage,
+      ...layers.backgroundImage,
+    ]),
+    backgroundSize: joinCssLayers([
+      imageStyles.backgroundSize,
+      ...layers.backgroundSize,
+    ]),
+    backgroundRepeat: joinCssLayers([
+      imageStyles.backgroundRepeat,
+      ...layers.backgroundRepeat,
+    ]),
+    backgroundPosition: joinCssLayers([
+      imageStyles.backgroundPosition,
+      ...layers.backgroundPosition,
+    ]),
+  };
+}
+
+/**
+ * Patch for the Fill panel's "+" (add fill) action.
+ *
+ * Figma parity: clicking "+" always adds a new fill on top of whatever is
+ * already there. The only exception is a genuinely empty fill state (no
+ * visible base solid AND no existing background layers) — there "+" just
+ * reveals the hidden base solid instead of stacking an empty default
+ * gradient on top of nothing.
+ *
+ * Previously the caller only checked whether the base solid had visible
+ * alpha, so an element with an existing gradient/image layer stack but a
+ * *hidden* base solid (e.g. right after `solidToGradientPatch` converts
+ * solid -> gradient and clears backgroundColor to "transparent") had "+"
+ * silently un-hide the base solid instead of adding a new layer — the
+ * opposite of what "+" is supposed to do, and it reintroduced the exact
+ * phantom-second-fill problem `solidToGradientPatch` exists to avoid.
+ */
+export function addFillLayerPatch(params: {
+  backgroundColor: string | undefined;
+  backgroundLayers: string[];
+  backgroundSizeLayers: string[];
+  backgroundRepeatLayers: string[];
+  backgroundPositionLayers: string[];
+}): Record<string, string> {
+  const {
+    backgroundColor,
+    backgroundLayers,
+    backgroundSizeLayers,
+    backgroundRepeatLayers,
+    backgroundPositionLayers,
+  } = params;
+
+  if (!colorHasVisibleAlpha(backgroundColor) && backgroundLayers.length === 0) {
+    return { backgroundColor: cssColorOrFallback(backgroundColor, "#ffffff") };
+  }
+
+  const nextLayer = defaultGradientLayer(
+    "linear",
+    backgroundColor || "#ffffff",
+  );
+  if (backgroundLayers.length === 0) {
+    return { backgroundImage: nextLayer };
+  }
+
+  // Prepending a layer without also prepending matching entries to the
+  // other three index-aligned parallel arrays (size/repeat/position) would
+  // shift every existing layer's index by one, silently re-pairing each of
+  // them with the *previous* layer's size/repeat/position (same class of
+  // bug `removeFillLayerAtIndex` above fixes for removal).
+  return {
+    backgroundImage: joinCssLayers([nextLayer, ...backgroundLayers]),
+    backgroundSize: joinCssLayers(["auto", ...backgroundSizeLayers]),
+    backgroundRepeat: joinCssLayers(["no-repeat", ...backgroundRepeatLayers]),
+    backgroundPosition: joinCssLayers(["0% 0%", ...backgroundPositionLayers]),
+  };
+}
+
+/**
+ * Patch for removing just the base solid/text fill row — the row shown when
+ * the base color has visible alpha, or always for a text fill. Must only
+ * clear that one property, never `backgroundImage`, so any other stacked
+ * gradient/image layers (each rendered as its own row with its own
+ * independent remove button — see `removeFillLayerAtIndex`) are left
+ * untouched. This used to also zero `backgroundImage` whenever the caller
+ * had `onStylesChange` available, silently deleting every other fill layer
+ * any time the base row's own remove button was clicked.
+ */
+export function removeBaseFillPatch(
+  fillProperty: "color" | "backgroundColor",
+): Record<string, string> {
+  return { [fillProperty]: "transparent" };
+}
+
 export function parseGradientLayer(layer: string): ParsedGradientLayer | null {
   const match = layer.trim().match(/^(linear|radial|conic)-gradient\((.*)\)$/i);
   if (!match) return null;
@@ -247,7 +451,21 @@ function readLeadingColor(part: string): { raw: string; value: string } | null {
     return { raw: transparent[0], value: "rgba(0, 0, 0, 0)" };
   }
   const functionName = trimmed.match(/^[a-z][a-z0-9-]*\(/i);
-  if (!functionName) return null;
+  if (!functionName) {
+    // Bare CSS color keyword — e.g. `linear-gradient(red, blue)` — not just
+    // hex/rgb/hsl/function colors. Gradients written by hand or generated
+    // from named-color CSS are common, and without this branch the leading
+    // stop was silently misread as a gradient *prefix* (the first stop's
+    // color was dropped, corrupting an otherwise-valid 2-stop gradient into
+    // a broken 1-stop one with a garbage prefix). Require the matched word to
+    // actually parse as a color so direction/shape prefix keywords ("to",
+    // "circle", "closest-side", "from", "at", …) are never misclassified.
+    const word = trimmed.match(/^[a-z]+\b/i);
+    if (word && parseCssColor(word[0])) {
+      return { raw: word[0], value: word[0] };
+    }
+    return null;
+  }
   let depth = 0;
   for (let index = 0; index < trimmed.length; index += 1) {
     const char = trimmed[index];
diff --git a/templates/design/app/components/design/edit-panel/fill-properties.test.tsx b/templates/design/app/components/design/edit-panel/fill-properties.test.tsx
new file mode 100644
index 0000000000..94bc41b125
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/fill-properties.test.tsx
@@ -0,0 +1,196 @@
+/**
+ * Base fill row image-layer prop wiring regression.
+ *
+ * `FillProperties`' base swatch renders a `<ColorInput>` whose
+ * `onImageFillLayerChange` builds its commit patch from whatever ColorInput
+ * computes internally from its `backgroundImage`/`backgroundSize`/
+ * `backgroundRepeat`/`backgroundPosition` props (see `imageFillChangePatch`
+ * in fill-gradient-helpers.ts). The base row previously only passed
+ * `backgroundImage`, so ColorInput treated every sibling layer as having no
+ * size/repeat/position of its own — switching the base swatch to Image then
+ * rebuilt those three properties as a single-entry list against the real
+ * N+1-layer backgroundImage stack, corrupting every existing gradient/image
+ * layer's size/repeat/position via CSS background-layer-list cycling (e.g.
+ * an existing "cover" silently became "auto").
+ *
+ * There is no React Testing Library in this app, but `layout-properties.test.tsx`
+ * establishes the pattern of rendering with `react-dom/server` and asserting
+ * on the resulting markup, so this file follows the same approach: stub out
+ * `ColorInput` to surface the exact props it receives, then assert the base
+ * row's `<ColorInput>` is wired with the real backgroundSize/backgroundRepeat/
+ * backgroundPosition values instead of leaving them empty.
+ */
+
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+
+import type { ElementInfo } from "../types";
+import { baseFillLayerSourceProps, FillProperties } from "./fill-properties";
+
+vi.mock("@agent-native/core/client", () => ({
+  cn: (...inputs: Array<string | false | null | undefined>) =>
+    inputs.filter(Boolean).join(" "),
+  useT: () => (key: string) => key,
+}));
+
+vi.mock("@/components/ui/tooltip", () => ({
+  Tooltip: ({ children }: { children?: unknown }) => children as never,
+  TooltipTrigger: ({ children }: { children?: unknown }) => children as never,
+  TooltipContent: () => null,
+  TooltipProvider: ({ children }: { children?: unknown }) => children as never,
+}));
+
+vi.mock("@/components/ui/popover", () => ({
+  Popover: ({ children }: { children?: unknown }) => children as never,
+  PopoverTrigger: ({ children }: { children?: unknown }) => children as never,
+  PopoverContent: () => null,
+}));
+
+vi.mock("../inspector", () => ({
+  DesignColorPicker: () => null,
+  imageFillToBackgroundStyles: () => ({
+    backgroundImage: "",
+    backgroundSize: "",
+    backgroundRepeat: "",
+    backgroundPosition: "",
+  }),
+}));
+
+vi.mock("./field-primitives", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./field-primitives")>();
+  return {
+    ...actual,
+    FieldTrailer: () => null,
+  };
+});
+
+// Stub ColorInput so the test can inspect exactly what props the base fill
+// row wires it with, without needing to render the real popover/picker tree.
+vi.mock("./panel-primitives", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./panel-primitives")>();
+  return {
+    ...actual,
+    ColorInput: (props: {
+      value: string;
+      backgroundImage?: string;
+      backgroundSize?: string;
+      backgroundRepeat?: string;
+      backgroundPosition?: string;
+    }) =>
+      createElement("div", {
+        "data-testid": "base-fill-color-input",
+        "data-value": props.value,
+        "data-background-image": props.backgroundImage ?? "",
+        "data-background-size": props.backgroundSize ?? "",
+        "data-background-repeat": props.backgroundRepeat ?? "",
+        "data-background-position": props.backgroundPosition ?? "",
+      }),
+  };
+});
+
+function element(overrides: Partial<ElementInfo> = {}): ElementInfo {
+  return {
+    tagName: "div",
+    classes: [],
+    computedStyles: {},
+    boundingRect: { x: 0, y: 0, width: 0, height: 0 },
+    isFlexChild: false,
+    isFlexContainer: false,
+    childElementCount: 0,
+    ...overrides,
+  } as ElementInfo;
+}
+
+describe("baseFillLayerSourceProps", () => {
+  it("sources all four background layer props together for a non-text fill", () => {
+    expect(
+      baseFillLayerSourceProps(
+        {
+          backgroundImage: "url(a.png), linear-gradient(red, blue)",
+          backgroundSize: "cover, 100% 100%",
+          backgroundRepeat: "no-repeat, repeat",
+          backgroundPosition: "center, 0% 0%",
+        },
+        false,
+      ),
+    ).toEqual({
+      backgroundImage: "url(a.png), linear-gradient(red, blue)",
+      backgroundSize: "cover, 100% 100%",
+      backgroundRepeat: "no-repeat, repeat",
+      backgroundPosition: "center, 0% 0%",
+    });
+  });
+
+  it("collapses every value to empty for a text fill (color can't hold a layered paint)", () => {
+    expect(
+      baseFillLayerSourceProps(
+        {
+          backgroundImage: "url(a.png)",
+          backgroundSize: "cover",
+          backgroundRepeat: "no-repeat",
+          backgroundPosition: "center",
+        },
+        true,
+      ),
+    ).toEqual({
+      backgroundImage: "",
+      backgroundSize: "",
+      backgroundRepeat: "",
+      backgroundPosition: "",
+    });
+  });
+});
+
+describe("FillProperties base row — image layer prop wiring", () => {
+  it("wires backgroundSize/backgroundRepeat/backgroundPosition onto the base row's ColorInput, not just backgroundImage", () => {
+    const el = element({
+      computedStyles: {
+        backgroundColor: "rgba(255,255,255,1)",
+        backgroundImage: "url(hero.png), linear-gradient(red, blue)",
+        backgroundSize: "cover, 100% 100%",
+        backgroundRepeat: "no-repeat, repeat",
+        backgroundPosition: "center, 0% 0%",
+      },
+    });
+
+    const markup = renderToStaticMarkup(
+      createElement(FillProperties, {
+        element: el,
+        onStyleChange: vi.fn(),
+        onStylesChange: vi.fn(),
+      }),
+    );
+
+    // Before the fix, backgroundSize/backgroundRepeat/backgroundPosition were
+    // never passed at all, so these data attributes would be missing/empty
+    // even though the element clearly has real, non-default values for all
+    // three (a genuine "cover, 100% 100%" sibling layer stack).
+    expect(markup).toContain('data-background-image="url(hero.png)');
+    expect(markup).toContain('data-background-size="cover, 100% 100%"');
+    expect(markup).toContain('data-background-repeat="no-repeat, repeat"');
+    expect(markup).toContain('data-background-position="center, 0% 0%"');
+  });
+
+  it("leaves every layer prop empty for a text fill selection", () => {
+    const el = element({
+      tagName: "span",
+      computedStyles: {
+        color: "#000000",
+      },
+    });
+
+    const markup = renderToStaticMarkup(
+      createElement(FillProperties, {
+        element: el,
+        onStyleChange: vi.fn(),
+        onStylesChange: vi.fn(),
+      }),
+    );
+
+    expect(markup).toContain('data-background-image=""');
+    expect(markup).toContain('data-background-size=""');
+    expect(markup).toContain('data-background-repeat=""');
+    expect(markup).toContain('data-background-position=""');
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/fill-properties.tsx b/templates/design/app/components/design/edit-panel/fill-properties.tsx
index bf84ac8d8e..f19be037cf 100644
--- a/templates/design/app/components/design/edit-panel/fill-properties.tsx
+++ b/templates/design/app/components/design/edit-panel/fill-properties.tsx
@@ -12,6 +12,7 @@ import {
   IconMinus,
   IconPlus,
 } from "@tabler/icons-react";
+import { useState } from "react";
 
 import {
   Popover,
@@ -24,16 +25,19 @@ import type { GlslShaderPanelContext } from "../inspector/GlslShaderPanel";
 import type { ElementInfo } from "../types";
 import { selectionColorValues } from "./document-colors";
 import { isTextElement } from "./element-classification";
+import { elementStableKey } from "./element-identity";
 import { commitStylePatch, FieldTrailer } from "./field-primitives";
 import {
+  addFillLayerPatch,
   averageGradientOpacity,
   buildGradientLayer,
-  defaultGradientLayer,
   gradientLabel,
   isLayerHiddenBySize,
   joinCssLayers,
   parseGradientLayer,
+  removeBaseFillPatch,
   removeFillLayerAtIndex,
+  setImageFillLayerPatch,
   splitCssLayers,
   withLayerSizeMarker,
 } from "./fill-gradient-helpers";
@@ -45,7 +49,6 @@ import {
 import { ColorInput, PanelSection } from "./panel-primitives";
 import {
   colorHasVisibleAlpha,
-  compactCssValue,
   cssColorOrFallback,
   swatchStyle,
 } from "./position-helpers";
@@ -57,6 +60,50 @@ import type {
   StylesChangeHandler,
 } from "./style-change-types";
 
+/**
+ * The four `backgroundImage`/`backgroundSize`/`backgroundRepeat`/
+ * `backgroundPosition` prop values fed to the base fill row's `<ColorInput>`.
+ * Text fills ("color") can't hold a layered paint at all, so every value
+ * collapses to "" for them.
+ *
+ * Factored out (rather than inlined ternaries in the JSX below) as a
+ * regression guard: `ColorInput.onImageFillLayerChange` builds its commit
+ * patch from whatever it computes internally from these four props (see
+ * `imageFillChangePatch` in fill-gradient-helpers.ts). Previously only
+ * `backgroundImage` was passed here, so ColorInput treated every sibling
+ * layer as having no size/repeat/position of its own — switching this base
+ * swatch to Image then rebuilt backgroundSize/backgroundRepeat/
+ * backgroundPosition as a single-entry list against the real N+1-layer
+ * backgroundImage stack, corrupting every existing layer's size/repeat/
+ * position via CSS background-layer-list cycling (e.g. an existing "cover"
+ * silently became "auto"). All four must always be sourced together, exactly
+ * like PageProperties' background row in EditPanel.tsx.
+ */
+export function baseFillLayerSourceProps(
+  styles: Record<string, string>,
+  isTextFillElement: boolean,
+): {
+  backgroundImage: string;
+  backgroundSize: string;
+  backgroundRepeat: string;
+  backgroundPosition: string;
+} {
+  if (isTextFillElement) {
+    return {
+      backgroundImage: "",
+      backgroundSize: "",
+      backgroundRepeat: "",
+      backgroundPosition: "",
+    };
+  }
+  return {
+    backgroundImage: styles.backgroundImage || "",
+    backgroundSize: styles.backgroundSize || "",
+    backgroundRepeat: styles.backgroundRepeat || "",
+    backgroundPosition: styles.backgroundPosition || "",
+  };
+}
+
 export function FillProperties({
   element,
   onStyleChange,
@@ -87,6 +134,16 @@ export function FillProperties({
   const styles = element.computedStyles;
   const isTextFillElement = isTextElement(element);
   const fillProperty = isTextFillElement ? "color" : "backgroundColor";
+  // Stash for a hidden layer's real pre-hide backgroundSize (e.g. a custom
+  // cover/contain/percentage) so re-showing it restores that value instead
+  // of permanently discarding it for "auto" — the same React-state stash
+  // pattern effects-properties.tsx uses for hidden shadow/blur effects (see
+  // `hiddenEffectStash` there), keyed by element + layer index so unrelated
+  // elements/layers never collide.
+  const [hiddenFillSizeStash, setHiddenFillSizeStash] = useState<
+    Record<string, string>
+  >({});
+  const fillStashKey = elementStableKey(element);
   const fillValue = isTextFillElement
     ? styles.color || ""
     : styles.backgroundColor || "";
@@ -102,6 +159,10 @@ export function FillProperties({
   const backgroundPositionLayers = isTextFillElement
     ? []
     : splitCssLayers(styles.backgroundPosition || "");
+  const baseFillLayerProps = baseFillLayerSourceProps(
+    styles,
+    isTextFillElement,
+  );
   const fillIsMixed =
     isMixedValue(fillValue) ||
     isMixedValue(styles.backgroundImage) ||
@@ -239,50 +300,16 @@ export function FillProperties({
                 );
                 return;
               }
-              if (!colorHasVisibleAlpha(styles.backgroundColor)) {
-                onStyleChange(
-                  "backgroundColor",
-                  cssColorOrFallback(styles.backgroundColor, "#ffffff"),
-                );
-                return;
-              }
-              const current = compactCssValue(styles.backgroundImage, "");
-              const nextLayer = defaultGradientLayer(
-                "linear",
-                styles.backgroundColor || "#ffffff",
-              );
-              if (!current) {
-                onStyleChange("backgroundImage", nextLayer);
-                return;
-              }
-              // Prepending a layer without also prepending matching entries
-              // to the other three index-aligned parallel arrays
-              // (size/repeat/position) would shift every existing layer's
-              // index by one, silently re-pairing each of them with the
-              // *previous* layer's size/repeat/position (same class of bug
-              // as the removeLayer fix above). Commit a default entry for
-              // the new layer in all four arrays together, in one patch.
-              const patch = {
-                backgroundImage: `${nextLayer}, ${current}`,
-                backgroundSize: joinCssLayers([
-                  "auto",
-                  ...backgroundSizeLayers,
-                ]),
-                backgroundRepeat: joinCssLayers([
-                  "no-repeat",
-                  ...backgroundRepeatLayers,
-                ]),
-                backgroundPosition: joinCssLayers([
-                  "0% 0%",
-                  ...backgroundPositionLayers,
-                ]),
-              };
-              if (onStylesChange) {
-                onStylesChange(patch);
-                return;
-              }
-              Object.entries(patch).forEach(([property, value]) =>
-                onStyleChange(property, value),
+              commitStylePatch(
+                addFillLayerPatch({
+                  backgroundColor: styles.backgroundColor,
+                  backgroundLayers,
+                  backgroundSizeLayers,
+                  backgroundRepeatLayers,
+                  backgroundPositionLayers,
+                }),
+                onStyleChange,
+                onStylesChange,
               );
             }}
           >
@@ -312,10 +339,11 @@ export function FillProperties({
                   // layer on top of any existing backgroundImage layers
                   // (rendered as their own rows below) instead of clobbering
                   // them — ColorInput derives its add/replace-layer logic
-                  // from this prop.
-                  backgroundImage={
-                    isTextFillElement ? "" : styles.backgroundImage
-                  }
+                  // from this prop. The size/repeat/position siblings must
+                  // come along too (same as PageProperties' background row in
+                  // EditPanel.tsx) — see `baseFillLayerSourceProps` above for
+                  // why all four are sourced together.
+                  {...baseFillLayerProps}
                   blendMode={
                     isTextFillElement
                       ? undefined
@@ -342,15 +370,19 @@ export function FillProperties({
                       ? undefined
                       : (v) => onStyleChange("backgroundImage", v)
                   }
-                  onImageFillChange={
+                  // Layer-index-aware: ColorInput merges the edited image
+                  // into the correct backgroundImage/backgroundSize/
+                  // backgroundRepeat/backgroundPosition index and hands back
+                  // the full four-property patch here, already preserving
+                  // every other stacked gradient/image layer (see
+                  // `imageFillChangePatch`) — commit it as-is instead of
+                  // rebuilding a single-layer patch that would silently wipe
+                  // those siblings.
+                  onImageFillLayerChange={
                     isTextFillElement
                       ? undefined
-                      : (value) =>
-                          commitStylePatch(
-                            imageFillToBackgroundStyles(value),
-                            onStyleChange,
-                            onStylesChange,
-                          )
+                      : (patch) =>
+                          commitStylePatch(patch, onStyleChange, onStylesChange)
                   }
                   documentColors={documentColors}
                   pickerKey={[
@@ -384,20 +416,13 @@ export function FillProperties({
               </SectionIconButton>
               <SectionIconButton
                 label={t("editPanel.labels.removeLayer")}
-                onClick={() => {
-                  if (isTextFillElement) {
-                    onStyleChange(fillProperty, "transparent");
-                    return;
-                  }
-                  if (onStylesChange) {
-                    onStylesChange({
-                      backgroundColor: "transparent",
-                      backgroundImage: "none",
-                    });
-                  } else {
-                    onStyleChange(fillProperty, "transparent");
-                  }
-                }}
+                onClick={() =>
+                  commitStylePatch(
+                    removeBaseFillPatch(fillProperty),
+                    onStyleChange,
+                    onStylesChange,
+                  )
+                }
               >
                 <IconMinus className="size-3.5" />
               </SectionIconButton>
@@ -415,12 +440,18 @@ export function FillProperties({
           {!isTextFillElement
             ? backgroundLayers.map((layer, index) => {
                 const gradient = parseGradientLayer(layer);
-                // Hidden state lives in the real, persisted backgroundSize
-                // marker (see withLayerSizeMarker) rather than React state,
-                // so it survives deselect/reselect. Opacity still reflects
-                // the gradient's own stop opacities for display, but no
-                // longer drives hide/show — a layer can be a fully-opaque
-                // gradient and still be hidden via zero-size.
+                // Hidden state itself lives in the real, persisted
+                // backgroundSize marker (see withLayerSizeMarker) rather than
+                // React state, so it survives deselect/reselect. Opacity
+                // still reflects the gradient's own stop opacities for
+                // display, but no longer drives hide/show — a layer can be a
+                // fully-opaque gradient and still be hidden via zero-size.
+                // The layer's *original* size (a custom cover/contain/
+                // percentage) can't be recovered from the marker itself once
+                // overwritten, so it's separately stashed in component state
+                // for the round trip (see hiddenFillSizeStash below) —
+                // same pattern as effects-properties.tsx's hiddenEffectStash
+                // for hidden shadow/blur effects.
                 const hidden = isLayerHiddenBySize(backgroundSizeLayers[index]);
                 const opacity = gradient
                   ? averageGradientOpacity(gradient.stops)
@@ -463,14 +494,47 @@ export function FillProperties({
                     onStyleChange(property, value),
                   );
                 };
+                const sizeStashKey = `${fillStashKey}:fill-size:${index}`;
                 const setLayerHidden = (nextHidden: boolean) => {
+                  if (nextHidden) {
+                    // Stash the real pre-hide size (a custom cover/contain/
+                    // percentage — see withLayerSizeMarker) so re-showing
+                    // can restore it instead of permanently discarding it
+                    // for "auto". Skip stashing if the layer is somehow
+                    // already hidden (nothing real to preserve).
+                    const current = backgroundSizeLayers[index];
+                    if (current && !isLayerHiddenBySize(current)) {
+                      setHiddenFillSizeStash((prev) => ({
+                        ...prev,
+                        [sizeStashKey]: current,
+                      }));
+                    }
+                    onStyleChange(
+                      "backgroundSize",
+                      withLayerSizeMarker(
+                        backgroundSizeLayers,
+                        backgroundLayers.length,
+                        index,
+                        true,
+                      ),
+                    );
+                    return;
+                  }
+
+                  const restored = hiddenFillSizeStash[sizeStashKey];
+                  setHiddenFillSizeStash((prev) => {
+                    const next = { ...prev };
+                    delete next[sizeStashKey];
+                    return next;
+                  });
                   onStyleChange(
                     "backgroundSize",
                     withLayerSizeMarker(
                       backgroundSizeLayers,
                       backgroundLayers.length,
                       index,
-                      nextHidden,
+                      false,
+                      restored,
                     ),
                   );
                 };
@@ -536,6 +600,35 @@ export function FillProperties({
                               ),
                             );
                           }}
+                          // Editing an existing image layer's URL/fit
+                          // through its own row popover previously had no
+                          // `onImageFillChange` wired at all, so it fell
+                          // through to `emitPaintValue(imageFillToCss(...))`
+                          // — a single-property `background` SHORTHAND
+                          // string (e.g. `url(...) center / cover no-repeat`)
+                          // written into `backgroundImage` alone, which is
+                          // invalid CSS for that longhand and left
+                          // backgroundSize/backgroundRepeat/backgroundPosition
+                          // untouched. Merge into this layer's own index
+                          // across all four parallel arrays instead (same
+                          // helper the base-row fix uses — see
+                          // `imageFillChangePatch` in panel-primitives.tsx).
+                          onImageFillChange={(value) =>
+                            commitStylePatch(
+                              setImageFillLayerPatch(
+                                {
+                                  backgroundImage: backgroundLayers,
+                                  backgroundSize: backgroundSizeLayers,
+                                  backgroundRepeat: backgroundRepeatLayers,
+                                  backgroundPosition: backgroundPositionLayers,
+                                },
+                                index,
+                                imageFillToBackgroundStyles(value),
+                              ),
+                              onStyleChange,
+                              onStylesChange,
+                            )
+                          }
                           paintType={gradient?.type ?? "image"}
                           backgroundImage={layer}
                           backgroundSize={backgroundSizeLayers[index]}
diff --git a/templates/design/app/components/design/edit-panel/inspector-controls.spec.ts b/templates/design/app/components/design/edit-panel/inspector-controls.spec.ts
new file mode 100644
index 0000000000..22063e082c
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/inspector-controls.spec.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import { nextRowDragOverIndex, resolveRowDrop } from "./inspector-controls";
+
+// ---------------------------------------------------------------------------
+// nextRowDragOverIndex — drop-indicator target row for a dragover event.
+// ---------------------------------------------------------------------------
+
+describe("nextRowDragOverIndex", () => {
+  it("reports the hovered row when it differs from the dragged row", () => {
+    expect(nextRowDragOverIndex(2, 0)).toBe(2);
+    expect(nextRowDragOverIndex(0, 2)).toBe(0);
+  });
+
+  it("clears the indicator (null) when hovering back over the dragged row itself", () => {
+    // Regression guard: this used to echo back `hoverIndex` unconditionally,
+    // which meant re-entering the source row mid-drag rendered a stray
+    // "before" drop-indicator line on the very row being dragged (dropping
+    // there is always a no-op per resolveRowDrop).
+    expect(nextRowDragOverIndex(1, 1)).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveRowDrop — from/to validation at drop time. Both directions
+// (dragging a row down past later rows, and up past earlier rows) must
+// resolve to the same {from,to} pair the caller's array-splice logic
+// expects; also guards against a stale `from` once the live array has
+// shrunk mid-drag.
+// ---------------------------------------------------------------------------
+
+describe("resolveRowDrop", () => {
+  it("resolves a downward drag (from < to)", () => {
+    expect(resolveRowDrop(0, 2, 4)).toEqual({ from: 0, to: 2 });
+  });
+
+  it("resolves an upward drag (from > to)", () => {
+    expect(resolveRowDrop(3, 1, 4)).toEqual({ from: 3, to: 1 });
+  });
+
+  it("is a no-op when dropped on the same row it started from", () => {
+    expect(resolveRowDrop(2, 2, 4)).toBeNull();
+  });
+
+  it("is a no-op when there is no active drag", () => {
+    expect(resolveRowDrop(null, 2, 4)).toBeNull();
+  });
+
+  it("rejects a `to` that is out of range against the live count", () => {
+    expect(resolveRowDrop(0, 5, 4)).toBeNull();
+    expect(resolveRowDrop(0, -1, 4)).toBeNull();
+  });
+
+  it("rejects a stale `from` that is out of range against the live count", () => {
+    // Regression guard: the underlying array can shrink mid-drag (e.g. an
+    // external update removes rows while the pointer is still down). The
+    // drop handler used to only re-validate `to` against the live count,
+    // letting a `from` captured at drag-start (before the shrink) reach the
+    // caller's onReorder out of bounds.
+    expect(resolveRowDrop(4, 1, 3)).toBeNull();
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/inspector-controls.tsx b/templates/design/app/components/design/edit-panel/inspector-controls.tsx
index 84d64ef9b4..95e4dc375b 100644
--- a/templates/design/app/components/design/edit-panel/inspector-controls.tsx
+++ b/templates/design/app/components/design/edit-panel/inspector-controls.tsx
@@ -103,6 +103,46 @@ export function SectionIconToggle({
   );
 }
 
+/**
+ * Compute the next `overIndex` for a dragover event on `hoverIndex`, given the
+ * index of the row currently being dragged. Hovering back over the dragged
+ * row itself has no meaningful drop position (dropping there is always a
+ * no-op — see `resolveRowDrop`), so this returns `null` to clear the
+ * indicator rather than echoing back `hoverIndex`, which would otherwise
+ * render a stray "before" drop-indicator line on the dragged row itself.
+ *
+ * Pure — exported for tests.
+ */
+export function nextRowDragOverIndex(
+  hoverIndex: number,
+  dragIndex: number,
+): number | null {
+  return hoverIndex === dragIndex ? null : hoverIndex;
+}
+
+/**
+ * Resolve a drop into a `{ from, to }` pair, or `null` for a no-op drop.
+ *
+ * Both `from` (the row that started the drag) and `to` (the row dropped on)
+ * are re-validated against `count` — the CURRENT live row count at drop time
+ * — rather than trusted from the drag-start snapshot. The underlying array
+ * can shrink mid-drag (e.g. an external update removes rows while the
+ * pointer is still down); re-checking only `to` and not `from` would let a
+ * stale drag-start index (captured before the shrink) reach the caller's
+ * `onReorder` out of bounds.
+ *
+ * Pure — exported for tests.
+ */
+export function resolveRowDrop(
+  from: number | null,
+  to: number,
+  count: number,
+): { from: number; to: number } | null {
+  if (from == null || from === to) return null;
+  if (from < 0 || from >= count || to < 0 || to >= count) return null;
+  return { from, to };
+}
+
 /**
  * Minimal pointer-based reorder for a flat row list (fill layers, shadow
  * layers). Deliberately not shared with LayersPanel.tsx's tree-drag logic —
@@ -127,17 +167,17 @@ export function useRowDragReorder(
       if (dragIndex == null) return;
       event.preventDefault();
       event.dataTransfer.dropEffect = "move";
-      if (index !== overIndex) setOverIndex(index);
+      const next = nextRowDragOverIndex(index, dragIndex);
+      if (next !== overIndex) setOverIndex(next);
     },
     onDrop: (event: DragEvent<HTMLDivElement>) => {
       event.preventDefault();
       const from = dragIndex;
       setDragIndex(null);
       setOverIndex(null);
-      if (from == null || from === index) return;
-      const { count: liveCount, onReorder: liveOnReorder } = liveRef.current;
-      if (index < 0 || index >= liveCount) return;
-      liveOnReorder(from, index);
+      const resolved = resolveRowDrop(from, index, liveRef.current.count);
+      if (!resolved) return;
+      liveRef.current.onReorder(resolved.from, resolved.to);
     },
   });
 
diff --git a/templates/design/app/components/design/edit-panel/interaction-state-helpers.spec.ts b/templates/design/app/components/design/edit-panel/interaction-state-helpers.spec.ts
new file mode 100644
index 0000000000..27317a3ed6
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/interaction-state-helpers.spec.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+
+import type { ElementInfo } from "../types";
+import {
+  authoredStyleValue,
+  resolveInteractionStateValue,
+} from "./interaction-state-helpers";
+
+function makeElement(overrides: Partial<ElementInfo> = {}): ElementInfo {
+  return {
+    tagName: "div",
+    classes: [],
+    computedStyles: {},
+    boundingRect: { x: 0, y: 0, width: 100, height: 40 },
+    isFlexChild: false,
+    isFlexContainer: false,
+    ...overrides,
+  };
+}
+
+describe("authoredStyleValue", () => {
+  it("prefers inlineStyles over computedStyles", () => {
+    const element = makeElement({
+      computedStyles: { color: "red" },
+      inlineStyles: { color: "blue" },
+    });
+    expect(authoredStyleValue(element, "color")).toBe("blue");
+  });
+
+  it("treats an authored 'auto' inline value as unset (empty string)", () => {
+    const element = makeElement({ inlineStyles: { left: "auto" } });
+    expect(authoredStyleValue(element, "left")).toBe("");
+  });
+
+  it("falls back to computedStyles when no inline value exists for the property", () => {
+    const element = makeElement({ computedStyles: { top: "12px" } });
+    expect(authoredStyleValue(element, "top")).toBe("12px");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveInteractionStateValue — fallback-to-base, precedence, and property
+// name normalization (stored state declarations are always kebab-case per
+// shared/interaction-states.ts's normalizeCssPropertyName, so this must
+// resolve a camelCase caller property to its kebab-case stored key).
+// ---------------------------------------------------------------------------
+
+describe("resolveInteractionStateValue", () => {
+  it("returns the base value when no state is active (stateStyles undefined)", () => {
+    expect(resolveInteractionStateValue(undefined, "color", "black")).toBe(
+      "black",
+    );
+  });
+
+  it("falls back to the base value when the active state has no override for this property", () => {
+    const stateStyles = { "background-color": "#111827" };
+    expect(resolveInteractionStateValue(stateStyles, "color", "black")).toBe(
+      "black",
+    );
+  });
+
+  it("returns the state's override instead of the base value when one exists (specific state wins over base — not reversed)", () => {
+    const stateStyles = { color: "white" };
+    expect(resolveInteractionStateValue(stateStyles, "color", "black")).toBe(
+      "white",
+    );
+  });
+
+  it("looks up a camelCase property against the kebab-case stored key", () => {
+    const stateStyles = { "background-color": "#111827" };
+    expect(
+      resolveInteractionStateValue(stateStyles, "backgroundColor", "white"),
+    ).toBe("#111827");
+  });
+
+  it("looks up a property that is already kebab-case directly", () => {
+    const stateStyles = { "background-color": "#111827" };
+    expect(
+      resolveInteractionStateValue(stateStyles, "background-color", "white"),
+    ).toBe("#111827");
+  });
+
+  it("treats an explicit empty-string override as a real override, not as missing", () => {
+    const stateStyles = { color: "" };
+    expect(resolveInteractionStateValue(stateStyles, "color", "black")).toBe(
+      "",
+    );
+  });
+
+  it("does not leak a base-state edit into an existing override, or vice versa (independent objects)", () => {
+    const base = { color: "black" };
+    const hoverOverride = { ...base, color: "white" };
+    // Editing the base object after deriving the hover override must not
+    // change the already-resolved hover value (proves no shared reference).
+    base.color = "green";
+    expect(
+      resolveInteractionStateValue(hoverOverride, "color", base.color),
+    ).toBe("white");
+    // And the reverse: mutating the override object must not retroactively
+    // change what the base value was captured as.
+    hoverOverride.color = "purple";
+    expect(base.color).toBe("green");
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/layout-properties.interaction.test.tsx b/templates/design/app/components/design/edit-panel/layout-properties.interaction.test.tsx
new file mode 100644
index 0000000000..bc461e500b
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/layout-properties.interaction.test.tsx
@@ -0,0 +1,138 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@agent-native/core/client", () => ({
+  cn: (...inputs: Array<string | false | null | undefined>) =>
+    inputs.filter(Boolean).join(" "),
+  useT: () => (key: string) => key,
+}));
+
+vi.mock("@/components/ui/tooltip", () => ({
+  Tooltip: ({ children }: { children?: unknown }) => children as never,
+  TooltipTrigger: ({ children }: { children?: unknown }) => children as never,
+  TooltipContent: ({ children }: { children?: unknown }) => children as never,
+  TooltipProvider: ({ children }: { children?: unknown }) => children as never,
+}));
+
+import type { ElementInfo } from "../types";
+import { LayoutContextProperties } from "./layout-properties";
+
+describe("LayoutContextProperties interactions", () => {
+  it("commits Grid atomically while preserving authored custom tracks", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const root = createRoot(container);
+    const onStyleChange = vi.fn();
+    const onStylesChange = vi.fn();
+    const customColumns = "96px 1fr minmax(80px, 2fr)";
+    const customRows = "repeat(2, max-content)";
+    const element = {
+      tagName: "div",
+      classes: [],
+      computedStyles: {
+        display: "grid",
+        gridTemplateColumns: "96px 180px 180px",
+        gridTemplateRows: "24px 24px",
+        gridAutoFlow: "row",
+        columnGap: "12px",
+        rowGap: "8px",
+        width: "480px",
+        height: "100px",
+      },
+      inlineStyles: {
+        gridTemplateColumns: customColumns,
+        gridTemplateRows: customRows,
+        gridAutoFlow: "row",
+      },
+      boundingRect: { x: 0, y: 0, width: 480, height: 100 },
+      isFlexChild: false,
+      isFlexContainer: false,
+      isGridContainer: true,
+      childElementCount: 4,
+      sourceId: "grid-1",
+    } as ElementInfo;
+
+    await act(async () => {
+      root.render(
+        <LayoutContextProperties
+          element={element}
+          onStyleChange={onStyleChange}
+          onStylesChange={onStylesChange}
+        />,
+      );
+    });
+
+    const gridButton = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Grid"]',
+    );
+    expect(gridButton?.getAttribute("aria-pressed")).toBe("true");
+    await act(async () => gridButton?.click());
+    expect(onStylesChange).toHaveBeenCalledOnce();
+    expect(onStylesChange).toHaveBeenCalledWith({
+      display: "grid",
+      gridTemplateColumns: customColumns,
+      gridTemplateRows: customRows,
+      gridAutoFlow: "row",
+    });
+    expect(onStyleChange).not.toHaveBeenCalled();
+
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  it("links asymmetric padding without mutating or averaging authored values", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const root = createRoot(container);
+    const onStyleChange = vi.fn();
+    const onStylesChange = vi.fn();
+    const element = {
+      tagName: "div",
+      classes: [],
+      computedStyles: {
+        display: "flex",
+        flexDirection: "row",
+        flexWrap: "nowrap",
+        width: "200px",
+        height: "100px",
+        paddingTop: "4px",
+        paddingRight: "8px",
+        paddingBottom: "12px",
+        paddingLeft: "16px",
+      },
+      boundingRect: { x: 0, y: 0, width: 200, height: 100 },
+      isFlexChild: false,
+      isFlexContainer: true,
+      childElementCount: 1,
+      sourceId: "frame-1",
+    } as ElementInfo;
+
+    await act(async () => {
+      root.render(
+        <LayoutContextProperties
+          element={element}
+          onStyleChange={onStyleChange}
+          onStylesChange={onStylesChange}
+        />,
+      );
+    });
+
+    const linkButton = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Link padding"]',
+    );
+    expect(linkButton).not.toBeNull();
+    await act(async () => linkButton?.click());
+
+    expect(onStyleChange).not.toHaveBeenCalled();
+    expect(onStylesChange).not.toHaveBeenCalled();
+    expect(
+      container.querySelector('button[aria-label="Unlink padding"]'),
+    ).not.toBeNull();
+
+    await act(async () => root.unmount());
+    container.remove();
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/layout-properties.test.tsx b/templates/design/app/components/design/edit-panel/layout-properties.test.tsx
new file mode 100644
index 0000000000..458da632cb
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/layout-properties.test.tsx
@@ -0,0 +1,195 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+
+import type { ElementInfo } from "../types";
+import {
+  autoLayoutStylesForFlow,
+  gridTemplateForTracks,
+  gridValueForElement,
+  justifyContentForGapMode,
+  LayoutContextProperties,
+  parseGridTemplate,
+} from "./layout-properties";
+
+vi.mock("@agent-native/core/client", () => ({
+  cn: (...inputs: Array<string | false | null | undefined>) =>
+    inputs.filter(Boolean).join(" "),
+  useT: () => (key: string) => key,
+}));
+
+vi.mock("@/components/ui/tooltip", () => ({
+  Tooltip: ({ children }: { children?: unknown }) => children as never,
+  TooltipTrigger: ({ children }: { children?: unknown }) => children as never,
+  TooltipContent: ({ children }: { children?: unknown }) => children as never,
+  TooltipProvider: ({ children }: { children?: unknown }) => children as never,
+}));
+
+function element(overrides: Partial<ElementInfo>): ElementInfo {
+  return {
+    tagName: "div",
+    classes: [],
+    computedStyles: {
+      display: "block",
+      width: "120px",
+      height: "80px",
+    },
+    boundingRect: { x: 0, y: 0, width: 120, height: 80 },
+    isFlexChild: false,
+    isFlexContainer: false,
+    childElementCount: 0,
+    ...overrides,
+  } as ElementInfo;
+}
+
+describe("LayoutContextProperties", () => {
+  it("maps each Flow choice to one complete atomic style patch", () => {
+    expect(autoLayoutStylesForFlow("normal")).toEqual({ display: "block" });
+    expect(autoLayoutStylesForFlow("vertical")).toEqual({
+      display: "flex",
+      flexDirection: "column",
+      flexWrap: "nowrap",
+    });
+    expect(autoLayoutStylesForFlow("horizontal")).toEqual({
+      display: "flex",
+      flexDirection: "row",
+      flexWrap: "nowrap",
+    });
+    expect(autoLayoutStylesForFlow("grid")).toEqual({
+      display: "grid",
+      gridTemplateColumns: "repeat(2, minmax(0, 1fr))",
+      gridTemplateRows: "repeat(1, max-content)",
+      gridAutoFlow: "row",
+    });
+  });
+
+  it("detects real grid tracks without rewriting authored custom templates", () => {
+    expect(parseGridTemplate("repeat(3, minmax(0, 1fr))")).toEqual({
+      count: 3,
+      sizing: "fill",
+    });
+    expect(parseGridTemplate("96px 1fr minmax(80px, 2fr)")).toEqual({
+      count: 3,
+      sizing: "custom",
+    });
+    expect(
+      gridTemplateForTracks(
+        3,
+        "custom",
+        undefined,
+        "96px 1fr minmax(80px, 2fr)",
+      ),
+    ).toBe("96px 1fr minmax(80px, 2fr)");
+
+    const grid = gridValueForElement(
+      element({
+        isGridContainer: true,
+        inlineStyles: {
+          gridTemplateColumns: "96px 1fr minmax(80px, 2fr)",
+          gridTemplateRows: "repeat(2, max-content)",
+        },
+        computedStyles: {
+          display: "grid",
+          gridTemplateColumns: "96px 180px 180px",
+          gridTemplateRows: "24px 24px",
+          columnGap: "12px",
+          rowGap: "8px",
+          width: "480px",
+          height: "80px",
+        },
+      }),
+    );
+    expect(grid).toMatchObject({
+      columns: 3,
+      columnSizing: "custom",
+      columnTemplate: "96px 1fr minmax(80px, 2fr)",
+      rows: 2,
+      rowSizing: "hug",
+      columnGap: 12,
+      rowGap: 8,
+    });
+  });
+
+  it("shows Flow and Padding for an empty rectangle so auto layout can be enabled before nesting", () => {
+    const markup = renderToStaticMarkup(
+      createElement(LayoutContextProperties, {
+        element: element({
+          primitiveKind: "rectangle",
+          sourceId: "draft-rect-1",
+        }),
+        onStyleChange: vi.fn(),
+      }),
+    );
+
+    expect(markup).toContain("editPanel.sections.autoLayout");
+    expect(markup).toContain("Flow");
+    expect(markup).toContain("Normal flow");
+    expect(markup).toContain("Padding");
+    expect(markup).toContain("Clip content");
+  });
+
+  it("maps gap-mode Auto to space-between and restores the last packed alignment on Fixed", () => {
+    // Auto gap mode IS justify-content:space-between. Switching back to
+    // Fixed must restore whatever packed (start/center/end) alignment was
+    // in effect before Auto was turned on, not hard-reset to flex-start —
+    // see the lastPackedJustifyRef comment in FlexContainerControls.
+    expect(justifyContentForGapMode("auto", "center")).toBe("space-between");
+    expect(justifyContentForGapMode("fixed", "center")).toBe("center");
+    expect(justifyContentForGapMode("fixed", "flex-end")).toBe("flex-end");
+  });
+
+  it("shows ordinary sizing rather than auto-layout controls for a flex-backed text primitive", () => {
+    const markup = renderToStaticMarkup(
+      createElement(LayoutContextProperties, {
+        element: element({
+          primitiveKind: "text",
+          sourceId: "draft-text-1",
+          isFlexContainer: true,
+          textContent: "Label",
+          computedStyles: {
+            display: "flex",
+            width: "120px",
+            height: "24px",
+          },
+          boundingRect: { x: 0, y: 0, width: 120, height: 24 },
+        }),
+        onStyleChange: vi.fn(),
+      }),
+    );
+
+    expect(markup).toContain("editPanel.sections.layout");
+    expect(markup).not.toContain("editPanel.sections.autoLayout");
+    expect(markup).not.toContain("Normal flow");
+  });
+
+  it("passes a mixed container flow through as Mixed instead of normal flow", () => {
+    const markup = renderToStaticMarkup(
+      createElement(LayoutContextProperties, {
+        element: element({
+          tagName: "div",
+          computedStyles: {
+            display: "Mixed",
+            flexDirection: "Mixed",
+            flexWrap: "Mixed",
+            justifyContent: "Mixed",
+            alignItems: "Mixed",
+            overflow: "Mixed",
+            width: "120px",
+            height: "80px",
+          },
+        }),
+        onStyleChange: vi.fn(),
+      }),
+    );
+
+    expect(markup).toContain('data-flow-value="mixed"');
+    expect(markup).toContain("Mixed");
+    expect(markup).toContain('aria-label="Normal flow" aria-pressed="false"');
+    expect(markup).toContain('aria-label="Vertical" aria-pressed="false"');
+    expect(markup).toContain('aria-label="Horizontal" aria-pressed="false"');
+    expect(markup).toContain('aria-label="Grid" aria-pressed="false"');
+    expect(markup).toContain("Gap mode: Mixed");
+    expect(markup).toContain('aria-checked="mixed"');
+    expect(markup).toContain('aria-label="top left" aria-pressed="false"');
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/layout-properties.tsx b/templates/design/app/components/design/edit-panel/layout-properties.tsx
index e255eb4a7b..2833c0d28d 100644
--- a/templates/design/app/components/design/edit-panel/layout-properties.tsx
+++ b/templates/design/app/components/design/edit-panel/layout-properties.tsx
@@ -6,7 +6,7 @@ import {
   IconMinus,
   IconPlus,
 } from "@tabler/icons-react";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 
 import {
   Tooltip,
@@ -19,6 +19,9 @@ import {
   AutoLayoutMatrix,
   ScrubInput,
   SizingField,
+  type AutoLayoutFlow,
+  type AutoLayoutGridTrackSizing,
+  type AutoLayoutGridValue,
   type AutoLayoutMatrixValue,
   type ScrubInputChangeMeta,
 } from "../inspector";
@@ -29,7 +32,6 @@ import {
   commitElementMinMax,
   commitElementSizing,
   cssElementSize,
-  elementHasLayoutChildren,
   horizontalToJustify,
   inferElementSizing,
   isContainerElement,
@@ -40,7 +42,7 @@ import {
 } from "./element-classification";
 import {
   deriveLockedAspectSize,
-  elementIdentityKey,
+  elementStableKey,
   useAspectRatioLock,
 } from "./element-identity";
 import { FieldTrailer, ScrubStyleInput } from "./field-primitives";
@@ -66,6 +68,146 @@ import {
   parseNumericValue,
 } from "./style-options";
 
+/**
+ * The `justifyContent` to write when the primary-axis gap-mode toggle
+ * changes. "Auto" gap mode IS `justify-content: space-between` (see
+ * `spaceBetween` on `AutoLayoutMatrixValue`); switching back to "Fixed"
+ * should restore whichever packed alignment (flex-start/center/flex-end) was
+ * in effect before "Auto" was turned on, not hard-reset to flex-start —
+ * mirrors Figma, where turning off "Space between" returns to the
+ * previously chosen start/center/end packing instead of silently
+ * re-aligning everything to the start. `lastPackedJustify` is the caller's
+ * best-known non-"space-between" `justifyContent` (see
+ * `lastPackedJustifyRef` at the call site). Exported for tests.
+ */
+export function justifyContentForGapMode(
+  gapMode: "auto" | "fixed",
+  lastPackedJustify: string,
+): string {
+  return gapMode === "auto" ? "space-between" : lastPackedJustify;
+}
+
+export function autoLayoutStylesForFlow(
+  flow: AutoLayoutFlow,
+  currentStyles: Record<string, string> = {},
+): Record<string, string> {
+  if (flow === "normal") return { display: "block" };
+  if (flow === "vertical") {
+    return { display: "flex", flexDirection: "column", flexWrap: "nowrap" };
+  }
+  if (flow === "grid") {
+    const authoredColumns = currentStyles.gridTemplateColumns;
+    const authoredRows = currentStyles.gridTemplateRows;
+    return {
+      display: "grid",
+      gridTemplateColumns:
+        authoredColumns && authoredColumns !== "none"
+          ? authoredColumns
+          : "repeat(2, minmax(0, 1fr))",
+      gridTemplateRows:
+        authoredRows && authoredRows !== "none"
+          ? authoredRows
+          : "repeat(1, max-content)",
+      gridAutoFlow: currentStyles.gridAutoFlow || "row",
+    };
+  }
+  return { display: "flex", flexDirection: "row", flexWrap: "nowrap" };
+}
+
+function splitGridTracks(template: string): string[] {
+  const tracks: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < template.length; index += 1) {
+    const character = template[index];
+    if (character === "(") depth += 1;
+    if (character === ")") depth = Math.max(0, depth - 1);
+    if (/\s/.test(character) && depth === 0) {
+      const track = template.slice(start, index).trim();
+      if (track) tracks.push(track);
+      start = index + 1;
+    }
+  }
+  const last = template.slice(start).trim();
+  if (last) tracks.push(last);
+  return tracks;
+}
+
+/** Parse the common uniform grid forms while preserving arbitrary authored CSS. */
+export function parseGridTemplate(template: string): {
+  count: number;
+  sizing: AutoLayoutGridTrackSizing;
+  fixedSize?: number;
+} {
+  const normalized = template.trim();
+  const repeat = normalized.match(/^repeat\(\s*(\d+)\s*,\s*(.+)\)$/i);
+  const count = repeat
+    ? Math.max(1, Number.parseInt(repeat[1], 10))
+    : Math.max(1, splitGridTracks(normalized).length);
+  const tracks = repeat ? [repeat[2].trim()] : splitGridTracks(normalized);
+  const first = tracks[0] || "";
+  const uniform = tracks.every((track) => track === first);
+  if (!uniform) return { count, sizing: "custom" };
+  if (/^(?:minmax\(\s*0(?:px)?\s*,\s*)?1fr\)?$/i.test(first)) {
+    return { count, sizing: "fill" };
+  }
+  if (/^(?:max-content|min-content|auto)$/i.test(first)) {
+    return { count, sizing: "hug" };
+  }
+  const fixed = first.match(/^(-?\d+(?:\.\d+)?)px$/i);
+  if (fixed) {
+    return { count, sizing: "fixed", fixedSize: Number(fixed[1]) };
+  }
+  return { count, sizing: "custom" };
+}
+
+export function gridTemplateForTracks(
+  count: number,
+  sizing: AutoLayoutGridTrackSizing,
+  fixedSize: number | undefined,
+  authoredTemplate: string | undefined,
+): string {
+  const safeCount = Math.max(1, Math.round(count));
+  if (sizing === "custom" && authoredTemplate) return authoredTemplate;
+  if (sizing === "hug") return `repeat(${safeCount}, max-content)`;
+  if (sizing === "fixed") {
+    return `repeat(${safeCount}, ${Math.max(0, fixedSize ?? 100)}px)`;
+  }
+  return `repeat(${safeCount}, minmax(0, 1fr))`;
+}
+
+function authoredGridTemplate(
+  element: ElementInfo,
+  property: "gridTemplateColumns" | "gridTemplateRows",
+): string {
+  return (
+    element.inlineStyles?.[property] || element.computedStyles[property] || ""
+  );
+}
+
+export function gridValueForElement(element: ElementInfo): AutoLayoutGridValue {
+  const columnsTemplate = authoredGridTemplate(element, "gridTemplateColumns");
+  const rowsTemplate = authoredGridTemplate(element, "gridTemplateRows");
+  const columns = parseGridTemplate(columnsTemplate);
+  const rows = parseGridTemplate(rowsTemplate);
+  return {
+    columns: columns.count,
+    rows: rows.count,
+    columnSizing: columns.sizing,
+    rowSizing: rows.sizing,
+    columnSize: columns.fixedSize,
+    rowSize: rows.fixedSize,
+    columnTemplate: columnsTemplate,
+    rowTemplate: rowsTemplate,
+    columnGap: parseNumericValue(element.computedStyles.columnGap || "0"),
+    rowGap: parseNumericValue(element.computedStyles.rowGap || "0"),
+    columnsMixed: isMixedValue(columnsTemplate),
+    rowsMixed: isMixedValue(rowsTemplate),
+    columnGapMixed: isMixedValue(element.computedStyles.columnGap),
+    rowGapMixed: isMixedValue(element.computedStyles.rowGap),
+  };
+}
+
 /** Flex container properties */
 function FlexContainerControls({
   element,
@@ -84,13 +226,41 @@ function FlexContainerControls({
   // control can show the right state (normal vs horizontal/vertical/wrap)
   // instead of an empty "add" affordance.
   const display = (styles.display || "").toLowerCase();
+  const isGrid = element.isGridContainer || display.includes("grid");
   const isFlex = element.isFlexContainer || display.includes("flex");
-  const displayMode: AutoLayoutMatrixValue["display"] = isFlex
-    ? "flex"
-    : "block";
-  const hasLayoutChildren = elementHasLayoutChildren(element);
+  const displayMode: AutoLayoutMatrixValue["display"] = isGrid
+    ? "grid"
+    : isFlex
+      ? "flex"
+      : "block";
+  const flowMixed = [
+    styles.display,
+    styles.flexDirection,
+    styles.flexWrap,
+    styles.gridTemplateColumns,
+    styles.gridTemplateRows,
+  ].some(isMixedValue);
   const flexDirection: AutoLayoutMatrixValue["direction"] =
     styles.flexDirection?.includes("column") ? "vertical" : "horizontal";
+  // `justifyContent` is always the main-axis property in flexbox regardless
+  // of direction, so it doubles as the "packed" (start/center/end) main-axis
+  // alignment AND the gap-mode signal ("space-between" = Auto gap, see
+  // `spaceBetween` below). Remember the last non-"space-between" value here
+  // so turning gap mode back to Fixed can restore the user's chosen packed
+  // alignment (see onGapModeChange) instead of hard-resetting to flex-start
+  // — mirrors Figma, where switching a container's primary-axis distribution
+  // away from "Space between" returns to whichever start/center/end packing
+  // was previously selected.
+  const lastPackedJustifyRef = useRef(
+    styles.justifyContent && styles.justifyContent !== "space-between"
+      ? styles.justifyContent
+      : "flex-start",
+  );
+  useEffect(() => {
+    if (styles.justifyContent && styles.justifyContent !== "space-between") {
+      lastPackedJustifyRef.current = styles.justifyContent;
+    }
+  }, [styles.justifyContent]);
   const mainGapAxis =
     flexDirection === "horizontal" ? "horizontal" : "vertical";
   // When the element is in normal flow (not flex yet), picking any flow option
@@ -107,7 +277,11 @@ function FlexContainerControls({
    * For 'block': sets display:block and leaves children unchanged — mirrors
    * the { kind:"autoLayout", enabled:false } substrate intent exactly.
    */
-  const handleDisplayChange = (nextDisplay: "flex" | "block") => {
+  const handleDisplayChange = (nextDisplay: "flex" | "grid" | "block") => {
+    if (nextDisplay === "grid") {
+      onStyleChange("display", "grid");
+      return;
+    }
     if (nextDisplay === "flex") {
       ensureFlex();
       return;
@@ -144,9 +318,30 @@ function FlexContainerControls({
   const autoLayoutValue: AutoLayoutMatrixValue = {
     direction: flexDirection,
     wrap: styles.flexWrap === "wrap" ? "wrap" : "nowrap",
-    alignment: autoLayoutAlignmentFromStyles(styles, flexDirection),
+    alignment: autoLayoutAlignmentFromStyles(
+      isGrid ? { ...styles, justifyContent: styles.justifyItems } : styles,
+      isGrid ? "horizontal" : flexDirection,
+    ),
+    alignmentMixed: [
+      styles.justifyContent,
+      styles.alignItems,
+      styles.alignContent,
+      ...(isGrid ? [styles.justifyItems] : []),
+    ].some(isMixedValue),
     gap: parseNumericValue(styles.gap || "0"),
+    // Multi-selections with differing gap/padding surface the MIXED_VALUE
+    // sentinel here; parseNumericValue would silently coerce it to 0 (a
+    // real-looking value that would clobber every element on edit), so flag
+    // each field so AutoLayoutMatrix renders a "Mixed" placeholder instead.
+    gapMixed: isMixedValue(styles.gap),
+    gapModeMixed: isMixedValue(styles.justifyContent),
     padding,
+    paddingMixed: {
+      top: isMixedValue(styles.paddingTop),
+      right: isMixedValue(styles.paddingRight),
+      bottom: isMixedValue(styles.paddingBottom),
+      left: isMixedValue(styles.paddingLeft),
+    },
     paddingLinked,
     childSizing: {
       horizontal: inferElementSizing(element, "horizontal"),
@@ -157,6 +352,7 @@ function FlexContainerControls({
       vertical: readElementMinMax(element, "vertical"),
     },
     clipContent: styles.overflow === "hidden",
+    clipContentMixed: isMixedValue(styles.overflow),
     resolvedSize: {
       horizontal: cssElementSize(element, "horizontal"),
       vertical: cssElementSize(element, "vertical"),
@@ -166,13 +362,28 @@ function FlexContainerControls({
       vertical: isMixedValue(styles.height),
     },
     display: displayMode,
+    flowMixed,
     spaceBetween: styles.justifyContent === "space-between",
+    grid: isGrid ? gridValueForElement(element) : undefined,
   };
 
   return (
     <div className="space-y-2">
       <AutoLayoutMatrix
         value={autoLayoutValue}
+        onFlowChange={(flow) => {
+          const patch = autoLayoutStylesForFlow(flow, {
+            ...styles,
+            ...element.inlineStyles,
+          });
+          if (onStylesChange) {
+            onStylesChange(patch);
+            return;
+          }
+          Object.entries(patch).forEach(([property, value]) =>
+            onStyleChange(property, value),
+          );
+        }}
         onDisplayChange={handleDisplayChange}
         onDirectionChange={(direction) => {
           ensureFlex();
@@ -185,7 +396,51 @@ function FlexContainerControls({
           ensureFlex();
           onStyleChange("flexWrap", wrap);
         }}
+        onGridChange={(nextGrid, meta) => {
+          const previousGrid = autoLayoutValue.grid;
+          const columnTemplate = gridTemplateForTracks(
+            nextGrid.columns,
+            nextGrid.columnSizing,
+            nextGrid.columnSize,
+            nextGrid.columnSizing === "custom" &&
+              previousGrid?.columns === nextGrid.columns
+              ? nextGrid.columnTemplate
+              : undefined,
+          );
+          const rowTemplate = gridTemplateForTracks(
+            nextGrid.rows,
+            nextGrid.rowSizing,
+            nextGrid.rowSize,
+            nextGrid.rowSizing === "custom" &&
+              previousGrid?.rows === nextGrid.rows
+              ? nextGrid.rowTemplate
+              : undefined,
+          );
+          const patch = {
+            display: "grid",
+            gridTemplateColumns: columnTemplate,
+            gridTemplateRows: rowTemplate,
+            gridAutoFlow: "row",
+            columnGap: `${nextGrid.columnGap}px`,
+            rowGap: `${nextGrid.rowGap}px`,
+          };
+          if (onStylesChange) {
+            onStylesChange(patch, meta);
+            return;
+          }
+          Object.entries(patch).forEach(([property, value]) =>
+            onStyleChange(property, value, meta),
+          );
+        }}
         onAlignmentChange={(alignment) => {
+          if (displayMode === "grid") {
+            onStyleChange(
+              "justifyItems",
+              horizontalToJustify(alignment.horizontal),
+            );
+            onStyleChange("alignItems", verticalToAlign(alignment.vertical));
+            return;
+          }
           if (autoLayoutValue.direction === "vertical") {
             onStyleChange(
               "alignItems",
@@ -227,31 +482,35 @@ function FlexContainerControls({
         }}
         onPaddingLinkedChange={(linked) => {
           setPaddingLinked(linked);
-          if (!linked) return;
-          const avg = Math.round(
-            (padding.top + padding.right + padding.bottom + padding.left) / 4,
-          );
-          onStyleChange("paddingTop", `${avg}px`);
-          onStyleChange("paddingRight", `${avg}px`);
-          onStyleChange("paddingBottom", `${avg}px`);
-          onStyleChange("paddingLeft", `${avg}px`);
+          // Linking is a display-mode choice, not a style edit. Figma keeps
+          // asymmetric padding intact when the sides are linked and only
+          // equalizes an axis after the user edits that linked field. The old
+          // eager average destroyed all four authored values immediately and
+          // produced four source commits/undo entries just from clicking the
+          // link icon. AutoLayoutMatrix intentionally displays left/top as
+          // each linked axis's representative value and applies both sides on
+          // the next real field edit, so no style write belongs here.
         }}
         onClipContentChange={(clipContent) =>
           onStyleChange("overflow", clipContent ? "hidden" : "visible")
         }
-        onDistribute={(axis) => {
-          if (axis === mainGapAxis) {
-            onStyleChange("justifyContent", "space-between");
-          } else if (autoLayoutValue.wrap === "wrap") {
-            onStyleChange("alignContent", "space-between");
-          }
-        }}
+        onDistribute={
+          displayMode === "grid"
+            ? undefined
+            : (axis) => {
+                if (axis === mainGapAxis) {
+                  onStyleChange("justifyContent", "space-between");
+                } else if (autoLayoutValue.wrap === "wrap") {
+                  onStyleChange("alignContent", "space-between");
+                }
+              }
+        }
         onGapModeChange={(gapMode, axis) => {
           if (axis !== mainGapAxis) return;
           ensureFlex();
           onStyleChange(
             "justifyContent",
-            gapMode === "auto" ? "space-between" : "flex-start",
+            justifyContentForGapMode(gapMode, lastPackedJustifyRef.current),
           );
         }}
         availableChildSizing={availableSizingForElement(element)}
@@ -274,7 +533,12 @@ function FlexContainerControls({
         onChildMinMaxChange={(axis, kind, val, meta) =>
           commitElementMinMax(axis, kind, val, onStyleChange, meta)
         }
-        showChildLayoutControls={hasLayoutChildren}
+        // Empty frames/rectangles still need the complete Flow + Padding
+        // surface: users must be able to turn auto layout on before adding a
+        // first child, just as they can for an empty frame in Figma. The old
+        // child-count gate left an "Auto layout" section containing only
+        // Resizing, with no way to enable auto layout from the inspector.
+        showChildLayoutControls
       />
     </div>
   );
@@ -598,9 +862,16 @@ export function LayoutContextProperties({
           must not silently flip while the user is mid-scrub — see the
           FlexContainerControls comment) resets on selection change instead of
           leaking to the next element — same pattern as CornerRadiusControl /
-          ExportSettingsPanel. */}
+          ExportSettingsPanel. Deliberately `elementStableKey`, NOT
+          `elementIdentityKey`: the latter folds in the rounded bounding rect,
+          which changes on every resize. Resizing a frame on canvas is a very
+          common action while its Auto layout section is open, and remounting
+          on every such tick would silently reset paddingLinked back to
+          allPaddingEqual mid-session — the exact class of bug the comment
+          below (STEVE TEST BATCH 4 #4) already fixed for the *value*-driven
+          case, reintroduced here via the *key*. */}
       <FlexContainerControls
-        key={elementIdentityKey(element)}
+        key={elementStableKey(element)}
         element={element}
         onStyleChange={onStyleChange}
         onStylesChange={onStylesChange}
diff --git a/templates/design/app/components/design/edit-panel/panel-primitives.spec.ts b/templates/design/app/components/design/edit-panel/panel-primitives.spec.ts
new file mode 100644
index 0000000000..a4749a0bad
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/panel-primitives.spec.ts
@@ -0,0 +1,121 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { commitStylePatch, resolveSpacingSideValue } from "./field-primitives";
+import {
+  normalizeLengthValue,
+  propInputKeyRequiresBlurGuard,
+} from "./panel-primitives";
+
+describe("normalizeLengthValue", () => {
+  it("appends the default unit to a bare integer", () => {
+    expect(normalizeLengthValue("32", "px")).toBe("32px");
+  });
+
+  it("appends the default unit to a bare decimal with a leading digit", () => {
+    expect(normalizeLengthValue("32.5", "px")).toBe("32.5px");
+  });
+
+  it("appends the default unit to a leading-decimal value with no integer part", () => {
+    // Regression: "0.5" was accepted but the numerically identical ".5" was
+    // rejected (and the field silently reverted instead of committing
+    // ".5px") because the old regex required a digit before the dot.
+    expect(normalizeLengthValue(".5", "px")).toBe(".5px");
+    expect(normalizeLengthValue("-.5", "px")).toBe("-.5px");
+  });
+
+  it("passes through a value that already carries a unit", () => {
+    expect(normalizeLengthValue("32px", "px")).toBe("32px");
+  });
+
+  it("passes through valid CSS keywords", () => {
+    expect(normalizeLengthValue("auto", "px")).toBe("auto");
+  });
+
+  it("reverts (returns null) for empty input", () => {
+    expect(normalizeLengthValue("   ", "px")).toBeNull();
+  });
+
+  it("reverts (returns null) for garbage input", () => {
+    // This template's vitest environment has no DOM, so `CSS.supports` is
+    // normally unavailable and normalizeLengthValue intentionally falls back
+    // to accepting the raw value (see its own comment). Stub a minimal
+    // CSS.supports so this test exercises the real browser revert path.
+    const originalCss = (globalThis as { CSS?: unknown }).CSS;
+    (globalThis as { CSS?: unknown }).CSS = { supports: () => false };
+    try {
+      expect(normalizeLengthValue("abc", "px")).toBeNull();
+    } finally {
+      (globalThis as { CSS?: unknown }).CSS = originalCss;
+    }
+  });
+
+  it("accepts the raw value when CSS.supports is unavailable (SSR/test fallback)", () => {
+    expect(normalizeLengthValue("abc", "px")).toBe("abc");
+  });
+});
+
+describe("propInputKeyRequiresBlurGuard", () => {
+  it("requires the blur guard for Enter", () => {
+    // Regression: Enter previously didn't arm skipNextBlurCommitRef, so the
+    // blur triggered by Enter's own `.blur()` call re-ran commit() a second
+    // time in the same tick and double-invoked onChange with the identical
+    // value.
+    expect(propInputKeyRequiresBlurGuard("Enter")).toBe(true);
+  });
+
+  it("requires the blur guard for Escape", () => {
+    expect(propInputKeyRequiresBlurGuard("Escape")).toBe(true);
+  });
+
+  it("does not require the blur guard for any other key", () => {
+    expect(propInputKeyRequiresBlurGuard("Tab")).toBe(false);
+    expect(propInputKeyRequiresBlurGuard("a")).toBe(false);
+    expect(propInputKeyRequiresBlurGuard("ArrowLeft")).toBe(false);
+  });
+});
+
+describe("resolveSpacingSideValue", () => {
+  it("preserves one decimal place instead of flooring to a whole pixel", () => {
+    // Regression: DesignSpacingControl's setSide used Math.round, silently
+    // discarding the 0.5px precision the four per-side ScrubInput fields
+    // advertise via precision={1} (every other ScrubInput commit site in
+    // this panel — position X/Y, stroke weight, font size — uses
+    // roundToOneDecimal instead of Math.round).
+    expect(resolveSpacingSideValue(12.5)).toBe("12.5px");
+  });
+
+  it("rounds beyond one decimal place", () => {
+    expect(resolveSpacingSideValue(12.34)).toBe("12.3px");
+    expect(resolveSpacingSideValue(12.36)).toBe("12.4px");
+  });
+
+  it("formats a whole number without a trailing decimal", () => {
+    expect(resolveSpacingSideValue(12)).toBe("12px");
+  });
+
+  it("never emits a signed-zero pixel value", () => {
+    expect(resolveSpacingSideValue(-0.04)).toBe("0px");
+  });
+});
+
+describe("commitStylePatch", () => {
+  it("uses one batch callback and forwards gesture metadata", () => {
+    const single = vi.fn();
+    const batch = vi.fn();
+    const meta = { phase: "commit" as const };
+
+    commitStylePatch(
+      { position: "absolute", left: "24px" },
+      single,
+      batch,
+      meta,
+    );
+
+    expect(batch).toHaveBeenCalledOnce();
+    expect(batch).toHaveBeenCalledWith(
+      { position: "absolute", left: "24px" },
+      meta,
+    );
+    expect(single).not.toHaveBeenCalled();
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/panel-primitives.tsx b/templates/design/app/components/design/edit-panel/panel-primitives.tsx
index f03fa1e325..dc4bfa23b4 100644
--- a/templates/design/app/components/design/edit-panel/panel-primitives.tsx
+++ b/templates/design/app/components/design/edit-panel/panel-primitives.tsx
@@ -19,21 +19,19 @@ import { Slider } from "@/components/ui/slider";
 import type { StyleChangeMeta } from "../EditPanel";
 import {
   DesignColorPicker,
-  type DesignFillRowPatch,
-  type DesignGradientStop,
-  type DesignGradientStopPatch,
+  imageFillToBackgroundStyles,
   type DesignGradientType,
   type ImageFillValue,
 } from "../inspector";
 import type { DesignPaintType } from "../inspector/DesignColorPicker";
 import type { GlslShaderPanelContext } from "../inspector/GlslShaderPanel";
 import {
-  buildFillRows,
   buildGradientLayer,
   defaultGradientLayer,
   defaultGradientStops,
   fillLayerId,
   fillLayerIndex,
+  imageFillChangePatch,
   joinCssLayers,
   parseGradientLayer,
   SOLID_FILL_ID,
@@ -43,13 +41,22 @@ import {
 import { colorHasVisibleAlpha, cssColorOrFallback } from "./position-helpers";
 import { isMixedValue, MIXED_VALUE } from "./selection-helpers";
 
-function normalizeLengthValue(raw: string, defaultUnit: string): string | null {
+export function normalizeLengthValue(
+  raw: string,
+  defaultUnit: string,
+): string | null {
   const trimmed = raw.trim();
   // Empty / invalid input returns null so the caller reverts the field instead
   // of committing an empty or garbage CSS value (e.g. fontSize:"" or
   // flexBasis:"abc") to the element's inline style.
   if (!trimmed) return null;
-  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return `${trimmed}${defaultUnit}`;
+  // Bare numbers get the field's default unit appended. `\d+` alone rejected a
+  // leading-decimal typed value like ".5" (no digit before the dot) even
+  // though "0.5" was accepted — the two are numerically identical, so ".5"
+  // silently reverted the field instead of becoming ".5px". Accept either a
+  // leading-digit form (`5`, `5.5`) or a leading-decimal form (`.5`).
+  if (/^-?(\d+(\.\d+)?|\.\d+)$/.test(trimmed))
+    return `${trimmed}${defaultUnit}`;
   // Validate free-form CSS so junk text never reaches the style. Fall back to
   // accepting the value when CSS.supports is unavailable (SSR/tests) to keep
   // prior behavior in non-DOM environments.
@@ -63,6 +70,21 @@ function normalizeLengthValue(raw: string, defaultUnit: string): string | null {
   return trimmed;
 }
 
+/**
+ * Enter and Escape are the only PropInput keys that manually call `.blur()`
+ * after handling themselves (commit-then-blur for Enter, revert-then-blur for
+ * Escape). Both must pre-arm `skipNextBlurCommitRef` so the onBlur handler —
+ * which fires synchronously inside that manual `.blur()` call, before React
+ * re-renders with the just-committed/-reverted draft — doesn't re-run
+ * commit() a second time against the same stale closure and double-invoke
+ * `onChange` with the identical value. Exported so the contract (which keys
+ * require the guard) is unit-testable without needing to simulate real DOM
+ * focus/blur timing.
+ */
+export function propInputKeyRequiresBlurGuard(key: string): boolean {
+  return key === "Enter" || key === "Escape";
+}
+
 /** Compact input row: label + text input.
  *
  * For CSS length fields (font-size, padding, width, etc.) pass `defaultUnit`
@@ -92,9 +114,24 @@ export function PropInput({
   // Escape reverts and blurs; the blur handler must then skip its commit or it
   // would re-commit the stale draft closure (mirrors ScrubInput's Escape path).
   const skipNextBlurCommitRef = useRef(false);
+  // Tracks focus without becoming a reactive effect dependency: a plain
+  // `focused` state variable in the effect's deps below would re-run the
+  // resync the instant blur sets it false, re-syncing from a `value` prop
+  // that hasn't caught up with the commit that same blur just fired (the
+  // classic "Enter/blur flashes back to the old value" bug — see
+  // ScrubInput's pendingCommitRef comment for the same class of issue). A ref
+  // sidesteps that: the effect only re-runs when `value` itself changes, and
+  // simply consults the current focus state at that point.
+  const focusedRef = useRef(false);
 
   useEffect(() => {
-    setDraft(value);
+    // Skip the resync while the user is actively editing — otherwise an
+    // unrelated re-render that changes this exact `value` prop (e.g. a poll
+    // tick, or another property's edit recomputing this element's styles)
+    // stomps the in-progress keystrokes with the last-committed value. This
+    // is the "you're typing and it snaps back to the old value" bug; mirrors
+    // ScrubInput's `!focused` guard on its own resync effect.
+    if (!focusedRef.current) setDraft(value);
   }, [value]);
 
   const commit = () => {
@@ -120,6 +157,7 @@ export function PropInput({
         type={type}
         value={draft}
         onFocus={(e) => {
+          focusedRef.current = true;
           if (mixed) e.currentTarget.select();
         }}
         onChange={(e) => {
@@ -131,6 +169,7 @@ export function PropInput({
           if (defaultUnit === undefined) onChange(e.target.value);
         }}
         onBlur={() => {
+          focusedRef.current = false;
           if (skipNextBlurCommitRef.current) {
             skipNextBlurCommitRef.current = false;
             return;
@@ -141,6 +180,13 @@ export function PropInput({
           if (e.key === "Enter") {
             e.preventDefault();
             commit();
+            // See propInputKeyRequiresBlurGuard: without this, the blur
+            // triggered below re-enters commit() a second time in the same
+            // synchronous tick, double-invoking onChange with the identical
+            // value.
+            skipNextBlurCommitRef.current = propInputKeyRequiresBlurGuard(
+              e.key,
+            );
             (e.currentTarget as HTMLInputElement).blur();
             return;
           }
@@ -149,7 +195,9 @@ export function PropInput({
             // Revert the draft to the last committed value and blur, matching
             // ScrubInput's Escape behavior.
             setDraft(value);
-            skipNextBlurCommitRef.current = true;
+            skipNextBlurCommitRef.current = propInputKeyRequiresBlurGuard(
+              e.key,
+            );
             (e.currentTarget as HTMLInputElement).blur();
           }
         }}
@@ -171,6 +219,7 @@ export function ColorInput({
   backgroundPosition,
   onBackgroundImageChange,
   onImageFillChange,
+  onImageFillLayerChange,
   blendMode,
   onBlendModeChange,
   supportsLayeredFills = false,
@@ -187,7 +236,34 @@ export function ColorInput({
   backgroundRepeat?: string;
   backgroundPosition?: string;
   onBackgroundImageChange?: (value: string) => void;
+  /**
+   * Single-layer image-fill commit: receives just the edited `{url, fit}`
+   * and leaves building the CSS patch to the caller (via
+   * `imageFillToBackgroundStyles`). Kept for callers that only accept that
+   * shape; prefer `onImageFillLayerChange` below when the caller can commit
+   * an arbitrary multi-property patch, since this single-layer callback has
+   * no way to report which layer changed and therefore always causes the
+   * caller to overwrite the *whole* background stack — silently discarding
+   * any other gradient/image layer stacked alongside it.
+   */
   onImageFillChange?: (value: ImageFillValue) => void;
+  /**
+   * Layer-index-aware sibling of `onImageFillChange`: fires with the full
+   * four-property background patch already merged to preserve every other
+   * stacked gradient/image layer (see `imageFillChangePatch`) — the caller
+   * should commit it as-is (e.g. via `commitStylePatch`), not narrow it back
+   * down to a single-layer write. Takes priority over `onImageFillChange`
+   * when both are provided.
+   */
+  onImageFillLayerChange?: (
+    patch: Record<
+      | "backgroundImage"
+      | "backgroundSize"
+      | "backgroundRepeat"
+      | "backgroundPosition",
+      string
+    >,
+  ) => void;
   blendMode?: string;
   onBlendModeChange?: (value: string) => void;
   supportsLayeredFills?: boolean;
@@ -212,8 +288,18 @@ export function ColorInput({
   const [draft, setDraft] = useState(value);
   const [selectedFillId, setSelectedFillId] = useState(SOLID_FILL_ID);
   const [selectedStopId, setSelectedStopId] = useState<string | undefined>();
+  // Set while a "preview" phase tick has fired but its bracketing "commit"
+  // hasn't landed yet (see setNext below) — i.e. mid drag/scrub gesture in
+  // the popover. Guards the resync effect so an unrelated external `value`
+  // change (e.g. a poll tick, or another property's edit recomputing this
+  // element's styles) can't stomp the optimistic draft this gesture is
+  // driving. Mirrors ScrubInput's pendingCommitRef guard for the same class
+  // of bug, and PropInput's focusedRef guard for the keyboard-typing
+  // equivalent.
+  const pendingGestureRef = useRef(false);
 
   useEffect(() => {
+    if (pendingGestureRef.current) return;
     setDraft(value);
   }, [value]);
 
@@ -283,6 +369,7 @@ export function ColorInput({
     // state. Reject anything that doesn't parse as a plain solid color in
     // that case instead of forwarding it.
     if (!supportsLayeredFills && !parseCssColor(next)) return;
+    pendingGestureRef.current = phase === "preview";
     setDraft(next);
     onChange(next, { phase });
   };
@@ -323,66 +410,31 @@ export function ColorInput({
     setSelectedStopId(gradient?.stops[0]?.id);
   };
 
-  const fillRows = supportsLayeredFills
-    ? buildFillRows(
-        draft || value || "#000000",
-        backgroundLayers,
-        selectedFillId,
-      )
-    : undefined;
-
-  const handleFillChange = (id: string, patch: DesignFillRowPatch) => {
-    if (id === SOLID_FILL_ID) {
-      if (patch.value !== undefined) setNext(patch.value);
-      if (patch.opacity !== undefined) {
-        const parsed = parseCssColor(patch.value ?? draft);
-        if (parsed) setNext(rgbaToCss(withColorOpacity(parsed, patch.opacity)));
-      }
-      return;
-    }
-
-    const index = fillLayerIndex(id);
-    if (index === null || !onBackgroundImageChange) return;
-    const currentLayer = backgroundLayers[index] || "";
-    if (patch.value !== undefined) {
-      replaceBackgroundLayer(index, patch.value);
-      return;
-    }
-    if (patch.opacity === undefined) return;
-    const gradient = parseGradientLayer(currentLayer);
-    if (!gradient) return;
-    replaceBackgroundLayer(
-      index,
-      buildGradientLayer(
-        gradient.type,
-        gradient.stops.map((stop) => ({
-          ...stop,
-          opacity: patch.opacity,
-        })),
-        gradient.prefix,
-      ),
-    );
-  };
-
-  const handleAddFill = onBackgroundImageChange
-    ? () => {
-        const nextLayers = [
-          defaultGradientLayer("linear", draft || value || "#000000"),
-          ...backgroundLayers,
-        ];
-        onBackgroundImageChange(joinCssLayers(nextLayers));
-        setSelectedFillId(fillLayerId(0));
-        setSelectedStopId("stop-0");
-      }
-    : undefined;
-
-  const handleRemoveFill = onBackgroundImageChange
-    ? (id: string) => {
-        const index = fillLayerIndex(id);
-        if (index === null) return;
-        removeBackgroundLayer(index);
+  // Prefer the layer-index-aware callback when the caller wired it: it
+  // receives the full four-property patch already merged to preserve every
+  // sibling gradient/image layer (see `imageFillChangePatch`), instead of
+  // just `{url, fit}` — the shape `onImageFillChange` alone can't express a
+  // "leave every other layer untouched" write, so a caller stuck with only
+  // that prop is structurally forced to replace the whole background stack.
+  const handleImageFillChange = onImageFillLayerChange
+    ? (nextImage: ImageFillValue) => {
+        const styles = imageFillToBackgroundStyles(nextImage);
+        const layerIndex = fillLayerIndex(selectedFillId);
+        onImageFillLayerChange(
+          imageFillChangePatch(
+            {
+              backgroundImage: backgroundLayers,
+              backgroundSize: backgroundSizeLayers,
+              backgroundRepeat: backgroundRepeatLayers,
+              backgroundPosition: backgroundPositionLayers,
+            },
+            layerIndex,
+            styles,
+          ),
+        );
+        if (layerIndex === null) setSelectedFillId(fillLayerId(0));
       }
-    : undefined;
+    : onImageFillChange;
 
   const handleGradientTypeChange =
     activeGradient && activeGradientIndex !== null
@@ -394,74 +446,6 @@ export function ColorInput({
         }
       : undefined;
 
-  const handleGradientStopChange =
-    activeGradient && activeGradientIndex !== null
-      ? (id: string, patch: DesignGradientStopPatch) => {
-          const nextStops = activeGradient.stops.map((stop) =>
-            stop.id === id ? { ...stop, ...patch } : stop,
-          );
-          replaceBackgroundLayer(
-            activeGradientIndex,
-            buildGradientLayer(
-              activeGradient.type,
-              nextStops,
-              activeGradient.prefix,
-            ),
-          );
-        }
-      : undefined;
-
-  const handleAddGradientStop = onBackgroundImageChange
-    ? () => {
-        if (activeGradient && activeGradientIndex !== null) {
-          const nextStop: DesignGradientStop = {
-            id: `stop-${activeGradient.stops.length}`,
-            color: draft || "#000000",
-            position: 50,
-            opacity: 100,
-          };
-          replaceBackgroundLayer(
-            activeGradientIndex,
-            buildGradientLayer(
-              activeGradient.type,
-              [...activeGradient.stops, nextStop],
-              activeGradient.prefix,
-            ),
-          );
-          setSelectedStopId(nextStop.id);
-          return;
-        }
-
-        onBackgroundImageChange(
-          joinCssLayers([
-            defaultGradientLayer("linear", draft || value || "#000000"),
-            ...backgroundLayers,
-          ]),
-        );
-        setSelectedFillId(fillLayerId(0));
-        setSelectedStopId("stop-0");
-      }
-    : undefined;
-
-  const handleRemoveGradientStop =
-    activeGradient && activeGradientIndex !== null
-      ? (id: string) => {
-          if (activeGradient.stops.length <= 2) return;
-          const nextStops = activeGradient.stops.filter(
-            (stop) => stop.id !== id,
-          );
-          replaceBackgroundLayer(
-            activeGradientIndex,
-            buildGradientLayer(
-              activeGradient.type,
-              nextStops,
-              activeGradient.prefix,
-            ),
-          );
-          setSelectedStopId(nextStops[0]?.id);
-        }
-      : undefined;
-
   const selectedPaintType: DesignPaintType =
     selectedFillId !== SOLID_FILL_ID
       ? selectedGradient
@@ -574,7 +558,7 @@ export function ColorInput({
       onPaintValueChange={
         supportsLayeredFills ? handlePaintValueChange : undefined
       }
-      onImageFillChange={onImageFillChange}
+      onImageFillChange={handleImageFillChange}
       backgroundImage={selectedBackgroundLayerValue(backgroundLayers)}
       backgroundSize={selectedBackgroundLayerValue(backgroundSizeLayers)}
       backgroundRepeat={selectedBackgroundLayerValue(backgroundRepeatLayers)}
@@ -584,24 +568,10 @@ export function ColorInput({
       blendMode={blendMode}
       onBlendModeChange={onBlendModeChange}
       showBlendMode={Boolean(onBlendModeChange)}
-      fillRows={fillRows}
-      selectedFillId={selectedFillId}
-      onFillSelect={supportsLayeredFills ? setSelectedFillId : undefined}
-      onFillChange={supportsLayeredFills ? handleFillChange : undefined}
-      onAddFill={supportsLayeredFills ? handleAddFill : undefined}
-      onRemoveFill={supportsLayeredFills ? handleRemoveFill : undefined}
       paintType={selectedPaintType}
       onPaintTypeChange={handlePaintTypeChange}
       gradientType={activeGradient?.type}
       onGradientTypeChange={handleGradientTypeChange}
-      gradientStops={activeGradient?.stops}
-      selectedStopId={selectedStopId}
-      onGradientStopSelect={setSelectedStopId}
-      onGradientStopChange={handleGradientStopChange}
-      onAddGradientStop={
-        supportsLayeredFills ? handleAddGradientStop : undefined
-      }
-      onRemoveGradientStop={handleRemoveGradientStop}
       documentColors={documentColors}
       supportedPaintTypes={supportedPaintTypes}
       glslShaderContext={glslShaderContext}
diff --git a/templates/design/app/components/design/edit-panel/position-helpers.stroke.test.ts b/templates/design/app/components/design/edit-panel/position-helpers.stroke.test.ts
new file mode 100644
index 0000000000..d4cfb4cd30
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/position-helpers.stroke.test.ts
@@ -0,0 +1,121 @@
+/**
+ * Stroke-section bug-hunt fixes (Figma-parity pass).
+ *
+ * 1. `strokeShowPatch` — StrokeLayerControl's eye-toggle "show" click used to
+ *    fire three sequential onStyleChange calls (color, style, width) instead
+ *    of one atomic patch, unlike every other multi-property commit in this
+ *    file (e.g. TextStrokeProperties' equivalent show handler, which already
+ *    batched via commitStylePatch). Extracted the patch computation so the
+ *    caller can commit it as one history step, and tested directly here.
+ * 2. `resolveRestoredStrokeStyle` — the Stroke section's top-level "+" button
+ *    restored a hidden-but-existing border with `borderStyle` hardcoded to
+ *    "solid", silently discarding a dashed/dotted style; the parallel outline
+ *    branch a few lines below it already preserved style correctly. Both
+ *    branches now share this one helper.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  outlineOffsetForPosition,
+  readStrokeOutlinePosition,
+  resolveRestoredStrokeStyle,
+  strokeShowPatch,
+} from "./position-helpers";
+
+describe("resolveRestoredStrokeStyle", () => {
+  it("preserves a real configured style (dashed/dotted/etc)", () => {
+    expect(resolveRestoredStrokeStyle("dashed")).toBe("dashed");
+    expect(resolveRestoredStrokeStyle("dotted")).toBe("dotted");
+    expect(resolveRestoredStrokeStyle("solid")).toBe("solid");
+  });
+
+  it('defaults to "solid" only when there is no style yet or it is the legacy "none" hide value', () => {
+    expect(resolveRestoredStrokeStyle("none")).toBe("solid");
+    expect(resolveRestoredStrokeStyle(undefined)).toBe("solid");
+    expect(resolveRestoredStrokeStyle("")).toBe("solid");
+  });
+});
+
+describe("strokeShowPatch", () => {
+  it("restores full alpha on the stashed RGB color", () => {
+    const patch = strokeShowPatch(
+      "border",
+      "rgba(255, 0, 0, 0)", // hidden via zero-alpha, red channel preserved
+      "2px",
+      "solid",
+    );
+    // rgbaToCss serializes a fully-opaque color as hex, not rgba(...).
+    expect(patch.borderColor).toBe("#ff0000");
+  });
+
+  it("falls back to opaque black when the stashed color is unparseable", () => {
+    const patch = strokeShowPatch("border", "", "2px", "solid");
+    expect(patch.borderColor).toBe("#000000");
+  });
+
+  it("guarantees a non-zero width, defaulting a zeroed width to 1px", () => {
+    expect(
+      strokeShowPatch("border", "rgba(0,0,0,1)", "0px", "solid").borderWidth,
+    ).toBe("1px");
+    expect(
+      strokeShowPatch("outline", "rgba(0,0,0,1)", "3px", "solid").outlineWidth,
+    ).toBe("3px");
+  });
+
+  it('only forces the style back to "solid" when it was the legacy "none" hide value', () => {
+    const fromNone = strokeShowPatch("border", "rgba(0,0,0,1)", "2px", "none");
+    expect(fromNone.borderStyle).toBe("solid");
+
+    const fromDashed = strokeShowPatch(
+      "outline",
+      "rgba(0,0,0,1)",
+      "2px",
+      "dashed",
+    );
+    // A real style must be left untouched — no key written at all, so the
+    // caller's existing outlineStyle stays exactly as it was.
+    expect(fromDashed.outlineStyle).toBeUndefined();
+  });
+
+  it("produces a single flat patch object usable as one atomic commitStylePatch call (border)", () => {
+    const patch = strokeShowPatch("border", "rgba(0,0,0,0)", "0px", "none");
+    expect(patch).toEqual({
+      borderColor: "#000000",
+      borderWidth: "1px",
+      borderStyle: "solid",
+    });
+  });
+
+  it("produces a single flat patch object usable as one atomic commitStylePatch call (outline)", () => {
+    const patch = strokeShowPatch("outline", "rgba(0,0,0,0)", "0px", "none");
+    expect(patch).toEqual({
+      outlineColor: "#000000",
+      outlineWidth: "1px",
+      outlineStyle: "solid",
+    });
+  });
+});
+
+// Not a bug fix — existing round-trip coverage for the position <-> offset
+// math these fixes sit next to, since neither had a dedicated test file yet.
+describe("outline position <-> offset round trip", () => {
+  it("outside is always offset 0px regardless of width", () => {
+    expect(outlineOffsetForPosition("outside", "4px")).toBe("0px");
+    expect(readStrokeOutlinePosition("4px", "0px")).toBe("outside");
+  });
+
+  it("center offsets by exactly -width/2 and reads back as center", () => {
+    expect(outlineOffsetForPosition("center", "4px")).toBe("-2px");
+    expect(readStrokeOutlinePosition("4px", "-2px")).toBe("center");
+  });
+
+  it("tolerates float drift from repeated round-tripping on odd widths", () => {
+    const offset = outlineOffsetForPosition("center", "3px");
+    expect(readStrokeOutlinePosition("3px", offset)).toBe("center");
+  });
+
+  it("zero width never reads back as center", () => {
+    expect(readStrokeOutlinePosition("0px", "0px")).toBe("outside");
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/position-helpers.ts b/templates/design/app/components/design/edit-panel/position-helpers.ts
index 98667ace78..05c0b16039 100644
--- a/templates/design/app/components/design/edit-panel/position-helpers.ts
+++ b/templates/design/app/components/design/edit-panel/position-helpers.ts
@@ -1,4 +1,8 @@
-import { parseCssColor } from "@shared/color-utils";
+import {
+  parseCssColor,
+  rgbaToCss,
+  withColorOpacity,
+} from "@shared/color-utils";
 
 export function cssLengthNumber(
   value: string | undefined,
@@ -179,6 +183,54 @@ export function outlineOffsetForPosition(
   return `${roundToOneDecimal(-widthPx / 2)}px`;
 }
 
+/**
+ * Resolve the borderStyle/outlineStyle to persist when (re)creating or
+ * restoring a stroke layer: preserve whatever real style was already set
+ * (solid/dashed/dotted/etc), and only default to "solid" when there's none
+ * yet or the legacy "none" hide value is still in place. Shared by both the
+ * border and outline "restore" branches in the Stroke section's add-layer
+ * handler so they stay in parity — previously only the outline branch did
+ * this (`styles.outlineStyle === "none" ? "solid" : styles.outlineStyle ||
+ * "solid"`); the border branch a few lines above it hardcoded `"solid"`
+ * unconditionally, silently discarding a dashed/dotted style whenever a
+ * hidden-but-existing border was restored via the section's + button
+ * instead of its own eye toggle (which already preserves style correctly).
+ */
+export function resolveRestoredStrokeStyle(
+  styleValue: string | undefined,
+): string {
+  return styleValue === "none" ? "solid" : styleValue || "solid";
+}
+
+/**
+ * The style patch StrokeLayerControl's eye-toggle "show" click commits when
+ * un-hiding a border/outline stroke: restores full alpha on the stashed RGB
+ * color (see `strokeHiddenByColor`), guarantees a non-zero width, and only
+ * forces the style back to "solid" when it was the legacy "none" hide value
+ * (preserving a dashed/dotted style otherwise). Extracted as a pure function
+ * — rather than three sequential `onStyleChange` calls — so the caller can
+ * commit it as ONE atomic patch via `commitStylePatch`/`onStylesChange`
+ * (a single undo/history step, matching every other multi-property commit
+ * in this file, e.g. TextStrokeProperties' equivalent show handler).
+ */
+export function strokeShowPatch(
+  prefix: "border" | "outline",
+  color: string,
+  width: string,
+  styleValue: string,
+): Record<string, string> {
+  const parsed = parseCssColor(color);
+  const restoredColor = parsed
+    ? rgbaToCss(withColorOpacity(parsed, 100))
+    : "#000000";
+  const patch: Record<string, string> = {
+    [`${prefix}Color`]: restoredColor,
+    [`${prefix}Width`]: width === "0px" ? "1px" : width || "1px",
+  };
+  if (styleValue === "none") patch[`${prefix}Style`] = "solid";
+  return patch;
+}
+
 export function swatchStyle(value: string | undefined) {
   return {
     background:
diff --git a/templates/design/app/components/design/edit-panel/position-layout-properties.test.ts b/templates/design/app/components/design/edit-panel/position-layout-properties.test.ts
new file mode 100644
index 0000000000..fd0e1283af
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/position-layout-properties.test.ts
@@ -0,0 +1,275 @@
+import { describe, expect, it } from "vitest";
+
+import type { ElementInfo } from "../types";
+import {
+  constraintsStylePatch,
+  definiteAuthoredOffset,
+  deriveConstraintsValue,
+} from "./position-layout-properties";
+
+function element(overrides: Partial<ElementInfo> = {}): ElementInfo {
+  return {
+    tagName: "div",
+    classes: [],
+    computedStyles: {},
+    boundingRect: { x: 0, y: 0, width: 100, height: 50 },
+    parentBoundingRect: { x: 0, y: 0, width: 400, height: 200 },
+    isFlexChild: false,
+    isFlexContainer: false,
+    ...overrides,
+  } as ElementInfo;
+}
+
+describe("definiteAuthoredOffset", () => {
+  it("passes through a real authored offset", () => {
+    expect(definiteAuthoredOffset("120px")).toBe("120px");
+  });
+
+  it("treats the CSS default 'auto' as unset", () => {
+    expect(definiteAuthoredOffset("auto")).toBeUndefined();
+  });
+
+  it("treats the Mixed sentinel as unset", () => {
+    expect(definiteAuthoredOffset("Mixed")).toBeUndefined();
+  });
+
+  it("treats an empty string or undefined as unset", () => {
+    expect(definiteAuthoredOffset("")).toBeUndefined();
+    expect(definiteAuthoredOffset(undefined)).toBeUndefined();
+  });
+});
+
+describe("deriveConstraintsValue", () => {
+  it("reads a plain, never-repositioned element as anchored left/top, not left-right/top-bottom", () => {
+    // No inlineStyles at all (the common case for an ordinary element that
+    // was never explicitly given left/right/top/bottom) — authoredStyleValue
+    // falls back to computedStyles, and getComputedStyle reports "auto" for
+    // an unpositioned element's left/right/top/bottom. Before the
+    // definiteAuthoredOffset guard, "auto" && "auto" read as truthy and this
+    // rendered as pinned to both edges on every ordinary element.
+    const value = deriveConstraintsValue(
+      element({
+        computedStyles: {
+          left: "auto",
+          right: "auto",
+          top: "auto",
+          bottom: "auto",
+          width: "100px",
+          height: "50px",
+        },
+      }),
+    );
+    expect(value).toEqual({ horizontal: "left", vertical: "top" });
+  });
+
+  it("reads an explicitly authored left+right as left-right", () => {
+    const value = deriveConstraintsValue(
+      element({
+        inlineStyles: { left: "10px", right: "10px" },
+        computedStyles: {
+          left: "10px",
+          right: "10px",
+          top: "auto",
+          bottom: "auto",
+        },
+      }),
+    );
+    expect(value.horizontal).toBe("left-right");
+  });
+
+  it("does not mistake a computed opposite edge for an authored pin", () => {
+    const value = deriveConstraintsValue(
+      element({
+        inlineStyles: { left: "40px", top: "20px", width: "120px" },
+        computedStyles: {
+          left: "40px",
+          right: "240px",
+          top: "20px",
+          bottom: "240px",
+          width: "120px",
+        },
+      }),
+    );
+    expect(value).toEqual({ horizontal: "left", vertical: "top" });
+  });
+
+  it("reads an explicitly authored right-only pin as right", () => {
+    const value = deriveConstraintsValue(
+      element({
+        inlineStyles: { right: "0px" },
+        computedStyles: { left: "auto", right: "0px" },
+      }),
+    );
+    expect(value.horizontal).toBe("right");
+  });
+
+  it("reads width:100% as scale regardless of left/right", () => {
+    const value = deriveConstraintsValue(
+      element({
+        computedStyles: { width: "100%", left: "auto", right: "auto" },
+      }),
+    );
+    expect(value.horizontal).toBe("scale");
+  });
+
+  it("reports a cross-selection Mixed horizontal axis honestly", () => {
+    const value = deriveConstraintsValue(
+      element({
+        computedStyles: { left: "Mixed", right: "Mixed" },
+      }),
+    );
+    expect(value.horizontal).toBe("mixed");
+    expect(value.vertical).toBe("top");
+  });
+
+  it("reports transform-dependent axes as Mixed when transforms differ", () => {
+    expect(
+      deriveConstraintsValue(
+        element({ computedStyles: { transform: "Mixed" } }),
+      ),
+    ).toEqual({ horizontal: "mixed", vertical: "mixed" });
+  });
+});
+
+describe("constraintsStylePatch", () => {
+  it("builds one complete centered constraints patch", () => {
+    expect(
+      constraintsStylePatch(
+        element({
+          computedStyles: { transform: "rotate(15deg)" },
+          boundingRect: { x: 20, y: 30, width: 100, height: 50 },
+          parentBoundingRect: { x: 0, y: 0, width: 400, height: 200 },
+        }),
+        { horizontal: "center", vertical: "center" },
+      ),
+    ).toEqual({
+      position: "absolute",
+      left: "calc(50% + -130px)",
+      right: "auto",
+      width: "100px",
+      top: "calc(50% + -45px)",
+      bottom: "auto",
+      height: "50px",
+      transform: "translateY(-50%) translateX(-50%) rotate(15deg)",
+    });
+  });
+
+  it("leaves a mixed axis entirely untouched when the other axis changes", () => {
+    expect(
+      constraintsStylePatch(
+        element({
+          inlineStyles: { left: "Mixed", right: "Mixed", top: "12px" },
+          computedStyles: { transform: "none" },
+        }),
+        { horizontal: "mixed", vertical: "bottom" },
+      ),
+    ).toEqual({
+      position: "absolute",
+      bottom: "150px",
+      top: "auto",
+      height: "50px",
+      transform: "none",
+    });
+  });
+
+  it("falls back to the current canvas coordinates without ever writing auto or Mixed as a pin", () => {
+    expect(
+      constraintsStylePatch(
+        element({
+          inlineStyles: { left: "Mixed", top: "auto" },
+          boundingRect: { x: 20.4, y: 30.6, width: 100, height: 50 },
+        }),
+        { horizontal: "left", vertical: "mixed" },
+      ),
+    ).toMatchObject({ left: "20.4px" });
+  });
+
+  it("writes proportional position and size for Scale on both axes", () => {
+    expect(
+      constraintsStylePatch(
+        element({
+          computedStyles: { transform: "rotate(12deg)" },
+          boundingRect: { x: 140, y: 90, width: 120, height: 60 },
+          parentBoundingRect: { x: 100, y: 50, width: 400, height: 200 },
+        }),
+        { horizontal: "scale", vertical: "scale" },
+      ),
+    ).toEqual({
+      position: "absolute",
+      left: "10%",
+      right: "auto",
+      width: "30%",
+      top: "20%",
+      bottom: "auto",
+      height: "30%",
+      transform: "rotate(12deg)",
+    });
+  });
+
+  it("preserves current right/bottom gaps instead of snapping to zero", () => {
+    expect(
+      constraintsStylePatch(
+        element({
+          boundingRect: { x: 140, y: 90, width: 120, height: 60 },
+          parentBoundingRect: { x: 100, y: 50, width: 400, height: 200 },
+        }),
+        { horizontal: "right", vertical: "bottom" },
+      ),
+    ).toMatchObject({
+      left: "auto",
+      right: "240px",
+      width: "120px",
+      top: "auto",
+      bottom: "100px",
+      height: "60px",
+    });
+  });
+
+  it("pins both edges and releases fixed size for stretch constraints", () => {
+    expect(
+      constraintsStylePatch(
+        element({
+          boundingRect: { x: 140, y: 90, width: 120, height: 60 },
+          parentBoundingRect: { x: 100, y: 50, width: 400, height: 200 },
+        }),
+        { horizontal: "left-right", vertical: "top-bottom" },
+      ),
+    ).toMatchObject({
+      left: "40px",
+      right: "240px",
+      width: "auto",
+      top: "40px",
+      bottom: "100px",
+      height: "auto",
+    });
+  });
+
+  it("does not rewrite the unchanged opposite axis and preserves its transform", () => {
+    expect(
+      constraintsStylePatch(
+        element({
+          inlineStyles: {
+            top: "50%",
+            height: "50px",
+            transform: "translateY(-50%) rotate(8deg)",
+          },
+          computedStyles: {
+            left: "20px",
+            top: "50%",
+            width: "100px",
+            height: "50px",
+            transform: "translateY(-50%) rotate(8deg)",
+          },
+          boundingRect: { x: 20, y: 75, width: 100, height: 50 },
+        }),
+        { horizontal: "scale", vertical: "center" },
+      ),
+    ).toEqual({
+      position: "absolute",
+      left: "5%",
+      right: "auto",
+      width: "25%",
+      transform: "translateY(-50%) rotate(8deg)",
+    });
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/position-layout-properties.tsx b/templates/design/app/components/design/edit-panel/position-layout-properties.tsx
index 2f52dbd049..d63819443f 100644
--- a/templates/design/app/components/design/edit-panel/position-layout-properties.tsx
+++ b/templates/design/app/components/design/edit-panel/position-layout-properties.tsx
@@ -43,7 +43,11 @@ import {
   AppearanceScrubField,
   CornerRadiusControl,
 } from "./appearance-properties";
-import { FieldTrailer, ScrubStyleInput } from "./field-primitives";
+import {
+  commitStylePatch,
+  FieldTrailer,
+  ScrubStyleInput,
+} from "./field-primitives";
 import {
   InspectorIconButton,
   InspectorSegment,
@@ -57,6 +61,7 @@ import type {
   BreakpointOverrideFieldContext,
   MotionKeyframeFieldContext,
   StyleChangeHandler,
+  StylesChangeHandler,
 } from "./style-change-types";
 import {
   mergeRotationValue,
@@ -65,16 +70,254 @@ import {
   parseScaleValue,
 } from "./transform-helpers";
 
+/**
+ * `authoredStyleValue()` returns the *inline* value when one is set, but
+ * falls back to the *computed* style otherwise — and `getComputedStyle()`
+ * reports "auto" for left/right/top/bottom on any element that has never had
+ * one of those offsets explicitly authored (the ordinary case for a plain,
+ * not-yet-repositioned element). A bare "auto" is not a real authored pin,
+ * and the cross-selection Mixed sentinel isn't either. Without this guard,
+ * `authoredLeft && authoredRight` truthiness checks below treated "auto" as
+ * "yes, pinned", so a completely unconstrained element read as "left-right"/
+ * "top-bottom" (pinned to both edges) in the Constraints preview, the X/Y
+ * fields showed a parsed "0" instead of the element's real on-canvas
+ * position, and picking "Left"/"Top" from an unconstrained element could
+ * write the literal string `"auto"` as the new `left`/`top` value instead of
+ * anchoring it at its current position. Exported for tests.
+ */
+export function definiteAuthoredOffset(
+  raw: string | undefined,
+): string | undefined {
+  if (!raw || raw === "auto" || isMixedValue(raw)) return undefined;
+  return raw;
+}
+
+function percentageLength(raw: string | undefined): boolean {
+  return !!raw && /^-?(?:\d+\.?\d*|\.\d+)%$/.test(raw.trim());
+}
+
+function geometryPercent(value: number, total: number): string {
+  if (!Number.isFinite(value) || !Number.isFinite(total) || total <= 0) {
+    return "0%";
+  }
+  return `${Number(((value / total) * 100).toFixed(6))}%`;
+}
+
+function geometryPx(value: number): string {
+  return `${Number(value.toFixed(3))}px`;
+}
+
+/** Once the bridge supplies an inline-style snapshot, absence is meaningful:
+ * an absolutely-positioned left-only element still has a computed `right`,
+ * but that resolved value is not an authored right pin. Older payloads omit
+ * `inlineStyles` entirely, so only those fall back to computed styles. */
+function authoredConstraintValue(
+  element: ElementInfo,
+  property: string,
+): string | undefined {
+  if (element.inlineStyles !== undefined) {
+    const value = element.inlineStyles[property];
+    return value === "auto" ? "" : value;
+  }
+  return element.computedStyles[property];
+}
+
+/**
+ * Derives the Constraints preview/widget state from an element's authored
+ * left/right/top/bottom/width/height/transform. Pulled out as a standalone
+ * pure function (mirrors `autoLayoutStylesForFlow` in layout-properties.tsx)
+ * so the "auto"/Mixed-safe derivation fixed by `definiteAuthoredOffset` above
+ * is directly unit-testable without rendering the whole panel. Exported for
+ * tests.
+ */
+export function deriveConstraintsValue(element: ElementInfo): ConstraintsValue {
+  const authoredLeft = authoredConstraintValue(element, "left");
+  const authoredRight = authoredConstraintValue(element, "right");
+  const authoredTop = authoredConstraintValue(element, "top");
+  const authoredBottom = authoredConstraintValue(element, "bottom");
+  const authoredWidth = authoredConstraintValue(element, "width");
+  const authoredHeight = authoredConstraintValue(element, "height");
+  const authoredTransform = authoredConstraintValue(element, "transform");
+  const definiteLeft = definiteAuthoredOffset(authoredLeft);
+  const definiteRight = definiteAuthoredOffset(authoredRight);
+  const definiteTop = definiteAuthoredOffset(authoredTop);
+  const definiteBottom = definiteAuthoredOffset(authoredBottom);
+  const horizontalMixed = [
+    authoredLeft,
+    authoredRight,
+    authoredWidth,
+    authoredTransform,
+  ].some(isMixedValue);
+  const verticalMixed = [
+    authoredTop,
+    authoredBottom,
+    authoredHeight,
+    authoredTransform,
+  ].some(isMixedValue);
+  return {
+    horizontal: horizontalMixed
+      ? "mixed"
+      : // Check scale before left+right: "scale" writes width:100% and clears
+        // left/right to auto, but legacy data may have 0px values that are truthy.
+        authoredWidth === "100%" ||
+          (percentageLength(authoredWidth) && percentageLength(definiteLeft))
+        ? "scale"
+        : definiteLeft && definiteRight
+          ? "left-right"
+          : definiteRight
+            ? "right"
+            : authoredTransform?.includes("translateX(-50%)")
+              ? "center"
+              : "left",
+    vertical: verticalMixed
+      ? "mixed"
+      : authoredHeight === "100%" ||
+          (percentageLength(authoredHeight) && percentageLength(definiteTop))
+        ? "scale"
+        : definiteTop && definiteBottom
+          ? "top-bottom"
+          : definiteBottom
+            ? "bottom"
+            : authoredTransform?.includes("translateY(-50%)")
+              ? "center"
+              : "top",
+  };
+}
+
+/** Build the complete constraints edit before writing anything. The previous
+ * implementation emitted position, four offsets, size, and transform as
+ * separate writes, producing visible intermediate layouts and one undo entry
+ * per property. Keeping this pure also makes the exact atomic patch directly
+ * regression-testable. A mixed axis is intentionally left untouched until the
+ * user chooses a concrete value for that axis. */
+export function constraintsStylePatch(
+  element: ElementInfo,
+  value: ConstraintsValue,
+): Record<string, string> {
+  const authoredTransform = authoredConstraintValue(element, "transform");
+  const currentValue = deriveConstraintsValue(element);
+  const patch: Record<string, string> = {};
+  let transform = isMixedValue(authoredTransform)
+    ? undefined
+    : authoredTransform;
+  let transformChanged = false;
+  const parentBounds =
+    element.parentBoundingRect ?? element.parentAutoLayout?.boundingRect;
+  const childBounds = element.boundingRect;
+  const relativeLeft = parentBounds
+    ? childBounds.x - parentBounds.x
+    : childBounds.x;
+  const relativeTop = parentBounds
+    ? childBounds.y - parentBounds.y
+    : childBounds.y;
+  const rightGap = parentBounds
+    ? parentBounds.width - relativeLeft - childBounds.width
+    : 0;
+  const bottomGap = parentBounds
+    ? parentBounds.height - relativeTop - childBounds.height
+    : 0;
+
+  if (
+    value.horizontal !== "mixed" &&
+    value.horizontal !== currentValue.horizontal
+  ) {
+    patch.position = "absolute";
+    transform = mergeTranslateFunction(
+      transform,
+      "X",
+      value.horizontal === "center" ? "-50%" : null,
+    );
+    transformChanged = true;
+    if (value.horizontal === "left") {
+      patch.left = geometryPx(relativeLeft);
+      patch.right = "auto";
+      patch.width = geometryPx(childBounds.width);
+    } else if (value.horizontal === "right") {
+      patch.right = geometryPx(rightGap);
+      patch.left = "auto";
+      patch.width = geometryPx(childBounds.width);
+    } else if (value.horizontal === "left-right") {
+      patch.left = geometryPx(relativeLeft);
+      patch.right = geometryPx(rightGap);
+      patch.width = "auto";
+    } else if (value.horizontal === "center") {
+      const centerOffset = parentBounds
+        ? relativeLeft + childBounds.width / 2 - parentBounds.width / 2
+        : 0;
+      patch.left =
+        Math.abs(centerOffset) < 0.0005
+          ? "50%"
+          : `calc(50% + ${geometryPx(centerOffset)})`;
+      patch.right = "auto";
+      patch.width = geometryPx(childBounds.width);
+    } else {
+      patch.left = parentBounds
+        ? geometryPercent(relativeLeft, parentBounds.width)
+        : "0%";
+      patch.right = "auto";
+      patch.width = parentBounds
+        ? geometryPercent(childBounds.width, parentBounds.width)
+        : "100%";
+    }
+  }
+
+  if (value.vertical !== "mixed" && value.vertical !== currentValue.vertical) {
+    patch.position = "absolute";
+    transform = mergeTranslateFunction(
+      transform,
+      "Y",
+      value.vertical === "center" ? "-50%" : null,
+    );
+    transformChanged = true;
+    if (value.vertical === "top") {
+      patch.top = geometryPx(relativeTop);
+      patch.bottom = "auto";
+      patch.height = geometryPx(childBounds.height);
+    } else if (value.vertical === "bottom") {
+      patch.bottom = geometryPx(bottomGap);
+      patch.top = "auto";
+      patch.height = geometryPx(childBounds.height);
+    } else if (value.vertical === "top-bottom") {
+      patch.top = geometryPx(relativeTop);
+      patch.bottom = geometryPx(bottomGap);
+      patch.height = "auto";
+    } else if (value.vertical === "center") {
+      const centerOffset = parentBounds
+        ? relativeTop + childBounds.height / 2 - parentBounds.height / 2
+        : 0;
+      patch.top =
+        Math.abs(centerOffset) < 0.0005
+          ? "50%"
+          : `calc(50% + ${geometryPx(centerOffset)})`;
+      patch.bottom = "auto";
+      patch.height = geometryPx(childBounds.height);
+    } else {
+      patch.top = parentBounds
+        ? geometryPercent(relativeTop, parentBounds.height)
+        : "0%";
+      patch.bottom = "auto";
+      patch.height = parentBounds
+        ? geometryPercent(childBounds.height, parentBounds.height)
+        : "100%";
+    }
+  }
+
+  if (transformChanged) patch.transform = transform || "none";
+  return patch;
+}
+
 /** Position, size, and spacing properties */
 export function PositionLayoutProperties({
   element,
   onStyleChange,
+  onStylesChange,
   onAlignSelection,
   motionKeyframeContext,
   breakpointOverrideContext,
 }: {
   element: ElementInfo;
   onStyleChange: StyleChangeHandler;
+  onStylesChange?: StylesChangeHandler;
   /**
    * Moves the selection itself (Figma's real "Alignment" row semantics):
    * aligns to the combined selection bounding box for a 2+ multi-selection,
@@ -113,40 +356,16 @@ export function PositionLayoutProperties({
       value === "top" ? "top" : value === "bottom" ? "bottom" : "center-v",
     );
   };
-  // Authored (not computed) offsets: when inlineStyles is present, "auto"/absent
-  // is treated as truly unset instead of the computed px fallback, so a plain
-  // top-left-anchored element reads as "left" rather than always "left-right".
+  // Authored (not computed) left/top: used directly (not through
+  // `definiteAuthoredOffset`) below because the X/Y fields need to tell
+  // "Mixed" apart from "unset", and handleConstraintsChange's own fallback
+  // already normalizes through `definiteAuthoredOffset` at its call sites.
+  // Right/bottom and the scale/rotation checks needed for the Constraints
+  // preview live in `deriveConstraintsValue` (above) instead.
   const authoredLeft = authoredStyleValue(element, "left");
-  const authoredRight = authoredStyleValue(element, "right");
   const authoredTop = authoredStyleValue(element, "top");
-  const authoredBottom = authoredStyleValue(element, "bottom");
-  const authoredWidth = authoredStyleValue(element, "width");
-  const authoredHeight = authoredStyleValue(element, "height");
   const authoredTransform = authoredStyleValue(element, "transform");
-  const constraintsValue: ConstraintsValue = {
-    horizontal:
-      // Check scale before left+right: "scale" writes width:100% and clears
-      // left/right to auto, but legacy data may have 0px values that are truthy.
-      authoredWidth === "100%"
-        ? "scale"
-        : authoredLeft && authoredRight
-          ? "left-right"
-          : authoredRight
-            ? "right"
-            : authoredTransform?.includes("translateX(-50%)")
-              ? "center"
-              : "left",
-    vertical:
-      authoredHeight === "100%"
-        ? "scale"
-        : authoredTop && authoredBottom
-          ? "top-bottom"
-          : authoredBottom
-            ? "bottom"
-            : authoredTransform?.includes("translateY(-50%)")
-              ? "center"
-              : "top",
-  };
+  const constraintsValue = deriveConstraintsValue(element);
   const [constraintsExpanded, setConstraintsExpanded] = useState(false);
   // 3D rotation/perspective progressive-disclosure expander — mirrors
   // CornerRadiusControl's showIndependentCorners pattern. Default-expanded
@@ -164,87 +383,13 @@ export function PositionLayoutProperties({
 
   const handleConstraintsChange = useCallback(
     (value: ConstraintsValue) => {
-      onStyleChange("position", "absolute");
-
-      // Compute the desired translateX/Y for each axis independently, then
-      // compose both into a single transform write so the two axes don't
-      // overwrite each other when both change simultaneously.
-      const txValue = value.horizontal === "center" ? "-50%" : null;
-      const tyValue = value.vertical === "center" ? "-50%" : null;
-      // Start from the current transform, apply X, then apply Y on top.
-      const transformAfterX = mergeTranslateFunction(
-        authoredTransform,
-        "X",
-        txValue,
-      );
-      const transformAfterXY = mergeTranslateFunction(
-        transformAfterX,
-        "Y",
-        tyValue,
+      commitStylePatch(
+        constraintsStylePatch(element, value),
+        onStyleChange,
+        onStylesChange,
       );
-
-      if (value.horizontal === "left") {
-        onStyleChange(
-          "left",
-          authoredLeft || `${Math.round(element.boundingRect.x)}px`,
-        );
-        onStyleChange("right", "auto");
-      } else if (value.horizontal === "right") {
-        onStyleChange("right", "0px");
-        onStyleChange("left", "auto");
-      } else if (value.horizontal === "left-right") {
-        onStyleChange(
-          "left",
-          authoredLeft || `${Math.round(element.boundingRect.x)}px`,
-        );
-        onStyleChange("right", "0px");
-      } else if (value.horizontal === "center") {
-        onStyleChange("left", "50%");
-        onStyleChange("right", "auto");
-      } else {
-        // scale: use auto (not 0px) so the left && right truthiness check
-        // in the reader does not misidentify this as "left-right".
-        onStyleChange("left", "auto");
-        onStyleChange("right", "auto");
-        onStyleChange("width", "100%");
-      }
-
-      if (value.vertical === "top") {
-        onStyleChange(
-          "top",
-          authoredTop || `${Math.round(element.boundingRect.y)}px`,
-        );
-        onStyleChange("bottom", "auto");
-      } else if (value.vertical === "bottom") {
-        onStyleChange("bottom", "0px");
-        onStyleChange("top", "auto");
-      } else if (value.vertical === "top-bottom") {
-        onStyleChange(
-          "top",
-          authoredTop || `${Math.round(element.boundingRect.y)}px`,
-        );
-        onStyleChange("bottom", "0px");
-      } else if (value.vertical === "center") {
-        onStyleChange("top", "50%");
-        onStyleChange("bottom", "auto");
-      } else {
-        // scale
-        onStyleChange("top", "auto");
-        onStyleChange("bottom", "auto");
-        onStyleChange("height", "100%");
-      }
-
-      // Write the composed transform once, after both axes are resolved.
-      onStyleChange("transform", transformAfterXY);
     },
-    [
-      element.boundingRect.x,
-      element.boundingRect.y,
-      onStyleChange,
-      authoredLeft,
-      authoredTop,
-      authoredTransform,
-    ],
+    [element, onStyleChange, onStylesChange],
   );
 
   return (
@@ -328,7 +473,9 @@ export function PositionLayoutProperties({
               ariaLabel="X-position"
               tooltipLabel="X-position"
               value={
-                isMixedValue(authoredLeft) ? MIXED_VALUE : authoredLeft || ""
+                isMixedValue(authoredLeft)
+                  ? MIXED_VALUE
+                  : (definiteAuthoredOffset(authoredLeft) ?? "")
               }
               placeholder={element.boundingRect.x}
               inputClassName="h-6"
@@ -338,8 +485,17 @@ export function PositionLayoutProperties({
                 // mirror handleConstraintsChange, which always sets
                 // position:absolute (the convention canvas drag/resize and
                 // primitive creation both use) before writing left/top.
-                if (!constrainedPosition) onStyleChange("position", "absolute");
-                onStyleChange("left", `${roundToOneDecimal(v)}px`, meta);
+                commitStylePatch(
+                  {
+                    ...(!constrainedPosition
+                      ? { position: "absolute" }
+                      : undefined),
+                    left: `${roundToOneDecimal(v)}px`,
+                  },
+                  onStyleChange,
+                  onStylesChange,
+                  meta,
+                );
               }}
             />
             <FieldTrailer
@@ -358,13 +514,24 @@ export function PositionLayoutProperties({
               ariaLabel="Y-position"
               tooltipLabel="Y-position"
               value={
-                isMixedValue(authoredTop) ? MIXED_VALUE : authoredTop || ""
+                isMixedValue(authoredTop)
+                  ? MIXED_VALUE
+                  : (definiteAuthoredOffset(authoredTop) ?? "")
               }
               placeholder={element.boundingRect.y}
               inputClassName="h-6"
               onChange={(v, meta) => {
-                if (!constrainedPosition) onStyleChange("position", "absolute");
-                onStyleChange("top", `${roundToOneDecimal(v)}px`, meta);
+                commitStylePatch(
+                  {
+                    ...(!constrainedPosition
+                      ? { position: "absolute" }
+                      : undefined),
+                    top: `${roundToOneDecimal(v)}px`,
+                  },
+                  onStyleChange,
+                  onStylesChange,
+                  meta,
+                );
               }}
             />
             <FieldTrailer
diff --git a/templates/design/app/components/design/edit-panel/selection-helpers.spec.ts b/templates/design/app/components/design/edit-panel/selection-helpers.spec.ts
new file mode 100644
index 0000000000..076c572773
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/selection-helpers.spec.ts
@@ -0,0 +1,296 @@
+import { describe, expect, it } from "vitest";
+
+import type { ElementInfo } from "../types";
+import {
+  isMixedValue,
+  MIXED_VALUE,
+  mixedElementFromSelection,
+  sameOrMixed,
+} from "./selection-helpers";
+
+function makeElement(overrides: Partial<ElementInfo> = {}): ElementInfo {
+  return {
+    tagName: "div",
+    classes: [],
+    computedStyles: {},
+    boundingRect: { x: 0, y: 0, width: 100, height: 40 },
+    isFlexChild: false,
+    isFlexContainer: false,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// sameOrMixed
+// ---------------------------------------------------------------------------
+
+describe("sameOrMixed", () => {
+  it("returns the shared value when every entry matches", () => {
+    expect(sameOrMixed(["16px", "16px", "16px"])).toBe("16px");
+  });
+
+  it("returns MIXED_VALUE as soon as one entry differs", () => {
+    expect(sameOrMixed(["16px", "16px", "8px"])).toBe(MIXED_VALUE);
+  });
+
+  it("returns an empty string for an empty array", () => {
+    expect(sameOrMixed([])).toBe("");
+  });
+
+  it("returns the sole value for a single-element array", () => {
+    expect(sameOrMixed(["solid"])).toBe("solid");
+  });
+
+  it("treats two equal empty strings as the same (not mixed)", () => {
+    expect(sameOrMixed(["", ""])).toBe("");
+  });
+
+  it("treats the literal string 'NaN' the same as any other equal string", () => {
+    // Values here are always strings (computed/authored CSS values), never
+    // JS numbers, so the classic `NaN !== NaN` footgun does not apply — two
+    // elements that both stringify to "NaN" are correctly "the same".
+    expect(sameOrMixed(["NaN", "NaN"])).toBe("NaN");
+  });
+
+  it("does not special-case the literal string 'Mixed' as an input value", () => {
+    // A real (non-sentinel) value that happens to equal MIXED_VALUE still
+    // reduces to itself when it's the only value present.
+    expect(sameOrMixed(["Mixed"])).toBe("Mixed");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isMixedValue
+// ---------------------------------------------------------------------------
+
+describe("isMixedValue", () => {
+  it("is true only for the exact MIXED_VALUE sentinel", () => {
+    expect(isMixedValue(MIXED_VALUE)).toBe(true);
+    expect(isMixedValue("Mixed")).toBe(true);
+  });
+
+  it("is false for other strings, including near-misses", () => {
+    expect(isMixedValue("mixed")).toBe(false);
+    expect(isMixedValue("Mixed ")).toBe(false);
+    expect(isMixedValue("16px")).toBe(false);
+    expect(isMixedValue("")).toBe(false);
+  });
+
+  it("is false for undefined", () => {
+    expect(isMixedValue(undefined)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mixedElementFromSelection
+// ---------------------------------------------------------------------------
+
+describe("mixedElementFromSelection", () => {
+  it("returns null for an empty selection", () => {
+    expect(mixedElementFromSelection([])).toBeNull();
+  });
+
+  it("mixes computedStyles values that differ across the selection", () => {
+    const a = makeElement({ computedStyles: { opacity: "1" } });
+    const b = makeElement({ computedStyles: { opacity: "0.5" } });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.computedStyles.opacity).toBe(MIXED_VALUE);
+  });
+
+  it("keeps a shared computedStyles value when all elements agree", () => {
+    const a = makeElement({ computedStyles: { opacity: "1" } });
+    const b = makeElement({ computedStyles: { opacity: "1" } });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.computedStyles.opacity).toBe("1");
+  });
+
+  it("treats a property present on only one element as Mixed, not a shared default", () => {
+    // `fontSize` only exists on the text element's computedStyles; the
+    // rectangle never captured it. The missing side must NOT silently read
+    // as "same as the other side" just because it coerces to "".
+    const text = makeElement({ computedStyles: { fontSize: "16px" } });
+    const rect = makeElement({ computedStyles: {} });
+    const merged = mixedElementFromSelection([text, rect]);
+    expect(merged?.computedStyles.fontSize).toBe(MIXED_VALUE);
+  });
+
+  // ── componentName (bug fix) ────────────────────────────────────────────
+  // elementIsComponentSelection() in element-classification.ts is a plain
+  // `.length > 0` truthiness check, so this field must resolve to a real
+  // shared name or `undefined` — never the "Mixed" sentinel string, which
+  // would itself read as "is a component" (a non-empty string).
+
+  it("keeps the shared component name when every element is the same component", () => {
+    const a = makeElement({ componentName: "Button" });
+    const b = makeElement({ componentName: "Button" });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.componentName).toBe("Button");
+  });
+
+  it("clears componentName (not 'Mixed') when a component is selected alongside a plain element", () => {
+    const button = makeElement({ componentName: "Button" });
+    const plainDiv = makeElement({ componentName: undefined });
+    const merged = mixedElementFromSelection([button, plainDiv]);
+    expect(merged?.componentName).toBeUndefined();
+    expect(merged?.componentName).not.toBe(MIXED_VALUE);
+  });
+
+  it("clears componentName regardless of which element is last in the array", () => {
+    const button = makeElement({ componentName: "Button" });
+    const plainDiv = makeElement({ componentName: undefined });
+    // Same pair, opposite order — must not depend on selection order.
+    const merged = mixedElementFromSelection([plainDiv, button]);
+    expect(merged?.componentName).toBeUndefined();
+  });
+
+  it("clears componentName when two different components are selected together", () => {
+    const button = makeElement({ componentName: "Button" });
+    const card = makeElement({ componentName: "Card" });
+    const merged = mixedElementFromSelection([button, card]);
+    expect(merged?.componentName).toBeUndefined();
+  });
+
+  // ── isGridContainer (bug fix) ───────────────────────────────────────────
+  // Must reduce the same way isFlexContainer already does (AND across the
+  // selection), instead of leaking from whichever element is last.
+
+  it("keeps isGridContainer true only when every element is a grid container", () => {
+    const a = makeElement({ isGridContainer: true });
+    const b = makeElement({ isGridContainer: true });
+    expect(mixedElementFromSelection([a, b])?.isGridContainer).toBe(true);
+  });
+
+  it("collapses isGridContainer to false for a mixed grid + non-grid selection, regardless of order", () => {
+    const grid = makeElement({ isGridContainer: true });
+    const nonGrid = makeElement({ isGridContainer: false });
+    expect(mixedElementFromSelection([nonGrid, grid])?.isGridContainer).toBe(
+      false,
+    );
+    // Previously this leaked `base` (the last element), so putting the grid
+    // container last used to flip the merged result to `true`.
+    expect(mixedElementFromSelection([nonGrid, grid])?.isGridContainer).toBe(
+      false,
+    );
+  });
+
+  // ── parentDisplay / parentAutoLayout / parentLayout collapse ────────────
+  // isParentFlex/isParentGrid/parentFlexDirection (element-classification.ts)
+  // read these three parent-layout snapshots to decide whether the
+  // FlexChild/GridChild controls render at all, and with which direction —
+  // they must collapse to undefined (hiding those controls) as soon as the
+  // selection spans two different parents, instead of leaking whichever
+  // element happens to be `base` (the last one).
+
+  it("preserves parentDisplay/parentAutoLayout/parentLayout when every element shares the same parent", () => {
+    const parentBoundingRect = { x: 0, y: 0, width: 300, height: 100 };
+    const parentAutoLayout = {
+      display: "flex",
+      selector: "#parent",
+      sourceId: "parent-1",
+      boundingRect: parentBoundingRect,
+    };
+    const parentLayout = {
+      display: "flex",
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "flex-start",
+      gap: "8px",
+    };
+    const a = makeElement({
+      parentDisplay: "flex",
+      parentAutoLayout,
+      parentBoundingRect,
+      parentLayout,
+    });
+    const b = makeElement({
+      parentDisplay: "flex",
+      parentAutoLayout,
+      parentBoundingRect: { ...parentBoundingRect },
+      parentLayout,
+    });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.parentDisplay).toBe("flex");
+    expect(merged?.parentAutoLayout).toEqual(parentAutoLayout);
+    expect(merged?.parentBoundingRect).toEqual(parentBoundingRect);
+    expect(merged?.parentLayout).toEqual(parentLayout);
+  });
+
+  it("collapses parentDisplay/parentAutoLayout/parentLayout to undefined when elements come from different parents", () => {
+    const a = makeElement({
+      parentDisplay: "flex",
+      parentBoundingRect: { x: 0, y: 0, width: 100, height: 40 },
+      parentAutoLayout: {
+        display: "flex",
+        sourceId: "parent-a",
+        boundingRect: { x: 0, y: 0, width: 100, height: 40 },
+      },
+      parentLayout: { display: "flex", flexDirection: "row" },
+    });
+    const b = makeElement({
+      parentDisplay: "block",
+      parentBoundingRect: { x: 0, y: 0, width: 200, height: 80 },
+      parentAutoLayout: {
+        display: "block",
+        sourceId: "parent-b",
+        boundingRect: { x: 0, y: 0, width: 200, height: 80 },
+      },
+      parentLayout: { display: "block" },
+    });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.parentDisplay).toBeUndefined();
+    expect(merged?.parentAutoLayout).toBeUndefined();
+    expect(merged?.parentBoundingRect).toBeUndefined();
+    expect(merged?.parentLayout).toBeUndefined();
+    // Order must not matter: putting the differing element last previously
+    // leaked it through as `base` for plain `...base` spread fields.
+    const mergedReversed = mixedElementFromSelection([b, a]);
+    expect(mergedReversed?.parentDisplay).toBeUndefined();
+    expect(mergedReversed?.parentAutoLayout).toBeUndefined();
+    expect(mergedReversed?.parentBoundingRect).toBeUndefined();
+    expect(mergedReversed?.parentLayout).toBeUndefined();
+  });
+
+  it("leaves parentDisplay/parentAutoLayout/parentLayout unchanged for a single-element selection", () => {
+    const parentLayout = { display: "grid", gridTemplateColumns: "1fr 1fr" };
+    const only = makeElement({
+      parentDisplay: "grid",
+      parentAutoLayout: {
+        display: "grid",
+        sourceId: "parent-1",
+        boundingRect: { x: 0, y: 0, width: 300, height: 100 },
+      },
+      parentLayout,
+    });
+    const merged = mixedElementFromSelection([only]);
+    expect(merged?.parentDisplay).toBe("grid");
+    expect(merged?.parentAutoLayout).toEqual(only.parentAutoLayout);
+    expect(merged?.parentLayout).toEqual(parentLayout);
+  });
+
+  // ── pendingNodeId (bug fix) ─────────────────────────────────────────────
+  // A merged selection has no single stable node id, same rationale as
+  // clearing `id`/`sourceId`.
+
+  it("clears pendingNodeId on the merged element instead of leaking it from the last element", () => {
+    const a = makeElement({ pendingNodeId: undefined });
+    const b = makeElement({ pendingNodeId: "draft-text-123" });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.pendingNodeId).toBeUndefined();
+  });
+
+  it("computes the bounding box as the union of all selected elements", () => {
+    const a = makeElement({
+      boundingRect: { x: 0, y: 0, width: 100, height: 40 },
+    });
+    const b = makeElement({
+      boundingRect: { x: 200, y: 50, width: 20, height: 20 },
+    });
+    const merged = mixedElementFromSelection([a, b]);
+    expect(merged?.boundingRect).toEqual({
+      x: 0,
+      y: 0,
+      width: 220,
+      height: 70,
+    });
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/selection-helpers.ts b/templates/design/app/components/design/edit-panel/selection-helpers.ts
index 859eb95e47..bc34acd063 100644
--- a/templates/design/app/components/design/edit-panel/selection-helpers.ts
+++ b/templates/design/app/components/design/edit-panel/selection-helpers.ts
@@ -12,6 +12,29 @@ export function sameOrMixed(values: string[]): string {
   return values.every((value) => value === first) ? first : MIXED_VALUE;
 }
 
+/**
+ * Structural equality via JSON — good enough for the small, JSON-serializable
+ * parent-layout snapshots (`parentDisplay`/`parentAutoLayout`/`parentLayout`)
+ * this is used for below; not intended as a general deep-equal.
+ */
+function sameStructure<T>(a: T | undefined, b: T | undefined): boolean {
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+
+/**
+ * Returns `value` when every element in `values` is structurally identical
+ * to it, else `undefined`. Used for object/optional-string fields where a
+ * `MIXED_VALUE` string sentinel doesn't apply (they aren't rendered as text)
+ * but silently leaking one arbitrary element's value across a selection with
+ * genuinely different values would still be wrong — see `parentDisplay` /
+ * `parentAutoLayout` / `parentLayout` below.
+ */
+function sameValueOrUndefined<T>(values: T[], candidate: T): T | undefined {
+  return values.every((value) => sameStructure(value, candidate))
+    ? candidate
+    : undefined;
+}
+
 export function mixedElementFromSelection(
   elements: ElementInfo[],
 ): ElementInfo | null {
@@ -60,11 +83,35 @@ export function mixedElementFromSelection(
       (element) => element.boundingRect.y + element.boundingRect.height,
     ),
   );
+  // Only report a shared component name when every selected element is the
+  // *same* named component instance (mirrors Figma: a multi-instance
+  // same-component selection still reads as a component). Anything else —
+  // including a component mixed with a plain element — collapses to
+  // undefined rather than a "Mixed" sentinel string: elementIsComponentSelection()
+  // in element-classification.ts only checks `.length > 0`, so leaking
+  // MIXED_VALUE ("Mixed", a non-empty string) through here would make a
+  // component+non-component multi-selection misreport as "is a component"
+  // (wrong purple icon/tint in SelectionHeader) instead of falling back to
+  // undefined the way an actual mismatch should.
+  const firstComponentName = elements[0]?.componentName;
+  const componentName =
+    firstComponentName &&
+    elements.every((element) => element.componentName === firstComponentName)
+      ? firstComponentName
+      : undefined;
+
   return {
     ...base,
     tagName: sameOrMixed(elements.map((element) => element.tagName)),
     id: undefined,
     sourceId: undefined,
+    // A merged/synthetic multi-selection has no single stable pending id
+    // either — clear it like id/sourceId above instead of leaking whichever
+    // element happened to be last, which isTextElement()'s nodeId-prefix
+    // fallback (for older payloads without primitiveKind) would otherwise
+    // read as if it belonged to the whole selection.
+    pendingNodeId: undefined,
+    componentName,
     selector: base.selector,
     classes: [],
     computedStyles,
@@ -87,5 +134,39 @@ export function mixedElementFromSelection(
     childElementCount: undefined,
     isFlexChild: elements.every((element) => element.isFlexChild),
     isFlexContainer: elements.every((element) => element.isFlexContainer),
+    // Same treatment as isFlexContainer above: isContainerElement() checks
+    // isFlexContainer || isGridContainer, so leaving isGridContainer to leak
+    // from `base` alone (via the ...base spread) let a mixed grid+non-grid
+    // selection misclassify as a uniform container based on selection order.
+    isGridContainer: elements.every((element) => element.isGridContainer),
+    // isParentFlex/isParentGrid/parentFlexDirection (element-classification.ts)
+    // read these three fields to decide whether LayoutContextProperties shows
+    // FlexChildControls/GridChildControls at all, and with which direction.
+    // Left unhandled, `...base` above leaked whichever element was selected
+    // LAST: multi-selecting elements from two different parents (e.g. one
+    // flex child + one plain block child, or two flex children with
+    // different flexDirection) rendered/hid those controls based on an
+    // arbitrary member of the selection, and any align-self/flex-grow edit
+    // made through them would apply to every selected element regardless of
+    // whether its own parent actually supports that property. Falling back
+    // to undefined when the selection's parents disagree matches the
+    // isFlexContainer/isGridContainer treatment above: hide the
+    // parent-relative controls rather than guess from one element.
+    parentDisplay: sameValueOrUndefined(
+      elements.map((element) => element.parentDisplay),
+      base.parentDisplay,
+    ),
+    parentAutoLayout: sameValueOrUndefined(
+      elements.map((element) => element.parentAutoLayout),
+      base.parentAutoLayout,
+    ),
+    parentBoundingRect: sameValueOrUndefined(
+      elements.map((element) => element.parentBoundingRect),
+      base.parentBoundingRect,
+    ),
+    parentLayout: sameValueOrUndefined(
+      elements.map((element) => element.parentLayout),
+      base.parentLayout,
+    ),
   };
 }
diff --git a/templates/design/app/components/design/edit-panel/stroke-properties.tsx b/templates/design/app/components/design/edit-panel/stroke-properties.tsx
index 7a9e4fb7e7..ed1947e548 100644
--- a/templates/design/app/components/design/edit-panel/stroke-properties.tsx
+++ b/templates/design/app/components/design/edit-panel/stroke-properties.tsx
@@ -33,10 +33,12 @@ import {
   outlineOffsetForPosition,
   readStrokeOutlinePosition,
   readTextStrokeStyle,
+  resolveRestoredStrokeStyle,
   resolveTextStrokeColor,
   roundToOneDecimal,
   strokeHiddenByColor,
   strokeIsVisible,
+  strokeShowPatch,
   textStrokeAddPatch,
   textStrokeIsVisible,
 } from "./position-helpers";
@@ -180,22 +182,21 @@ function StrokeLayerControl({
             // "none"/"solid". Writing "none" would lose a dashed/dotted
             // style permanently, since there is no round-trippable "unset"
             // for that keyword once it's overwritten.
-            const parsed = parseCssColor(color);
             if (visible) {
+              const parsed = parseCssColor(color);
               onStyleChange(
                 `${prefix}Color`,
                 parsed ? rgbaToCss(withColorOpacity(parsed, 0)) : "transparent",
               );
               return;
             }
-            const restoredColor = parsed
-              ? rgbaToCss(withColorOpacity(parsed, 100))
-              : "#000000";
-            onStyleChange(`${prefix}Color`, restoredColor);
-            if (styleValue === "none") onStyleChange(`${prefix}Style`, "solid");
-            onStyleChange(
-              `${prefix}Width`,
-              width === "0px" ? "1px" : width || "1px",
+            // Restore color/width/style as ONE commit (single undo step)
+            // rather than three sequential onStyleChange calls — see
+            // strokeShowPatch's doc comment.
+            commitStylePatch(
+              strokeShowPatch(prefix, color, width, styleValue),
+              onStyleChange,
+              onStylesChange,
             );
           }}
         >
@@ -384,7 +385,12 @@ export function StrokeProperties({
               commitStylePatch(
                 {
                   borderWidth: "1px",
-                  borderStyle: "solid",
+                  // Preserve a real style (dashed/dotted/etc) that survived
+                  // on a hidden-via-alpha border — only the outline branch
+                  // below used to do this; the border branch hardcoded
+                  // "solid" unconditionally, silently discarding it. See
+                  // resolveRestoredStrokeStyle's doc comment.
+                  borderStyle: resolveRestoredStrokeStyle(styles.borderStyle),
                   borderColor,
                 },
                 onStyleChange,
@@ -396,10 +402,9 @@ export function StrokeProperties({
               const outlineWidth = `${
                 Math.max(1, cssLengthNumber(styles.outlineWidth, 1)) + 1
               }px`;
-              const outlineStyle =
-                styles.outlineStyle === "none"
-                  ? "solid"
-                  : styles.outlineStyle || "solid";
+              const outlineStyle = resolveRestoredStrokeStyle(
+                styles.outlineStyle,
+              );
               const outlineColor = cssColorOrFallback(
                 styles.outlineColor || styles.borderColor,
                 "#000000",
diff --git a/templates/design/app/components/design/edit-panel/style-options.test.ts b/templates/design/app/components/design/edit-panel/style-options.test.ts
new file mode 100644
index 0000000000..be7c9436aa
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/style-options.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveLineHeight, sidesAreLinked } from "./style-options";
+
+// ─── resolveLineHeight — px-as-ratio misparse regression ────────────────────
+//
+// `resolveLineHeight` converts a CSS line-height into the unitless ratio the
+// Typography section's numeric field displays/edits. When the browser
+// reports a px-computed value (e.g. "19.2px" for a 16px font at ratio 1.2),
+// it must be divided by the font-size to recover the ratio. If the font-size
+// isn't available/valid, the px string must NOT fall through to the generic
+// `parseFloat` path below — that silently reads "19.2px" as the number 19.2
+// and would display it directly as if it were already a unitless ratio
+// (i.e. a "19.2" line-height instead of "1.2").
+describe("resolveLineHeight", () => {
+  it("divides a px-computed line-height by font-size to recover the ratio", () => {
+    expect(resolveLineHeight("19.2px", "16px")).toBe(1.2);
+  });
+
+  it("falls back to the default ratio instead of misreading the raw px number when font-size is missing", () => {
+    expect(resolveLineHeight("19.2px", undefined)).toBe(1.2);
+    expect(resolveLineHeight("19.2px", "")).toBe(1.2);
+  });
+
+  it("falls back to the default ratio when font-size is present but unparsable", () => {
+    expect(resolveLineHeight("19.2px", "not-a-size")).toBe(1.2);
+  });
+
+  it("falls back to the default ratio when font-size resolves to zero", () => {
+    expect(resolveLineHeight("19.2px", "0px")).toBe(1.2);
+  });
+
+  it("returns the default ratio for 'normal' or empty values", () => {
+    expect(resolveLineHeight("normal", "16px")).toBe(1.2);
+    expect(resolveLineHeight(undefined, "16px")).toBe(1.2);
+    expect(resolveLineHeight("", "16px")).toBe(1.2);
+  });
+
+  it("parses an already-unitless ratio directly", () => {
+    expect(resolveLineHeight("1.5", "16px")).toBe(1.5);
+  });
+});
+
+describe("sidesAreLinked", () => {
+  it("is true when all four sides parse to the same number", () => {
+    expect(
+      sidesAreLinked({ top: "4px", right: "4px", bottom: "4px", left: "4px" }),
+    ).toBe(true);
+  });
+
+  it("is false when any side differs", () => {
+    expect(
+      sidesAreLinked({ top: "4px", right: "8px", bottom: "4px", left: "4px" }),
+    ).toBe(false);
+  });
+
+  it("treats missing sides as 0", () => {
+    expect(
+      sidesAreLinked({ top: "", right: "0px", bottom: "0", left: "" }),
+    ).toBe(true);
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/style-options.ts b/templates/design/app/components/design/edit-panel/style-options.ts
index bb04a6ca0b..055a1655d6 100644
--- a/templates/design/app/components/design/edit-panel/style-options.ts
+++ b/templates/design/app/components/design/edit-panel/style-options.ts
@@ -74,6 +74,13 @@ export function resolveLineHeight(
     if (Number.isFinite(lhPx) && Number.isFinite(fsPx) && fsPx > 0) {
       return Math.round((lhPx / fsPx) * 100) / 100;
     }
+    // A px-computed line-height that we can't divide by a valid font-size
+    // (missing/invalid fontSize) must NOT fall through to the unitless-ratio
+    // parse below — `parseFloat("19.2px")` silently reads as `19.2`, which
+    // would render as a wildly wrong multiplier (e.g. "19.2") instead of a
+    // sane ~1.2 ratio. Fall back to the same default the empty/"normal" case
+    // above uses.
+    return 1.2;
   }
   const numeric = parseFloat(lh);
   return Number.isFinite(numeric) && numeric > 0 ? numeric : 1.2;
diff --git a/templates/design/app/components/design/edit-panel/typography-helpers.spec.ts b/templates/design/app/components/design/edit-panel/typography-helpers.spec.ts
new file mode 100644
index 0000000000..7e21f678b0
--- /dev/null
+++ b/templates/design/app/components/design/edit-panel/typography-helpers.spec.ts
@@ -0,0 +1,316 @@
+import { describe, expect, it } from "vitest";
+
+import { MIXED_VALUE } from "./selection-helpers";
+import {
+  displayFontFamilyName,
+  FONT_FAMILY_OPTIONS,
+  FONT_WEIGHT_OPTIONS,
+  isKnownFontWeight,
+  isTextDecorationLineActive,
+  nextTextDecorationLineValue,
+  parseTextDecorationLineTokens,
+  resolveFixedResizeDimension,
+  resolveFontFamilyFieldValue,
+  resolveFontFamilySelectValue,
+  splitFontFamilyList,
+  TEXT_CASE_OPTIONS,
+} from "./typography-helpers";
+
+// ---------------------------------------------------------------------------
+// splitFontFamilyList / resolveFontFamilySelectValue — font-family stack
+// parsing must be case-insensitive and quote/whitespace tolerant so a
+// computed "Inter", "'Inter', sans-serif", or " inter , sans-serif " all
+// resolve to the same known FONT_FAMILY_OPTIONS entry.
+// ---------------------------------------------------------------------------
+
+describe("splitFontFamilyList", () => {
+  it("splits a plain comma-separated stack", () => {
+    expect(splitFontFamilyList("Inter, sans-serif")).toEqual([
+      "Inter",
+      "sans-serif",
+    ]);
+  });
+
+  it("strips single and double quotes around family names", () => {
+    expect(splitFontFamilyList("'Inter', sans-serif")).toEqual([
+      "Inter",
+      "sans-serif",
+    ]);
+    expect(splitFontFamilyList('"Playfair Display", serif')).toEqual([
+      "Playfair Display",
+      "serif",
+    ]);
+  });
+
+  it("does not split on a comma inside a quoted family name", () => {
+    expect(splitFontFamilyList('"Foo, Bar", serif')).toEqual([
+      "Foo, Bar",
+      "serif",
+    ]);
+  });
+
+  it("returns an empty array for undefined/empty input", () => {
+    expect(splitFontFamilyList(undefined)).toEqual([]);
+    expect(splitFontFamilyList("")).toEqual([]);
+    expect(splitFontFamilyList("   ")).toEqual([]);
+  });
+});
+
+describe("resolveFontFamilySelectValue", () => {
+  it("resolves an unquoted stack to the matching option", () => {
+    expect(resolveFontFamilySelectValue("Inter, sans-serif")).toBe(
+      "'Inter', sans-serif",
+    );
+  });
+
+  it("resolves a quoted stack to the same option", () => {
+    expect(resolveFontFamilySelectValue("'Inter', sans-serif")).toBe(
+      "'Inter', sans-serif",
+    );
+  });
+
+  it("is case-insensitive", () => {
+    expect(resolveFontFamilySelectValue("INTER, SANS-SERIF")).toBe(
+      "'Inter', sans-serif",
+    );
+    expect(resolveFontFamilySelectValue("inter, sans-serif")).toBe(
+      "'Inter', sans-serif",
+    );
+  });
+
+  it("tolerates extra whitespace around family names", () => {
+    expect(resolveFontFamilySelectValue("  Inter  ,   sans-serif  ")).toBe(
+      "'Inter', sans-serif",
+    );
+  });
+
+  it("falls back to matching on the first family when the full stack differs", () => {
+    // e.g. a computed style tail that differs from our canonical fallback
+    // stack should still resolve by first-family name.
+    expect(resolveFontFamilySelectValue("Inter, Arial, sans-serif")).toBe(
+      "'Inter', sans-serif",
+    );
+  });
+
+  it("returns the generic default for an empty/undefined value", () => {
+    expect(resolveFontFamilySelectValue(undefined)).toBe("sans-serif");
+    expect(resolveFontFamilySelectValue("")).toBe("sans-serif");
+  });
+
+  it("passes through an unrecognized font stack unchanged (no silent default)", () => {
+    // Previously any unmatched value should surface as its own trimmed raw
+    // string, not silently fall back to the first FONT_FAMILY_OPTIONS entry.
+    expect(resolveFontFamilySelectValue("Roboto, sans-serif")).toBe(
+      "Roboto, sans-serif",
+    );
+    expect(resolveFontFamilySelectValue(FONT_FAMILY_OPTIONS[0].value)).not.toBe(
+      "Roboto, sans-serif",
+    );
+  });
+});
+
+describe("displayFontFamilyName", () => {
+  it("maps known generic families to friendly labels", () => {
+    expect(displayFontFamilyName("sans-serif")).toBe("Sans Serif");
+    expect(displayFontFamilyName("serif")).toBe("Serif");
+    expect(displayFontFamilyName("monospace")).toBe("Monospace");
+    expect(displayFontFamilyName("system-ui")).toBe("System UI");
+    expect(displayFontFamilyName("-apple-system")).toBe("System UI");
+    expect(displayFontFamilyName("BlinkMacSystemFont")).toBe("Apple System");
+  });
+
+  it("returns the first family name verbatim for an unknown font", () => {
+    expect(displayFontFamilyName("Roboto, sans-serif")).toBe("Roboto");
+  });
+
+  it("falls back to a generic label when there is no value", () => {
+    expect(displayFontFamilyName(undefined)).toBe("Sans Serif");
+    expect(displayFontFamilyName("")).toBe("Sans Serif");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveFontFamilyFieldValue — mixed-selection safety. A multi-selection
+// spanning different fonts must resolve to the MIXED_VALUE sentinel so the
+// caller can render it as a disabled placeholder instead of a normal,
+// clickable option (bug: previously this coincidentally worked because
+// MIXED_VALUE's literal text happens to be "Mixed", but nothing marked it as
+// non-selectable — see typography-properties.tsx for the fix).
+// ---------------------------------------------------------------------------
+
+describe("resolveFontFamilyFieldValue", () => {
+  it("returns the MIXED_VALUE sentinel unchanged for a mixed selection", () => {
+    expect(resolveFontFamilyFieldValue(MIXED_VALUE)).toBe(MIXED_VALUE);
+  });
+
+  it("resolves a non-mixed value exactly like resolveFontFamilySelectValue", () => {
+    expect(resolveFontFamilyFieldValue("Inter, sans-serif")).toBe(
+      resolveFontFamilySelectValue("Inter, sans-serif"),
+    );
+    expect(resolveFontFamilyFieldValue(undefined)).toBe(
+      resolveFontFamilySelectValue(undefined),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isKnownFontWeight — every FONT_WEIGHT_OPTIONS notch must be recognized;
+// a variable-font weight outside those nine must not be, so the caller can
+// inject a synthesized option (bug: previously an off-notch weight like
+// "550" left the font-weight Select's value matching no item — rendered
+// blank even though the real weight was still applied).
+// ---------------------------------------------------------------------------
+
+describe("isKnownFontWeight", () => {
+  it("recognizes every standard notch", () => {
+    for (const option of FONT_WEIGHT_OPTIONS) {
+      expect(isKnownFontWeight(option.value)).toBe(true);
+    }
+  });
+
+  it("rejects an off-notch variable-font weight", () => {
+    expect(isKnownFontWeight("550")).toBe(false);
+    expect(isKnownFontWeight("650")).toBe(false);
+  });
+
+  it("rejects a non-numeric keyword the computed style didn't normalize", () => {
+    expect(isKnownFontWeight("bold")).toBe(false);
+    expect(isKnownFontWeight("normal")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveFixedResizeDimension — converting auto-width/auto-height text to
+// "fixed" must preserve the element's real authored size when present, and
+// otherwise fall back to its actual current rendered size (boundingRect),
+// never an arbitrary hardcoded constant (bug: the prior "200px"/"48px"
+// defaults caused a visible size jump on every auto -> fixed conversion for
+// a box that had never been explicitly sized).
+// ---------------------------------------------------------------------------
+
+describe("resolveFixedResizeDimension", () => {
+  it("preserves an existing authored (non-auto) size verbatim", () => {
+    expect(resolveFixedResizeDimension("240px", false, 999)).toBe("240px");
+  });
+
+  it("falls back to the current rendered bounding size when auto", () => {
+    expect(resolveFixedResizeDimension(undefined, true, 340)).toBe("340px");
+    expect(resolveFixedResizeDimension("max-content", true, 128.4)).toBe(
+      "128px",
+    );
+  });
+
+  it("rounds a fractional bounding size to the nearest whole pixel", () => {
+    expect(resolveFixedResizeDimension(undefined, true, 199.6)).toBe("200px");
+  });
+
+  it("never emits a zero or negative fallback size", () => {
+    expect(resolveFixedResizeDimension(undefined, true, 0)).toBe("1px");
+    expect(resolveFixedResizeDimension(undefined, true, -5)).toBe("1px");
+  });
+
+  it("treats a non-finite bounding size as zero rather than NaN", () => {
+    expect(resolveFixedResizeDimension(undefined, true, Number.NaN)).toBe(
+      "1px",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseTextDecorationLineTokens / isTextDecorationLineActive /
+// nextTextDecorationLineValue — underline/strikethrough toggle state must be
+// read off the clean `textDecorationLine` computed longhand OR the composite
+// `textDecoration` shorthand (both can appear depending on caller), and a
+// mixed selection must never be misread as "this line is active".
+// ---------------------------------------------------------------------------
+
+describe("parseTextDecorationLineTokens", () => {
+  it("returns an empty set for none/undefined/empty", () => {
+    expect(parseTextDecorationLineTokens(undefined).size).toBe(0);
+    expect(parseTextDecorationLineTokens("").size).toBe(0);
+    expect(parseTextDecorationLineTokens("none").size).toBe(0);
+  });
+
+  it("parses a single line keyword", () => {
+    expect(parseTextDecorationLineTokens("underline")).toEqual(
+      new Set(["underline"]),
+    );
+    expect(parseTextDecorationLineTokens("line-through")).toEqual(
+      new Set(["line-through"]),
+    );
+  });
+
+  it("parses multiple space-separated line keywords", () => {
+    expect(parseTextDecorationLineTokens("underline line-through")).toEqual(
+      new Set(["underline", "line-through"]),
+    );
+  });
+
+  it("picks the line keyword out of a full shorthand computed string", () => {
+    expect(
+      parseTextDecorationLineTokens("underline solid rgb(0, 0, 0)"),
+    ).toEqual(new Set(["underline"]));
+  });
+});
+
+describe("isTextDecorationLineActive", () => {
+  it("reports true only when the line is present", () => {
+    expect(isTextDecorationLineActive("underline", "underline")).toBe(true);
+    expect(isTextDecorationLineActive("underline", "line-through")).toBe(false);
+    expect(isTextDecorationLineActive("none", "underline")).toBe(false);
+    expect(isTextDecorationLineActive(undefined, "underline")).toBe(false);
+  });
+
+  it("treats a mixed-selection sentinel as inactive, never active", () => {
+    expect(isTextDecorationLineActive(MIXED_VALUE, "underline")).toBe(false);
+    expect(isTextDecorationLineActive(MIXED_VALUE, "line-through")).toBe(false);
+  });
+});
+
+describe("nextTextDecorationLineValue", () => {
+  it("turns a line on from none", () => {
+    expect(nextTextDecorationLineValue("none", "underline")).toBe("underline");
+    expect(nextTextDecorationLineValue(undefined, "underline")).toBe(
+      "underline",
+    );
+  });
+
+  it("turns a line off, falling back to none when nothing is left active", () => {
+    expect(nextTextDecorationLineValue("underline", "underline")).toBe("none");
+  });
+
+  it("adds a second line without clobbering the first", () => {
+    expect(nextTextDecorationLineValue("underline", "line-through")).toBe(
+      "underline line-through",
+    );
+  });
+
+  it("removes one of two active lines, keeping the other", () => {
+    expect(
+      nextTextDecorationLineValue("underline line-through", "underline"),
+    ).toBe("line-through");
+  });
+
+  it("treats a mixed selection as no lines active, so the click sets it uniformly", () => {
+    expect(nextTextDecorationLineValue(MIXED_VALUE, "underline")).toBe(
+      "underline",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TEXT_CASE_OPTIONS — the four text-transform notches the Case control
+// exposes must match the CSS keywords exactly (they are committed verbatim
+// through onStyleChange("textTransform", value)).
+// ---------------------------------------------------------------------------
+
+describe("TEXT_CASE_OPTIONS", () => {
+  it("exposes exactly the four supported text-transform keywords", () => {
+    expect(TEXT_CASE_OPTIONS.map((option) => option.value)).toEqual([
+      "none",
+      "uppercase",
+      "lowercase",
+      "capitalize",
+    ]);
+  });
+});
diff --git a/templates/design/app/components/design/edit-panel/typography-helpers.ts b/templates/design/app/components/design/edit-panel/typography-helpers.ts
index 4f638a7715..2012f42341 100644
--- a/templates/design/app/components/design/edit-panel/typography-helpers.ts
+++ b/templates/design/app/components/design/edit-panel/typography-helpers.ts
@@ -1,3 +1,5 @@
+import { isMixedValue, MIXED_VALUE } from "./selection-helpers";
+
 export const FONT_FAMILY_OPTIONS = [
   { value: "inherit", key: "inherit" },
   { value: "sans-serif", key: "sansSerif" },
@@ -21,8 +23,38 @@ export const FONT_WEIGHT_OPTIONS = [
   { value: "900", key: "black" },
 ] as const;
 
+/**
+ * True when `value` matches one of the nine standard FONT_WEIGHT_OPTIONS
+ * notches. Variable-font weights (e.g. "550") or a keyword the browser
+ * didn't normalize are real but "unknown" — callers should inject a
+ * synthesized option for these instead of silently rendering a Select whose
+ * value matches no item (blank dropdown, current weight still applied).
+ */
+export function isKnownFontWeight(value: string): boolean {
+  return FONT_WEIGHT_OPTIONS.some((option) => option.value === value);
+}
+
 export type TextResizeMode = "auto-width" | "auto-height" | "fixed";
 
+/**
+ * Fallback dimension used when converting a text box from an auto (width or
+ * height) resize mode to "fixed". When the box already has a real authored
+ * size (not auto), that size is preserved verbatim. Otherwise this must use
+ * the element's actual current on-screen size (`boundingSizePx`, from
+ * `boundingRect`) rather than an arbitrary constant — converting auto-width
+ * text that currently renders at, say, 340px wide to "fixed" must keep it at
+ * ~340px, not silently snap it to a hardcoded default and visibly resize it.
+ */
+export function resolveFixedResizeDimension(
+  authoredValue: string | undefined,
+  isAuto: boolean,
+  boundingSizePx: number,
+): string {
+  if (authoredValue && !isAuto) return authoredValue;
+  const size = Number.isFinite(boundingSizePx) ? Math.round(boundingSizePx) : 0;
+  return `${Math.max(1, size)}px`;
+}
+
 function cleanFontFamilyName(value: string): string {
   const trimmed = value.trim();
   if (
@@ -115,3 +147,126 @@ export function resolveFontFamilySelectValue(
   );
   return firstFamilyOption?.value ?? raw;
 }
+
+/**
+ * Mixed-selection-safe wrapper around resolveFontFamilySelectValue.
+ *
+ * A multi-selection spanning different font families injects the MIXED_VALUE
+ * sentinel string ("Mixed") into computedStyles.fontFamily (see
+ * mixedElementFromSelection/sameOrMixed in selection-helpers.ts). Feeding
+ * that sentinel straight into resolveFontFamilySelectValue happened to
+ * resolve back to the literal string "Mixed" (no option's normalized stack
+ * or first-family matches, so the raw fallback wins) — but only by
+ * coincidence, since MIXED_VALUE itself is "Mixed". Callers must not rely on
+ * that coincidence: without an explicit mixed check the caller has no signal
+ * to render the value as a disabled placeholder, so "Mixed" ends up as a
+ * normal, clickable SelectItem the user could select and commit as a literal
+ * (nonsensical) `font-family: Mixed` style. This wrapper makes the mixed
+ * state explicit so callers can branch on it the same way they already do
+ * for fontWeight/fontSize/lineHeight/letterSpacing.
+ */
+export function resolveFontFamilyFieldValue(
+  computedFontFamily: string | undefined,
+): string {
+  if (isMixedValue(computedFontFamily)) return MIXED_VALUE;
+  return resolveFontFamilySelectValue(computedFontFamily);
+}
+
+/**
+ * PERSISTENCE GOTCHA — commit text-decoration toggles through "text-decoration"
+ * (the shorthand), never "text-decoration-line" (the longhand).
+ *
+ * The persisted-source style patcher (`applyStyleEdit`/`normalizeStyleProperty`
+ * in `shared/code-layer.ts`) only writes properties on its `VisualStyleProperty`
+ * allow-list. That list has "text-decoration" but does NOT have
+ * "text-decoration-line" — so an `onStyleChange("textDecorationLine", ...)`
+ * call would normalize to the unlisted kebab name, miss the allow-list, and
+ * return "unsupported": the live iframe preview (which patches the DOM
+ * directly via `element.style.setProperty`, no allow-list) would still
+ * visually flip on the toggle tick, but the change would never reach the
+ * saved HTML source and would revert on the next load/reparse — a
+ * works-in-preview, doesn't-persist bug. The shorthand happily accepts a bare
+ * line-keyword list ("underline", "underline line-through", "none") as its
+ * value, which is valid CSS and *is* on the allow-list, so every helper below
+ * reads/writes through "text-decoration" (property name "textDecoration" from
+ * call sites) even though the bridge separately exposes the clean longhand
+ * `textDecorationLine` computed value for reading current state.
+ */
+export type TextDecorationLineToken = "underline" | "line-through" | "overline";
+
+const TEXT_DECORATION_LINE_TOKENS: readonly TextDecorationLineToken[] = [
+  "underline",
+  "line-through",
+  "overline",
+];
+
+/**
+ * Parses a text-decoration-line-ish CSS value ("none", "underline",
+ * "underline line-through", or even the full shorthand computed string like
+ * "underline solid rgb(0, 0, 0)") into the set of line tokens present. Works
+ * on either the clean longhand or the composite shorthand since it just
+ * looks for each known keyword as a whole word.
+ */
+export function parseTextDecorationLineTokens(
+  value: string | undefined,
+): Set<TextDecorationLineToken> {
+  const tokens = new Set<TextDecorationLineToken>();
+  if (!value) return tokens;
+  for (const token of TEXT_DECORATION_LINE_TOKENS) {
+    if (new RegExp(`(?:^|\\s)${token}(?:\\s|$)`).test(value)) {
+      tokens.add(token);
+    }
+  }
+  return tokens;
+}
+
+/**
+ * True when `line` is active in `value`. A mixed-selection sentinel (see
+ * `isMixedValue`) always reads as inactive — same convention every other
+ * mixed-aware field in this panel uses (fontFamily/fontWeight/fontSize/...):
+ * an indeterminate state renders as "off", not as a guess at one element's
+ * value.
+ */
+export function isTextDecorationLineActive(
+  value: string | undefined,
+  line: TextDecorationLineToken,
+): boolean {
+  if (isMixedValue(value)) return false;
+  return parseTextDecorationLineTokens(value).has(line);
+}
+
+/**
+ * Returns the "text-decoration" value to commit after toggling `line` on/off
+ * against the element's current decoration-line state. A mixed selection is
+ * treated as "no lines active yet" so the first click always turns the
+ * toggled line ON uniformly across every selected element — matching how
+ * every other Select-driven field here (fontFamily, fontWeight, ...)
+ * overwrites a mixed selection with one explicit value instead of trying to
+ * merge each element's own prior state.
+ */
+export function nextTextDecorationLineValue(
+  currentValue: string | undefined,
+  line: TextDecorationLineToken,
+): string {
+  const current = isMixedValue(currentValue)
+    ? new Set<TextDecorationLineToken>()
+    : parseTextDecorationLineTokens(currentValue);
+  if (current.has(line)) current.delete(line);
+  else current.add(line);
+  return current.size === 0 ? "none" : Array.from(current).join(" ");
+}
+
+/**
+ * text-transform options (Figma's "Case" control). Unlike font-family/weight,
+ * "text-transform" is already on the persisted-source `VisualStyleProperty`
+ * allow-list under its own name, so callers can commit it directly with
+ * `onStyleChange("textTransform", value)` — no shorthand workaround needed.
+ */
+export const TEXT_CASE_OPTIONS = [
+  { value: "none", key: "none" },
+  { value: "uppercase", key: "uppercase" },
+  { value: "lowercase", key: "lowercase" },
+  { value: "capitalize", key: "capitalize" },
+] as const;
+
+export type TextCaseValue = (typeof TEXT_CASE_OPTIONS)[number]["value"];
diff --git a/templates/design/app/components/design/edit-panel/typography-properties.tsx b/templates/design/app/components/design/edit-panel/typography-properties.tsx
index d6d4f497bb..162232951b 100644
--- a/templates/design/app/components/design/edit-panel/typography-properties.tsx
+++ b/templates/design/app/components/design/edit-panel/typography-properties.tsx
@@ -10,9 +10,15 @@ import {
   IconLayoutAlignMiddle,
   IconLayoutAlignTop,
   IconLetterCase,
+  IconLetterCaseLower,
+  IconLetterCaseToggle,
+  IconLetterCaseUpper,
   IconLetterSpacing,
   IconLineHeight,
   IconSquare,
+  IconStrikethrough,
+  IconTextSize,
+  IconUnderline,
 } from "@tabler/icons-react";
 import { useState } from "react";
 
@@ -45,12 +51,22 @@ import { PanelSection } from "./panel-primitives";
 import { roundToOneDecimal } from "./position-helpers";
 import { isMixedValue, MIXED_VALUE } from "./selection-helpers";
 import type { StyleChangeHandler } from "./style-change-types";
-import { parseNumericValue, resolveLineHeight } from "./style-options";
+import {
+  optionValue,
+  parseNumericValue,
+  resolveLineHeight,
+} from "./style-options";
 import {
   displayFontFamilyName,
   FONT_FAMILY_OPTIONS,
   FONT_WEIGHT_OPTIONS,
-  resolveFontFamilySelectValue,
+  isKnownFontWeight,
+  isTextDecorationLineActive,
+  nextTextDecorationLineValue,
+  resolveFixedResizeDimension,
+  resolveFontFamilyFieldValue,
+  TEXT_CASE_OPTIONS,
+  type TextDecorationLineToken,
   type TextResizeMode,
 } from "./typography-helpers";
 
@@ -90,14 +106,76 @@ function TextResizeControls({
   );
 }
 
+type TypographyDetailsTab = "basics" | "details";
+
+/**
+ * The tab bar's "Basics"/"Details" buttons are a real tab list (not the
+ * static, non-interactive spans this replaced) — see the module-level note
+ * near `TypographyDetailsPopover` for why the third "Variable" tab was
+ * dropped instead of wired up.
+ */
+function TypographyDetailsTabButton({
+  label,
+  active,
+  onClick,
+}: {
+  label: string;
+  active: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      role="tab"
+      aria-selected={active}
+      onClick={onClick}
+      className={cn(
+        "cursor-pointer rounded px-2.5 py-1 !text-[11px] font-medium text-muted-foreground",
+        active &&
+          "bg-[var(--design-editor-panel-raised-bg)] font-semibold text-foreground",
+      )}
+    >
+      {label}
+    </button>
+  );
+}
+
+/**
+ * Text decoration (underline/strikethrough) and case (none/uppercase/
+ * lowercase/capitalize) live here, in the popover's "Details" tab, rather
+ * than as a 5th always-visible row in the compact panel above — matching
+ * Figma, which tucks these into the same type-details flyout instead of the
+ * always-on compact type row. Deliberately NOT duplicating line-height /
+ * letter-spacing here even though Figma's flyout also shows them: this
+ * panel's compact row (see TypographyProperties below) already exposes both
+ * as always-visible, directly-editable fields, so a second live-editable
+ * copy of the exact same property here would be redundant clutter and an
+ * easy source of two-inputs-fighting-the-same-value bugs, not a feature.
+ */
 function TypographyDetailsPopover({
   resizeMode,
   onResizeModeChange,
+  underlineActive,
+  strikethroughActive,
+  onToggleUnderline,
+  onToggleStrikethrough,
+  textCase,
+  textCaseIsMixed,
+  onTextCaseChange,
 }: {
   resizeMode: TextResizeMode;
   onResizeModeChange: (mode: TextResizeMode) => void;
+  underlineActive: boolean;
+  strikethroughActive: boolean;
+  onToggleUnderline: () => void;
+  onToggleStrikethrough: () => void;
+  textCase: string;
+  textCaseIsMixed: boolean;
+  onTextCaseChange: (value: string) => void;
 }) {
+  const t = useT();
   const [open, setOpen] = useState(false);
+  const [activeTab, setActiveTab] = useState<TypographyDetailsTab>("basics");
 
   return (
     <Popover open={open} onOpenChange={setOpen}>
@@ -131,32 +209,99 @@ function TypographyDetailsPopover({
         className="z-[100010] w-[360px] rounded-xl border-[var(--design-editor-control-border)] bg-[var(--design-editor-panel-bg)] p-0 text-foreground shadow-2xl"
       >
         <div className="flex items-center gap-1 border-b border-[var(--design-editor-control-border)] p-2.5">
-          <div className="flex rounded-md bg-[var(--design-editor-control-bg)] p-0.5">
-            <span className="rounded bg-[var(--design-editor-panel-raised-bg)] px-2.5 py-1 !text-[11px] font-semibold text-foreground">
-              {"Basics" /* i18n-ignore design typography details tab */}
-            </span>
-            <span className="px-2.5 py-1 !text-[11px] font-medium text-muted-foreground">
-              {"Details" /* i18n-ignore design typography details tab */}
-            </span>
-            <span className="px-2.5 py-1 !text-[11px] font-medium text-muted-foreground">
-              {"Variable" /* i18n-ignore design typography details tab */}
-            </span>
+          <div
+            role="tablist"
+            className="flex rounded-md bg-[var(--design-editor-control-bg)] p-0.5"
+          >
+            <TypographyDetailsTabButton
+              label={t("editPanel.typographyDetails.basicsTab")}
+              active={activeTab === "basics"}
+              onClick={() => setActiveTab("basics")}
+            />
+            <TypographyDetailsTabButton
+              label={t("editPanel.typographyDetails.detailsTab")}
+              active={activeTab === "details"}
+              onClick={() => setActiveTab("details")}
+            />
           </div>
         </div>
-        <div className="space-y-3 p-4 !text-[11px]">
-          <div className="flex h-20 items-center justify-center rounded-md bg-[var(--design-editor-control-bg)] text-[18px] text-muted-foreground/80">
-            {"Preview" /* i18n-ignore design typography details preview */}
+        {activeTab === "basics" ? (
+          <div className="space-y-3 p-4 !text-[11px]">
+            <div className="flex h-20 items-center justify-center rounded-md bg-[var(--design-editor-control-bg)] text-[18px] text-muted-foreground/80">
+              {"Preview" /* i18n-ignore design typography details preview */}
+            </div>
+            <div className="flex items-center justify-between gap-3">
+              <span className="!text-[11px] font-medium text-muted-foreground">
+                {"Text box" /* i18n-ignore design typography details label */}
+              </span>
+              <TextResizeControls
+                resizeMode={resizeMode}
+                onResizeModeChange={onResizeModeChange}
+              />
+            </div>
           </div>
-          <div className="flex items-center justify-between gap-3">
-            <span className="!text-[11px] font-medium text-muted-foreground">
-              {"Text box" /* i18n-ignore design typography details label */}
-            </span>
-            <TextResizeControls
-              resizeMode={resizeMode}
-              onResizeModeChange={onResizeModeChange}
-            />
+        ) : (
+          <div className="space-y-3 p-4 !text-[11px]">
+            <div className="flex items-center justify-between gap-3">
+              <span className="!text-[11px] font-medium text-muted-foreground">
+                {t("editPanel.typographyDetails.decorationLabel")}
+              </span>
+              <InspectorSegment>
+                <InspectorIconButton
+                  label={t("editPanel.textDecorations.underline")}
+                  shortcut="⌘U"
+                  active={underlineActive}
+                  onClick={onToggleUnderline}
+                >
+                  <IconUnderline className="size-3.5" />
+                </InspectorIconButton>
+                <InspectorIconButton
+                  label={t("editPanel.textDecorations.strikethrough")}
+                  shortcut="⌘⇧X"
+                  active={strikethroughActive}
+                  onClick={onToggleStrikethrough}
+                >
+                  <IconStrikethrough className="size-3.5" />
+                </InspectorIconButton>
+              </InspectorSegment>
+            </div>
+            <div className="flex items-center justify-between gap-3">
+              <span className="!text-[11px] font-medium text-muted-foreground">
+                {t("editPanel.typographyDetails.caseLabel")}
+              </span>
+              <InspectorSegment>
+                <InspectorIconButton
+                  label={t("editPanel.textCases.none")}
+                  active={!textCaseIsMixed && textCase === "none"}
+                  onClick={() => onTextCaseChange("none")}
+                >
+                  <IconLetterCase className="size-3.5" />
+                </InspectorIconButton>
+                <InspectorIconButton
+                  label={t("editPanel.textCases.uppercase")}
+                  active={!textCaseIsMixed && textCase === "uppercase"}
+                  onClick={() => onTextCaseChange("uppercase")}
+                >
+                  <IconLetterCaseUpper className="size-3.5" />
+                </InspectorIconButton>
+                <InspectorIconButton
+                  label={t("editPanel.textCases.lowercase")}
+                  active={!textCaseIsMixed && textCase === "lowercase"}
+                  onClick={() => onTextCaseChange("lowercase")}
+                >
+                  <IconLetterCaseLower className="size-3.5" />
+                </InspectorIconButton>
+                <InspectorIconButton
+                  label={t("editPanel.textCases.capitalize")}
+                  active={!textCaseIsMixed && textCase === "capitalize"}
+                  onClick={() => onTextCaseChange("capitalize")}
+                >
+                  <IconLetterCaseToggle className="size-3.5" />
+                </InspectorIconButton>
+              </InspectorSegment>
+            </div>
           </div>
-        </div>
+        )}
       </PopoverContent>
     </Popover>
   );
@@ -176,24 +321,6 @@ export function TypographyProperties({
     value: option.value,
     label: t(`editPanel.fontFamilies.${option.key}`),
   }));
-  const fontFamily = resolveFontFamilySelectValue(styles.fontFamily);
-  const fontFamilyOptions = FONT_FAMILY_OPTIONS.some(
-    (option) => option.value === fontFamily,
-  )
-    ? baseFontFamilyOptions
-    : [
-        {
-          value: fontFamily,
-          label: displayFontFamilyName(styles.fontFamily || fontFamily),
-        },
-        ...baseFontFamilyOptions,
-      ];
-  const fontWeightOptions = FONT_WEIGHT_OPTIONS.map((option) => ({
-    value: option.value,
-    label: t(`editPanel.fontWeights.${option.key}`),
-  }));
-  const textAlign = styles.textAlign || "left";
-
   // Mixed-selection guards: a multi-selection with differing values injects
   // the MIXED_VALUE sentinel string into these computedStyles fields (see
   // mixedElementFromSelection/sameOrMixed). Parsing that sentinel with
@@ -202,10 +329,75 @@ export function TypographyProperties({
   // fabricated 0 (size), 1.2 (line-height), or blank (tracking) rather than
   // the Mixed state ScrubInput already knows how to render — same pattern as
   // the rotation field above.
+  const fontFamilyIsMixed = isMixedValue(styles.fontFamily);
   const fontWeightIsMixed = isMixedValue(styles.fontWeight);
   const fontSizeIsMixed = isMixedValue(styles.fontSize);
   const lineHeightIsMixed = isMixedValue(styles.lineHeight);
   const letterSpacingIsMixed = isMixedValue(styles.letterSpacing);
+  const textTransformIsMixed = isMixedValue(styles.textTransform);
+
+  // Text decoration (underline/strikethrough) reads through the bridge's
+  // clean `textDecorationLine` computed longhand (never the composite
+  // `textDecoration` shorthand string, which also carries style/color) but
+  // WRITES commit through the "textDecoration" property name — see
+  // nextTextDecorationLineValue's doc comment in typography-helpers.ts for
+  // why the longhand isn't on the persisted-source style allow-list.
+  const underlineActive = isTextDecorationLineActive(
+    styles.textDecorationLine,
+    "underline",
+  );
+  const strikethroughActive = isTextDecorationLineActive(
+    styles.textDecorationLine,
+    "line-through",
+  );
+  const toggleTextDecorationLine = (line: TextDecorationLineToken) => {
+    onStyleChange(
+      "textDecoration",
+      nextTextDecorationLineValue(styles.textDecorationLine, line),
+    );
+  };
+  // Mixed-selection guard mirrors fontWeight/fontFamily above: an
+  // indeterminate case across the selection renders with none of the four
+  // options highlighted rather than guessing one element's value.
+  const textCase = textTransformIsMixed
+    ? "none"
+    : optionValue(TEXT_CASE_OPTIONS, styles.textTransform, "none");
+  const setTextCase = (value: string) => onStyleChange("textTransform", value);
+
+  // resolveFontFamilyFieldValue returns the MIXED_VALUE sentinel unchanged
+  // when the selection differs so the Select below can render it as an
+  // explicit disabled placeholder (matching fontWeight's pattern just below)
+  // instead of a normal, clickable option that could commit the literal
+  // string "Mixed" as a font-family value.
+  const fontFamily = resolveFontFamilyFieldValue(styles.fontFamily);
+  const fontFamilyOptions = fontFamilyIsMixed
+    ? baseFontFamilyOptions
+    : FONT_FAMILY_OPTIONS.some((option) => option.value === fontFamily)
+      ? baseFontFamilyOptions
+      : [
+          {
+            value: fontFamily,
+            label: displayFontFamilyName(styles.fontFamily || fontFamily),
+          },
+          ...baseFontFamilyOptions,
+        ];
+  const baseFontWeightOptions = FONT_WEIGHT_OPTIONS.map((option) => ({
+    value: option.value,
+    label: t(`editPanel.fontWeights.${option.key}`),
+  }));
+  // Non-mixed but not one of the nine standard notches (e.g. a variable-font
+  // weight like "550") needs the same synthesized-option treatment as an
+  // unknown font family — otherwise the Select's value matches no item and
+  // renders blank even though the real weight is still applied.
+  const currentFontWeight = styles.fontWeight || "400";
+  const fontWeightOptions =
+    fontWeightIsMixed || isKnownFontWeight(currentFontWeight)
+      ? baseFontWeightOptions
+      : [
+          { value: currentFontWeight, label: currentFontWeight },
+          ...baseFontWeightOptions,
+        ];
+  const textAlign = styles.textAlign || "left";
 
   // M1 · Text resizing mode (auto-width / auto-height / fixed). the design
   // editor's text nodes always expose this segment. Read authored
@@ -240,8 +432,20 @@ export function TypographyProperties({
       : !heightIsAuto && !widthIsAuto
         ? "fixed"
         : "auto-height";
-  const currentWidth = styles.width && !widthIsAuto ? styles.width : "200px";
-  const currentHeight = styles.height && !heightIsAuto ? styles.height : "48px";
+  // Fall back to the element's actual current on-screen size (not an
+  // arbitrary constant) when there's no real authored size yet — converting
+  // auto-width/auto-height text to "fixed" must preserve its current
+  // rendered size instead of visibly snapping it to a hardcoded default.
+  const currentWidth = resolveFixedResizeDimension(
+    styles.width,
+    widthIsAuto,
+    element.boundingRect.width,
+  );
+  const currentHeight = resolveFixedResizeDimension(
+    styles.height,
+    heightIsAuto,
+    element.boundingRect.height,
+  );
   const setResizeMode = (mode: TextResizeMode) => {
     if (mode === "auto-width") {
       onStyleChange("width", "max-content");
@@ -318,6 +522,15 @@ export function TypographyProperties({
             <SelectValue />
           </SelectTrigger>
           <SelectContent>
+            {fontFamilyIsMixed ? (
+              <SelectItem
+                value={MIXED_VALUE}
+                disabled
+                className="!text-[11px] text-muted-foreground"
+              >
+                {MIXED_VALUE}
+              </SelectItem>
+            ) : null}
             {fontFamilyOptions.map((opt) => (
               <SelectItem
                 key={opt.value}
@@ -334,7 +547,7 @@ export function TypographyProperties({
       {/* Row 2: weight + size side by side */}
       <div className="grid grid-cols-2 gap-1.5">
         <Select
-          value={fontWeightIsMixed ? MIXED_VALUE : styles.fontWeight || "400"}
+          value={fontWeightIsMixed ? MIXED_VALUE : currentFontWeight}
           onValueChange={(v) => onStyleChange("fontWeight", v)}
         >
           <SelectTrigger className="h-6 rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-1.5 !text-[11px] shadow-none focus:ring-1 focus:ring-[var(--design-editor-accent-color)]">
@@ -364,7 +577,7 @@ export function TypographyProperties({
         <ScrubInput
           label={t("editPanel.labels.size")}
           ariaLabel={t("editPanel.labels.size")}
-          icon={IconLetterCase}
+          icon={IconTextSize}
           value={
             fontSizeIsMixed
               ? 0
@@ -493,6 +706,15 @@ export function TypographyProperties({
           <TypographyDetailsPopover
             resizeMode={resizeMode}
             onResizeModeChange={setResizeMode}
+            underlineActive={underlineActive}
+            strikethroughActive={strikethroughActive}
+            onToggleUnderline={() => toggleTextDecorationLine("underline")}
+            onToggleStrikethrough={() =>
+              toggleTextDecorationLine("line-through")
+            }
+            textCase={textCase}
+            textCaseIsMixed={textTransformIsMixed}
+            onTextCaseChange={setTextCase}
           />
         </div>
       </div>
diff --git a/templates/design/app/components/design/inspector/AutoLayoutMatrix.interaction.test.tsx b/templates/design/app/components/design/inspector/AutoLayoutMatrix.interaction.test.tsx
new file mode 100644
index 0000000000..1518ca0bef
--- /dev/null
+++ b/templates/design/app/components/design/inspector/AutoLayoutMatrix.interaction.test.tsx
@@ -0,0 +1,128 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@/components/ui/tooltip", () => ({
+  Tooltip: ({ children }: { children?: unknown }) => children as never,
+  TooltipTrigger: ({ children }: { children?: unknown }) => children as never,
+  TooltipContent: ({ children }: { children?: unknown }) => children as never,
+  TooltipProvider: ({ children }: { children?: unknown }) => children as never,
+}));
+
+import {
+  AutoLayoutMatrix,
+  type AutoLayoutMatrixValue,
+} from "./AutoLayoutMatrix";
+
+const value: AutoLayoutMatrixValue = {
+  direction: "horizontal",
+  wrap: "nowrap",
+  alignment: { horizontal: "left", vertical: "top" },
+  gap: 8,
+  padding: { top: 4, right: 4, bottom: 4, left: 4 },
+  paddingLinked: true,
+  childSizing: { horizontal: "fixed", vertical: "fixed" },
+  display: "block",
+};
+
+describe("AutoLayoutMatrix Flow interactions", () => {
+  it("uses the atomic Flow callback without emitting three individual changes", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const root = createRoot(container);
+    const onFlowChange = vi.fn();
+    const onDisplayChange = vi.fn();
+    const onDirectionChange = vi.fn();
+    const onWrapChange = vi.fn();
+
+    await act(async () => {
+      root.render(
+        <AutoLayoutMatrix
+          value={value}
+          onFlowChange={onFlowChange}
+          onDisplayChange={onDisplayChange}
+          onDirectionChange={onDirectionChange}
+          onWrapChange={onWrapChange}
+          onAlignmentChange={vi.fn()}
+          onGapChange={vi.fn()}
+          onPaddingChange={vi.fn()}
+          onPaddingLinkedChange={vi.fn()}
+          onChildSizingChange={vi.fn()}
+        />,
+      );
+    });
+
+    const vertical = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Vertical"]',
+    );
+    expect(vertical).not.toBeNull();
+    await act(async () => vertical?.click());
+
+    expect(onFlowChange).toHaveBeenCalledOnce();
+    expect(onFlowChange).toHaveBeenCalledWith("vertical");
+    expect(onDisplayChange).not.toHaveBeenCalled();
+    expect(onDirectionChange).not.toHaveBeenCalled();
+    expect(onWrapChange).not.toHaveBeenCalled();
+
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  it("treats Grid as a distinct atomic flow and exposes explicit track controls", async () => {
+    const container = document.createElement("div");
+    document.body.append(container);
+    const root = createRoot(container);
+    const onFlowChange = vi.fn();
+
+    await act(async () => {
+      root.render(
+        <AutoLayoutMatrix
+          value={{
+            ...value,
+            display: "grid",
+            grid: {
+              columns: 3,
+              rows: 2,
+              columnSizing: "fill",
+              rowSizing: "hug",
+              columnGap: 12,
+              rowGap: 8,
+            },
+          }}
+          onFlowChange={onFlowChange}
+          onDirectionChange={vi.fn()}
+          onWrapChange={vi.fn()}
+          onAlignmentChange={vi.fn()}
+          onGapChange={vi.fn()}
+          onGridChange={vi.fn()}
+          onPaddingChange={vi.fn()}
+          onPaddingLinkedChange={vi.fn()}
+          onChildSizingChange={vi.fn()}
+        />,
+      );
+    });
+
+    expect(container.querySelector('[data-flow-value="grid"]')).not.toBeNull();
+    expect(
+      container.querySelector('input[aria-label="Columns"]'),
+    ).not.toBeNull();
+    expect(container.querySelector('input[aria-label="Rows"]')).not.toBeNull();
+    expect(
+      container.querySelector('input[aria-label="Column gap"]'),
+    ).not.toBeNull();
+    expect(
+      container.querySelector('input[aria-label="Row gap"]'),
+    ).not.toBeNull();
+
+    const grid = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Grid"]',
+    );
+    await act(async () => grid?.click());
+    expect(onFlowChange).toHaveBeenCalledWith("grid");
+
+    await act(async () => root.unmount());
+    container.remove();
+  });
+});
diff --git a/templates/design/app/components/design/inspector/AutoLayoutMatrix.test.tsx b/templates/design/app/components/design/inspector/AutoLayoutMatrix.test.tsx
index 6fee3578ff..9b864ac7dd 100644
--- a/templates/design/app/components/design/inspector/AutoLayoutMatrix.test.tsx
+++ b/templates/design/app/components/design/inspector/AutoLayoutMatrix.test.tsx
@@ -44,4 +44,126 @@ describe("AutoLayoutMatrix", () => {
     expect(markup).not.toContain("Padding");
     expect(markup).not.toContain("Clip content");
   });
+
+  it("shows a Mixed placeholder for gap instead of a misleading 0 when the multi-selection's gap values differ", () => {
+    const markup = renderToStaticMarkup(
+      createElement(AutoLayoutMatrix, {
+        value: { ...value, gap: 0, gapMixed: true },
+        onDirectionChange: noop,
+        onWrapChange: noop,
+        onAlignmentChange: noop,
+        onGapChange: noop,
+        onPaddingChange: noop,
+        onPaddingLinkedChange: noop,
+        onChildSizingChange: noop,
+      }),
+    );
+
+    expect(markup).toContain("Mixed");
+    expect(markup).not.toMatch(/value="0"/);
+  });
+
+  it("shows a Mixed placeholder for the linked horizontal padding field when left/right differ across the selection, without marking the vertical field mixed", () => {
+    const markup = renderToStaticMarkup(
+      createElement(AutoLayoutMatrix, {
+        value: {
+          ...value,
+          padding: { top: 4, right: 0, bottom: 4, left: 0 },
+          paddingMixed: { left: true, right: true },
+        },
+        onDirectionChange: noop,
+        onWrapChange: noop,
+        onAlignmentChange: noop,
+        onGapChange: noop,
+        onPaddingChange: noop,
+        onPaddingLinkedChange: noop,
+        onChildSizingChange: noop,
+      }),
+    );
+
+    // Both the horizontal padding field's aria-label and the literal "Mixed"
+    // placeholder text should be present.
+    expect(markup).toContain("Mixed");
+  });
+
+  it("shows Mixed for a single unlinked padding side without affecting the other sides", () => {
+    const markup = renderToStaticMarkup(
+      createElement(AutoLayoutMatrix, {
+        value: {
+          ...value,
+          padding: { top: 4, right: 4, bottom: 4, left: 8 },
+          paddingLinked: false,
+          paddingMixed: { left: true },
+        },
+        onDirectionChange: noop,
+        onWrapChange: noop,
+        onAlignmentChange: noop,
+        onGapChange: noop,
+        onPaddingChange: noop,
+        onPaddingLinkedChange: noop,
+        onChildSizingChange: noop,
+      }),
+    );
+
+    expect(markup).toContain("Mixed");
+  });
+
+  it("shows an explicit Mixed flow with no plausible segment selected", () => {
+    const markup = renderToStaticMarkup(
+      createElement(AutoLayoutMatrix, {
+        value: { ...value, flowMixed: true },
+        onDirectionChange: noop,
+        onWrapChange: noop,
+        onAlignmentChange: noop,
+        onGapChange: noop,
+        onPaddingChange: noop,
+        onPaddingLinkedChange: noop,
+        onChildSizingChange: noop,
+      }),
+    );
+
+    expect(markup).toContain('data-flow-value="mixed"');
+    expect(markup).toContain("Mixed");
+    expect(markup).toContain('aria-label="Normal flow" aria-pressed="false"');
+    expect(markup).toContain('aria-label="Vertical" aria-pressed="false"');
+    expect(markup).toContain('aria-label="Horizontal" aria-pressed="false"');
+    expect(markup).toContain('aria-label="Grid" aria-pressed="false"');
+  });
+
+  it("shows mixed alignment, gap mode, and clipping without plausible defaults", () => {
+    const markup = renderToStaticMarkup(
+      createElement(AutoLayoutMatrix, {
+        value: {
+          ...value,
+          alignmentMixed: true,
+          gapModeMixed: true,
+          clipContentMixed: true,
+        },
+        onDirectionChange: noop,
+        onWrapChange: noop,
+        onAlignmentChange: noop,
+        onGapChange: noop,
+        onPaddingChange: noop,
+        onPaddingLinkedChange: noop,
+        onChildSizingChange: noop,
+        onDistribute: noop,
+      }),
+    );
+
+    expect(markup).toContain("Gap mode: Mixed");
+    expect(markup).toContain('aria-checked="mixed"');
+    for (const label of [
+      "top left",
+      "top center",
+      "top right",
+      "middle left",
+      "middle center",
+      "middle right",
+      "bottom left",
+      "bottom center",
+      "bottom right",
+    ]) {
+      expect(markup).toContain(`aria-label="${label}" aria-pressed="false"`);
+    }
+  });
 });
diff --git a/templates/design/app/components/design/inspector/AutoLayoutMatrix.tsx b/templates/design/app/components/design/inspector/AutoLayoutMatrix.tsx
index b15afb68e4..85f624bd27 100644
--- a/templates/design/app/components/design/inspector/AutoLayoutMatrix.tsx
+++ b/templates/design/app/components/design/inspector/AutoLayoutMatrix.tsx
@@ -46,6 +46,25 @@ export type AutoLayoutDirection = "horizontal" | "vertical";
 export type AutoLayoutWrap = "nowrap" | "wrap";
 export type AutoLayoutSizing = "hug" | "fill" | "fixed";
 export type AutoLayoutSizingAxis = "horizontal" | "vertical";
+export type AutoLayoutGridTrackSizing = "fill" | "hug" | "fixed" | "custom";
+
+export interface AutoLayoutGridValue {
+  columns: number;
+  rows: number;
+  columnSizing: AutoLayoutGridTrackSizing;
+  rowSizing: AutoLayoutGridTrackSizing;
+  columnSize?: number;
+  rowSize?: number;
+  /** Exact authored values, retained for non-uniform/custom templates. */
+  columnTemplate?: string;
+  rowTemplate?: string;
+  columnGap: number;
+  rowGap: number;
+  columnsMixed?: boolean;
+  rowsMixed?: boolean;
+  columnGapMixed?: boolean;
+  rowGapMixed?: boolean;
+}
 
 /** Round to one decimal place — matches the `precision={1}` ScrubInput fields
  * advertise (e.g. X/Y position, stroke weight) so W/H commit sub-pixel values
@@ -59,6 +78,7 @@ function roundToOneDecimal(value: number): number {
  * non-flex containers; the other four map to flex direction + wrap state.
  */
 export type AutoLayoutFlow = "normal" | "vertical" | "horizontal" | "grid";
+type ResolvedAutoLayoutFlow = AutoLayoutFlow | "mixed";
 
 export interface AutoLayoutPadding {
   top: number;
@@ -71,10 +91,12 @@ export interface AutoLayoutMatrixValue {
   direction: AutoLayoutDirection;
   wrap: AutoLayoutWrap;
   alignment: AlignmentMatrixValue;
+  alignmentMixed?: boolean;
   gap: number;
   padding: AutoLayoutPadding;
   paddingLinked: boolean;
   clipContent?: boolean;
+  clipContentMixed?: boolean;
   resolvedSize?: {
     horizontal?: number;
     vertical?: number;
@@ -83,6 +105,32 @@ export interface AutoLayoutMatrixValue {
     horizontal?: boolean;
     vertical?: boolean;
   };
+  /**
+   * Set when a multi-selection has differing `gap` values across elements.
+   * Mirrors the edit-panel `MIXED_VALUE`/`isMixedValue` sentinel pattern used
+   * for other fields: rather than silently coercing an unparseable "Mixed"
+   * CSS value down to `0` (which reads as "no gap" and would clobber every
+   * selected element's real gap the moment the user touches the field), the
+   * Gap ScrubInput renders the "Mixed" placeholder instead of a numeric 0.
+   * Optional so existing single-selection callers are unaffected.
+   */
+  gapMixed?: boolean;
+  gapModeMixed?: boolean;
+  /** Explicit CSS-grid tracks. Grid is a separate flow, never flex-wrap. */
+  grid?: AutoLayoutGridValue;
+  /**
+   * Per-side mixed flags for `padding`, same rationale as `gapMixed`. Each
+   * side is independent because a multi-selection can have matching top/bottom
+   * padding but differing left/right (or any other combination) — collapsing
+   * to one boolean would either over- or under-report "Mixed" for the linked
+   * 2-field view. Optional so existing single-selection callers are unaffected.
+   */
+  paddingMixed?: {
+    top?: boolean;
+    right?: boolean;
+    bottom?: boolean;
+    left?: boolean;
+  };
   childSizing: {
     horizontal: AutoLayoutSizing;
     vertical: AutoLayoutSizing;
@@ -102,7 +150,11 @@ export interface AutoLayoutMatrixValue {
    * treated as disabled. Defaults to flex when omitted so existing callers are
    * unaffected.
    */
-  display?: "flex" | "block";
+  display?: "flex" | "grid" | "block";
+  /** True when a multi-selection disagrees on display/direction/wrap. No flow
+   * segment is shown as active and the row explicitly says Mixed until the
+   * user chooses one common flow. */
+  flowMixed?: boolean;
   /**
    * When true, the gap mode is "Auto" (CSS `justify-content: space-between`).
    * When false or omitted, gap mode is "Fixed" (a numeric gap value).
@@ -162,6 +214,10 @@ export interface AutoLayoutMatrixProps {
    * nothing until reselect).
    */
   onGapChange: (gap: number, meta?: ScrubInputChangeMeta) => void;
+  onGridChange?: (
+    grid: AutoLayoutGridValue,
+    meta?: ScrubInputChangeMeta,
+  ) => void;
   onPaddingChange: (
     padding: AutoLayoutPadding,
     meta?: ScrubInputChangeMeta,
@@ -204,13 +260,20 @@ export interface AutoLayoutMatrixProps {
    * no variable collections exist.
    */
   onApplyVariable?: (axis: AutoLayoutSizingAxis) => void;
+  /**
+   * Optional atomic Flow callback. Inspector hosts that persist code should
+   * use this to commit display + direction + wrap in one source/history step.
+   * Without it, the component falls back to the individual callbacks for
+   * backwards compatibility.
+   */
+  onFlowChange?: (flow: AutoLayoutFlow) => void;
   /**
    * Emitted when the user picks a flow that changes the layout mode between
    * normal-flow (block) and flex. Pass this so selecting the first ("normal")
    * flow icon can turn auto layout off, and selecting a flex flow can turn it
    * on. Optional — when omitted the control still works in pure-flex mode.
    */
-  onDisplayChange?: (display: "flex" | "block") => void;
+  onDisplayChange?: (display: "flex" | "grid" | "block") => void;
   availableChildSizing?: Partial<
     Record<AutoLayoutSizingAxis, AutoLayoutSizing[]>
   >;
@@ -261,9 +324,10 @@ export const DEFAULT_AUTO_LAYOUT_LABELS: AutoLayoutMatrixLabels = {
 const SIZING_OPTIONS: AutoLayoutSizing[] = ["hug", "fill", "fixed"];
 
 /** Derive the active flow option from display + direction + wrap state. */
-function getFlowOption(value: AutoLayoutMatrixValue): AutoLayoutFlow {
+function getFlowOption(value: AutoLayoutMatrixValue): ResolvedAutoLayoutFlow {
+  if (value.flowMixed) return "mixed";
   if (value.display === "block") return "normal";
-  if (value.wrap === "wrap") return "grid";
+  if (value.display === "grid") return "grid";
   if (value.direction === "vertical") return "vertical";
   return "horizontal";
 }
@@ -274,6 +338,7 @@ export function AutoLayoutMatrix({
   onWrapChange,
   onAlignmentChange,
   onGapChange,
+  onGridChange,
   onPaddingChange,
   onPaddingLinkedChange,
   onClipContentChange,
@@ -282,6 +347,7 @@ export function AutoLayoutMatrix({
   onChildSizingChange,
   onChildMinMaxChange,
   onApplyVariable,
+  onFlowChange,
   onDisplayChange,
   onChildSizeChange,
   availableChildSizing,
@@ -300,18 +366,32 @@ export function AutoLayoutMatrix({
   // the user's intent without a silent lossy round-trip through the average.
   const horizontalPaddingValue = value.padding.left;
   const verticalPaddingValue = value.padding.top;
+  // The linked view shows one field per axis representing both sides, so it
+  // must report "Mixed" whenever *either* side of that axis differs across
+  // the selection — otherwise a selection with equal left/right but mixed
+  // top/bottom (or vice versa) would silently show a real-looking number.
+  const horizontalPaddingMixed = Boolean(
+    value.paddingMixed?.left || value.paddingMixed?.right,
+  );
+  const verticalPaddingMixed = Boolean(
+    value.paddingMixed?.top || value.paddingMixed?.bottom,
+  );
 
   const activeFlow = getFlowOption(value);
   const isBlock = activeFlow === "normal";
 
   /** Apply a flow choice, coordinating display + direction + wrap. */
   const selectFlow = (flow: AutoLayoutFlow) => {
+    if (onFlowChange) {
+      onFlowChange(flow);
+      return;
+    }
     if (flow === "normal") {
       onDisplayChange?.("block");
       return;
     }
-    // Any flex flow turns auto layout on.
-    onDisplayChange?.("flex");
+    // Grid is a distinct layout model; horizontal/vertical use flexbox.
+    onDisplayChange?.(flow === "grid" ? "grid" : "flex");
     if (flow === "vertical") {
       onDirectionChange("vertical");
       onWrapChange("nowrap");
@@ -319,9 +399,7 @@ export function AutoLayoutMatrix({
       onDirectionChange("horizontal");
       onWrapChange("nowrap");
     } else {
-      // grid → horizontal direction with wrap
-      onDirectionChange("horizontal");
-      onWrapChange("wrap");
+      // Grid tracks are controlled independently below.
     }
   };
 
@@ -331,12 +409,22 @@ export function AutoLayoutMatrix({
         {/* ── Flow ── */}
         {showChildLayoutControls ? (
           <div className="space-y-1.5">
-            <ControlLabel>
-              {"Flow" /* i18n-ignore design inspector label */}
-            </ControlLabel>
+            <div className="flex items-center justify-between gap-2">
+              <ControlLabel>
+                {"Flow" /* i18n-ignore design inspector label */}
+              </ControlLabel>
+              {value.flowMixed ? (
+                <span className="!text-[11px] text-muted-foreground">
+                  {"Mixed" /* i18n-ignore design mixed value */}
+                </span>
+              ) : null}
+            </div>
             <div className="flex items-center gap-1.5">
               {/* 4-segment flow bar: normal / vertical / horizontal / grid */}
-              <div className="flex h-7 flex-1 items-center gap-0.5 rounded-md bg-[var(--design-editor-control-bg)] p-0.5">
+              <div
+                data-flow-value={activeFlow}
+                className="flex h-7 flex-1 items-center gap-0.5 rounded-md bg-[var(--design-editor-control-bg)] p-0.5"
+              >
                 <FlowButton
                   label={"Normal flow" /* i18n-ignore design inspector label */}
                   active={activeFlow === "normal"}
@@ -487,11 +575,19 @@ export function AutoLayoutMatrix({
         {showChildLayoutControls && !isBlock ? (
           <div className="grid grid-cols-[78px_1fr] items-start gap-3">
             <div className="space-y-1.5">
-              <ControlLabel>
-                {"Alignment" /* i18n-ignore design inspector label */}
-              </ControlLabel>
+              <div className="flex items-center justify-between gap-2">
+                <ControlLabel>
+                  {"Alignment" /* i18n-ignore design inspector label */}
+                </ControlLabel>
+                {value.alignmentMixed ? (
+                  <span className="!text-[11px] text-muted-foreground">
+                    {"Mixed" /* i18n-ignore design mixed value */}
+                  </span>
+                ) : null}
+              </div>
               <CompactAlignmentMatrix
                 value={value.alignment}
+                mixed={value.alignmentMixed}
                 onChange={onAlignmentChange}
                 direction={value.direction}
                 disabled={disabled}
@@ -499,19 +595,42 @@ export function AutoLayoutMatrix({
               />
             </div>
 
-            <div className="space-y-1.5">
-              <ControlLabel>{copy.gap}</ControlLabel>
-              <GapField
-                value={value.gap}
-                onGapChange={onGapChange}
-                onDistribute={onDistribute}
-                onGapModeChange={onGapModeChange}
-                label={copy.gap}
+            {activeFlow === "grid" && value.grid ? (
+              <GridControls
+                value={value.grid}
+                onChange={onGridChange}
                 disabled={disabled}
-                direction={value.direction}
-                gapMode={value.spaceBetween ? "auto" : "fixed"}
               />
-            </div>
+            ) : (
+              <div className="space-y-1.5">
+                <ControlLabel>{copy.gap}</ControlLabel>
+                <GapField
+                  value={value.gap}
+                  mixed={value.gapMixed}
+                  onGapChange={onGapChange}
+                  onDistribute={onDistribute}
+                  onGapModeChange={onGapModeChange}
+                  label={copy.gap}
+                  disabled={disabled}
+                  direction={value.direction}
+                  gapMode={value.spaceBetween ? "auto" : "fixed"}
+                  gapModeMixed={value.gapModeMixed}
+                />
+                {activeFlow === "horizontal" ? (
+                  <label className="flex items-center gap-2 !text-[11px] text-foreground">
+                    <Checkbox
+                      checked={value.wrap === "wrap"}
+                      disabled={disabled}
+                      onCheckedChange={(checked) =>
+                        onWrapChange(checked === true ? "wrap" : "nowrap")
+                      }
+                      className="size-3.5 rounded-[3px]"
+                    />
+                    <span>{copy.wrap}</span>
+                  </label>
+                ) : null}
+              </div>
+            )}
           </div>
         ) : null}
 
@@ -526,6 +645,7 @@ export function AutoLayoutMatrix({
                   icon={IconPaddingHorizontal}
                   ariaLabel={copy.paddingLeft + " / " + copy.paddingRight}
                   value={horizontalPaddingValue}
+                  mixed={horizontalPaddingMixed}
                   onChange={(next, meta) =>
                     onPaddingChange(
                       {
@@ -543,6 +663,7 @@ export function AutoLayoutMatrix({
                   icon={IconPaddingVertical}
                   ariaLabel={copy.paddingTop + " / " + copy.paddingBottom}
                   value={verticalPaddingValue}
+                  mixed={verticalPaddingMixed}
                   onChange={(next, meta) =>
                     onPaddingChange(
                       {
@@ -572,6 +693,7 @@ export function AutoLayoutMatrix({
                     icon={IconPaddingTopMini}
                     ariaLabel={copy.paddingTop}
                     value={value.padding.top}
+                    mixed={value.paddingMixed?.top}
                     onChange={(next, meta) =>
                       onPaddingChange({ ...value.padding, top: next }, meta)
                     }
@@ -581,6 +703,7 @@ export function AutoLayoutMatrix({
                     icon={IconPaddingRightMini}
                     ariaLabel={copy.paddingRight}
                     value={value.padding.right}
+                    mixed={value.paddingMixed?.right}
                     onChange={(next, meta) =>
                       onPaddingChange({ ...value.padding, right: next }, meta)
                     }
@@ -590,6 +713,7 @@ export function AutoLayoutMatrix({
                     icon={IconPaddingBottomMini}
                     ariaLabel={copy.paddingBottom}
                     value={value.padding.bottom}
+                    mixed={value.paddingMixed?.bottom}
                     onChange={(next, meta) =>
                       onPaddingChange({ ...value.padding, bottom: next }, meta)
                     }
@@ -599,6 +723,7 @@ export function AutoLayoutMatrix({
                     icon={IconPaddingLeftMini}
                     ariaLabel={copy.paddingLeft}
                     value={value.padding.left}
+                    mixed={value.paddingMixed?.left}
                     onChange={(next, meta) =>
                       onPaddingChange({ ...value.padding, left: next }, meta)
                     }
@@ -621,7 +746,11 @@ export function AutoLayoutMatrix({
         {showChildLayoutControls ? (
           <label className="flex h-6 cursor-pointer items-center gap-2 !text-[11px] text-foreground">
             <Checkbox
-              checked={Boolean(value.clipContent)}
+              checked={
+                value.clipContentMixed
+                  ? "indeterminate"
+                  : Boolean(value.clipContent)
+              }
               disabled={disabled}
               onCheckedChange={(checked) =>
                 onClipContentChange?.(checked === true)
@@ -668,6 +797,179 @@ const ALIGNMENT_CELLS: Array<{
 // Sub-components
 // ─────────────────────────────────────────────────
 
+function GridControls({
+  value,
+  onChange,
+  disabled,
+}: {
+  value: AutoLayoutGridValue;
+  onChange?: (value: AutoLayoutGridValue, meta?: ScrubInputChangeMeta) => void;
+  disabled: boolean;
+}) {
+  const update = (
+    patch: Partial<AutoLayoutGridValue>,
+    meta?: ScrubInputChangeMeta,
+  ) => onChange?.({ ...value, ...patch }, meta);
+
+  return (
+    <div className="space-y-1.5">
+      <ControlLabel>
+        {"Grid" /* i18n-ignore design inspector label */}
+      </ControlLabel>
+      <div className="grid grid-cols-2 gap-1.5">
+        <GridNumberField
+          label={"Columns" /* i18n-ignore design inspector label */}
+          value={value.columns}
+          mixed={value.columnsMixed}
+          min={1}
+          max={24}
+          onChange={(columns, meta) => update({ columns }, meta)}
+          disabled={disabled || !onChange}
+        />
+        <GridNumberField
+          label={"Rows" /* i18n-ignore design inspector label */}
+          value={value.rows}
+          mixed={value.rowsMixed}
+          min={1}
+          max={24}
+          onChange={(rows, meta) => update({ rows }, meta)}
+          disabled={disabled || !onChange}
+        />
+        <GridTrackPicker
+          label={"Column sizing" /* i18n-ignore design inspector label */}
+          value={value.columnSizing}
+          fixedSize={value.columnSize}
+          disabled={disabled || !onChange}
+          onChange={(columnSizing) => update({ columnSizing })}
+          onFixedSizeChange={(columnSize, meta) => update({ columnSize }, meta)}
+        />
+        <GridTrackPicker
+          label={"Row sizing" /* i18n-ignore design inspector label */}
+          value={value.rowSizing}
+          fixedSize={value.rowSize}
+          disabled={disabled || !onChange}
+          onChange={(rowSizing) => update({ rowSizing })}
+          onFixedSizeChange={(rowSize, meta) => update({ rowSize }, meta)}
+        />
+        <GridNumberField
+          label={"Column gap" /* i18n-ignore design inspector label */}
+          value={value.columnGap}
+          mixed={value.columnGapMixed}
+          min={0}
+          unit="px"
+          onChange={(columnGap, meta) => update({ columnGap }, meta)}
+          disabled={disabled || !onChange}
+        />
+        <GridNumberField
+          label={"Row gap" /* i18n-ignore design inspector label */}
+          value={value.rowGap}
+          mixed={value.rowGapMixed}
+          min={0}
+          unit="px"
+          onChange={(rowGap, meta) => update({ rowGap }, meta)}
+          disabled={disabled || !onChange}
+        />
+      </div>
+    </div>
+  );
+}
+
+function GridNumberField({
+  label,
+  value,
+  mixed,
+  min,
+  max,
+  unit,
+  onChange,
+  disabled,
+}: {
+  label: string;
+  value: number;
+  mixed?: boolean;
+  min: number;
+  max?: number;
+  unit?: string;
+  onChange: (value: number, meta: ScrubInputChangeMeta) => void;
+  disabled: boolean;
+}) {
+  return (
+    <ScrubInput
+      label={label}
+      ariaLabel={label}
+      tooltipLabel={label}
+      value={value}
+      mixed={mixed}
+      onChange={onChange}
+      unit={unit}
+      min={min}
+      max={max}
+      step={1}
+      precision={0}
+      disabled={disabled}
+      className="min-w-0 gap-0 rounded-md bg-[var(--design-editor-control-bg)]"
+      labelClassName="h-7 w-6 justify-center overflow-hidden px-1 !text-[9px] text-muted-foreground [&>svg]:hidden"
+      inputClassName="h-7 border-0 bg-transparent px-1 !text-[11px] shadow-none focus-visible:ring-0"
+    />
+  );
+}
+
+function GridTrackPicker({
+  label,
+  value,
+  fixedSize = 100,
+  disabled,
+  onChange,
+  onFixedSizeChange,
+}: {
+  label: string;
+  value: AutoLayoutGridTrackSizing;
+  fixedSize?: number;
+  disabled: boolean;
+  onChange: (value: AutoLayoutGridTrackSizing) => void;
+  onFixedSizeChange: (value: number, meta: ScrubInputChangeMeta) => void;
+}) {
+  return (
+    <div className="flex min-w-0 rounded-md bg-[var(--design-editor-control-bg)]">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button
+            type="button"
+            variant="ghost"
+            disabled={disabled}
+            aria-label={label}
+            className="h-7 min-w-0 flex-1 justify-start rounded-md px-2 !text-[11px] font-normal capitalize"
+          >
+            {value}
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="start">
+          {(["fill", "hug", "fixed", "custom"] as const).map((option) => (
+            <DropdownMenuItem key={option} onSelect={() => onChange(option)}>
+              <span className="capitalize">{option}</span>
+            </DropdownMenuItem>
+          ))}
+        </DropdownMenuContent>
+      </DropdownMenu>
+      {value === "fixed" ? (
+        <ScrubInput
+          label={label}
+          ariaLabel={`${label} size`}
+          value={fixedSize}
+          onChange={onFixedSizeChange}
+          unit="px"
+          min={0}
+          precision={0}
+          disabled={disabled}
+          className="w-14 min-w-0 gap-0"
+          labelClassName="hidden"
+          inputClassName="h-7 border-0 bg-transparent px-1 !text-[11px] shadow-none focus-visible:ring-0"
+        />
+      ) : null}
+    </div>
+  );
+}
+
 /**
  * Compact 3×3 alignment grid (no border box). Inactive cells show a faint dot;
  * the active cell shows accent bars oriented by flow — horizontal bars for a
@@ -677,12 +979,14 @@ const ALIGNMENT_CELLS: Array<{
  */
 function CompactAlignmentMatrix({
   value,
+  mixed = false,
   onChange,
   direction,
   disabled,
   onDistribute,
 }: {
   value: AlignmentMatrixValue;
+  mixed?: boolean;
   onChange: (value: AlignmentMatrixValue) => void;
   direction: AutoLayoutDirection;
   disabled: boolean;
@@ -695,6 +999,7 @@ function CompactAlignmentMatrix({
       <div className={cn("grid w-fit grid-cols-3 rounded-md")}>
         {ALIGNMENT_CELLS.map((cell) => {
           const active =
+            !mixed &&
             cell.horizontal === value.horizontal &&
             cell.vertical === value.vertical;
           return (
@@ -917,6 +1222,7 @@ function FlowButton({
  */
 function GapField({
   value,
+  mixed = false,
   onGapChange,
   onDistribute,
   onGapModeChange,
@@ -924,8 +1230,11 @@ function GapField({
   disabled,
   direction,
   gapMode = "fixed",
+  gapModeMixed = false,
 }: {
   value: number;
+  /** Set for a multi-selection with differing gap values — see AutoLayoutMatrixValue.gapMixed. */
+  mixed?: boolean;
   /** Forwards ScrubInput's gesture meta — see AutoLayoutMatrixProps.onGapChange. */
   onGapChange: (gap: number, meta?: ScrubInputChangeMeta) => void;
   onDistribute?: (axis: DistributionAxis) => void;
@@ -934,6 +1243,7 @@ function GapField({
   disabled: boolean;
   direction: AutoLayoutDirection;
   gapMode?: "fixed" | "auto";
+  gapModeMixed?: boolean;
 }) {
   return (
     <div className="flex items-center gap-1.5">
@@ -950,6 +1260,7 @@ function GapField({
           tooltipLabel={label}
           icon={IconGap}
           value={value}
+          mixed={mixed}
           onChange={(next, meta) => onGapChange(next, meta)}
           unit="px"
           min={0}
@@ -967,7 +1278,11 @@ function GapField({
                 <DropdownMenuTrigger asChild>
                   <button
                     type="button"
-                    aria-label={"Gap mode" /* i18n-ignore inspector tooltip */}
+                    aria-label={
+                      gapModeMixed
+                        ? "Gap mode: Mixed" /* i18n-ignore inspector tooltip */
+                        : "Gap mode" /* i18n-ignore inspector tooltip */
+                    }
                     disabled={disabled}
                     className={cn(
                       "flex h-7 w-6 shrink-0 items-center justify-center rounded-r-md",
@@ -990,14 +1305,14 @@ function GapField({
               sideOffset={4}
             >
               <DropdownMenuCheckboxItem
-                checked={gapMode !== "auto"}
+                checked={!gapModeMixed && gapMode !== "auto"}
                 className="text-[12px]"
                 onSelect={() => onGapModeChange?.("fixed", direction)}
               >
                 {"Fixed" /* i18n-ignore design gap mode label */}
               </DropdownMenuCheckboxItem>
               <DropdownMenuCheckboxItem
-                checked={gapMode === "auto"}
+                checked={!gapModeMixed && gapMode === "auto"}
                 className="text-[12px]"
                 onSelect={() => {
                   if (onGapModeChange) {
@@ -1043,12 +1358,15 @@ function PaddingField({
   icon: Icon,
   ariaLabel,
   value,
+  mixed = false,
   onChange,
   disabled,
 }: {
   icon: (props: { className?: string }) => ReactNode;
   ariaLabel: string;
   value: number;
+  /** Set for a multi-selection with differing padding on this side — see AutoLayoutMatrixValue.paddingMixed. */
+  mixed?: boolean;
   /** Forwards ScrubInput's gesture meta — see AutoLayoutMatrixProps.onPaddingChange. */
   onChange: (value: number, meta?: ScrubInputChangeMeta) => void;
   disabled: boolean;
@@ -1066,6 +1384,7 @@ function PaddingField({
         tooltipLabel={ariaLabel}
         icon={Icon}
         value={value}
+        mixed={mixed}
         onChange={(next, meta) => onChange(next, meta)}
         unit="px"
         min={0}
diff --git a/templates/design/app/components/design/inspector/ConstraintsWidget.test.tsx b/templates/design/app/components/design/inspector/ConstraintsWidget.test.tsx
new file mode 100644
index 0000000000..0efeb3690a
--- /dev/null
+++ b/templates/design/app/components/design/inspector/ConstraintsWidget.test.tsx
@@ -0,0 +1,20 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { ConstraintsWidget } from "./ConstraintsWidget";
+
+describe("ConstraintsWidget mixed selections", () => {
+  it("renders an explicit Mixed value for each mixed axis", () => {
+    const markup = renderToStaticMarkup(
+      createElement(ConstraintsWidget, {
+        value: { horizontal: "mixed", vertical: "mixed" },
+        onChange: () => undefined,
+      }),
+    );
+
+    expect(markup.match(/Mixed/g)?.length).toBeGreaterThanOrEqual(2);
+    expect(markup).toContain('aria-label="Horizontal"');
+    expect(markup).toContain('aria-label="Vertical"');
+  });
+});
diff --git a/templates/design/app/components/design/inspector/ConstraintsWidget.tsx b/templates/design/app/components/design/inspector/ConstraintsWidget.tsx
index c9248f5656..3c169198d7 100644
--- a/templates/design/app/components/design/inspector/ConstraintsWidget.tsx
+++ b/templates/design/app/components/design/inspector/ConstraintsWidget.tsx
@@ -15,13 +15,15 @@ export type HorizontalConstraint =
   | "right"
   | "left-right"
   | "center"
-  | "scale";
+  | "scale"
+  | "mixed";
 export type VerticalConstraint =
   | "top"
   | "bottom"
   | "top-bottom"
   | "center"
-  | "scale";
+  | "scale"
+  | "mixed";
 
 export interface ConstraintsValue {
   horizontal: HorizontalConstraint;
@@ -40,6 +42,7 @@ export interface ConstraintsWidgetLabels {
   topBottom: string;
   center: string;
   scale: string;
+  mixed: string;
 }
 
 export interface ConstraintsWidgetProps {
@@ -71,6 +74,7 @@ const DEFAULT_LABELS: ConstraintsWidgetLabels = {
   topBottom: "Top and bottom", // i18n-ignore fallback component label
   center: "Center", // i18n-ignore fallback component label
   scale: "Scale", // i18n-ignore fallback component label
+  mixed: "Mixed", // i18n-ignore fallback component label
 };
 
 // ── pin-box geometry ────────────────────────────────────────────────────────
@@ -479,6 +483,10 @@ function ConstraintSelect({
           { value: "center", label: labels.center },
           { value: "scale", label: labels.scale },
         ];
+  const renderedOptions =
+    value === "mixed"
+      ? [{ value: "mixed", label: labels.mixed, disabled: true }, ...options]
+      : options;
 
   return (
     <Select
@@ -492,14 +500,15 @@ function ConstraintSelect({
         className="h-8 rounded-md border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] px-2 text-[12px] shadow-none focus:ring-1 focus:ring-[var(--design-editor-accent-color)] focus:ring-offset-0 [&>svg]:size-3"
         aria-label={axis === "horizontal" ? labels.horizontal : labels.vertical}
       >
-        <SelectValue />
+        {value === "mixed" ? labels.mixed : <SelectValue />}
       </SelectTrigger>
       <SelectContent className="z-[270]">
         <SelectGroup>
-          {options.map((option) => (
+          {renderedOptions.map((option) => (
             <SelectItem
               key={option.value}
               value={option.value}
+              disabled={"disabled" in option && option.disabled}
               className="text-[12px]"
             >
               {option.label}
diff --git a/templates/design/app/components/design/inspector/DesignColorPicker.escape.test.tsx b/templates/design/app/components/design/inspector/DesignColorPicker.escape.test.tsx
new file mode 100644
index 0000000000..7658e4c41a
--- /dev/null
+++ b/templates/design/app/components/design/inspector/DesignColorPicker.escape.test.tsx
@@ -0,0 +1,171 @@
+// @vitest-environment happy-dom
+
+/**
+ * Escape-key ordering regression (adversarial-review item 2): does an
+ * Escape keypress inside DesignColorPicker's open popover (wired at
+ * `onEscapeKeyDown={revertToOpenSnapshot}`, ~DesignColorPicker.tsx:1368)
+ * also reach `useDesignHotkeys`' `onEscape` (handleEscapeHotkey in
+ * DesignEditor.tsx), which pops/clears the canvas selection? If so, one
+ * Escape press would both revert+close the picker AND pop canvas
+ * selection — two distinct effects from a single keypress.
+ *
+ * This does NOT render the full DesignColorPicker/DesignEditor tree (out of
+ * scope and too heavy); instead it wires the two REAL, unmocked mechanisms
+ * that decide the outcome — Radix's `@radix-ui/react-dismissable-layer`
+ * (via the shared `PopoverContent` wrapper, same `onEscapeKeyDown` prop
+ * DesignColorPicker uses) and the real `useDesignHotkeys` hook (same
+ * `onEscape` prop DesignEditor.tsx wires to `handleEscapeHotkey`) — and
+ * dispatches a real, bubbling, cancelable "Escape" keydown at a plain
+ * (non-editable) inner element, matching the SV field / ColorTrack slider /
+ * gradient stop buttons named in the review: none of them are
+ * input/textarea/select/contenteditable/role=textbox, so
+ * `isDesignHotkeyEditableTarget` would NOT skip them on its own.
+ *
+ * Finding: the double-fire cannot happen, and no code change was made here.
+ * Radix's `DismissableLayer` (see
+ * @radix-ui/react-dismissable-layer/dist/index.mjs) adds its Escape listener
+ * on `ownerDocument` with `{ capture: true }`, and always calls
+ * `event.preventDefault()` after `onEscapeKeyDown` fires whenever the layer
+ * has an `onDismiss` (Popover always wires one — `onDismiss: () =>
+ * context.onOpenChange(false)` — regardless of what `onEscapeKeyDown` does).
+ * `useDesignHotkeys` (DesignEditor.tsx's call has no `target`/`capture`
+ * override) listens on `window` with the default bubble phase. Native keydown
+ * dispatch order is: capture phase window -> document -> ... -> target, then
+ * bubble phase target -> ... -> document -> window. Radix's document-capture
+ * listener therefore always runs and calls `preventDefault()` *before* the
+ * event ever reaches the target or bubbles back up to `window`, so by the
+ * time `useDesignHotkeys`' handler runs, `event.defaultPrevented` is already
+ * `true` and its very first guard (`if (event.defaultPrevented ...) return;`)
+ * bails out before `onEscape` is invoked. The ordering is a structural
+ * guarantee of the DOM event model (document is always an ancestor of
+ * window's bubble-phase delivery point in this browser event model — more
+ * precisely: capture always fully completes down to target before any
+ * bubble listener runs), not an accident of registration order, so this test
+ * pins the guarantee rather than proposing a fix.
+ */
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { useDesignHotkeys } from "@/hooks/useDesignHotkeys";
+
+let container: HTMLDivElement;
+let root: ReturnType<typeof createRoot>;
+
+beforeEach(() => {
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+function Harness({
+  onPopoverEscape,
+  onCanvasEscapeHotkey,
+}: {
+  onPopoverEscape: () => void;
+  onCanvasEscapeHotkey: () => void;
+}) {
+  // Mirrors DesignEditor.tsx's real `useDesignHotkeys({ ..., onEscape:
+  // handleEscapeHotkey })` call: no `target`/`capture` override, so it binds
+  // to `window` in the default bubble phase, exactly like production.
+  useDesignHotkeys({ onEscape: onCanvasEscapeHotkey });
+
+  return (
+    <Popover open onOpenChange={() => undefined}>
+      <PopoverTrigger asChild>
+        <button type="button">trigger</button>
+      </PopoverTrigger>
+      {/* portalled=false keeps this inline for the test; DesignColorPicker's
+          real PopoverContent (portalled, default true) still binds Radix's
+          document-level capture listener the same way regardless of portal
+          placement — portalling only changes where the DOM node lives, not
+          which document/capture phase the DismissableLayer effect uses. */}
+      <PopoverContent portalled={false} onEscapeKeyDown={onPopoverEscape}>
+        {/* A plain button — not input/textarea/select/contenteditable/
+            role=textbox — matching the SV field / ColorTrack slider /
+            gradient stop buttons the review named as targets that
+            useDesignHotkeys' editable-target guard would NOT skip. */}
+        <button type="button" data-testid="inner-target">
+          inner
+        </button>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+describe("Escape ordering — DesignColorPicker popover vs canvas hotkeys", () => {
+  it("an Escape keydown on a non-editable popover-content target fires the popover's onEscapeKeyDown but never reaches useDesignHotkeys' onEscape", () => {
+    const onPopoverEscape = vi.fn();
+    const onCanvasEscapeHotkey = vi.fn();
+
+    act(() => {
+      root.render(
+        <Harness
+          onPopoverEscape={onPopoverEscape}
+          onCanvasEscapeHotkey={onCanvasEscapeHotkey}
+        />,
+      );
+    });
+
+    const inner = container.querySelector<HTMLButtonElement>(
+      '[data-testid="inner-target"]',
+    );
+    expect(inner).not.toBeNull();
+
+    act(() => {
+      inner!.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "Escape",
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    });
+
+    expect(onPopoverEscape).toHaveBeenCalledTimes(1);
+    expect(onCanvasEscapeHotkey).not.toHaveBeenCalled();
+  });
+
+  it("a bare Escape keydown with no open popover DOES reach useDesignHotkeys' onEscape (control case — proves the hook itself is wired and working)", () => {
+    const onCanvasEscapeHotkey = vi.fn();
+
+    function ControlHarness() {
+      useDesignHotkeys({ onEscape: onCanvasEscapeHotkey });
+      return (
+        <button type="button" data-testid="plain-target">
+          plain
+        </button>
+      );
+    }
+
+    act(() => {
+      root.render(<ControlHarness />);
+    });
+
+    const target = container.querySelector<HTMLButtonElement>(
+      '[data-testid="plain-target"]',
+    );
+    act(() => {
+      target!.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "Escape",
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    });
+
+    expect(onCanvasEscapeHotkey).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/templates/design/app/components/design/inspector/DesignColorPicker.gesture.test.ts b/templates/design/app/components/design/inspector/DesignColorPicker.gesture.test.ts
index 2aca96319e..904aa3ce58 100644
--- a/templates/design/app/components/design/inspector/DesignColorPicker.gesture.test.ts
+++ b/templates/design/app/components/design/inspector/DesignColorPicker.gesture.test.ts
@@ -16,9 +16,12 @@
 import { describe, expect, it } from "vitest";
 
 import {
+  computeScrubbedValue,
   endPointerGesture,
   POINTER_GESTURE_IDLE,
+  SCRUB_GESTURE_IDLE,
   startPointerGesture,
+  startScrubGesture,
   type PointerGestureState,
 } from "./DesignColorPicker";
 
@@ -93,3 +96,80 @@ describe("DesignColorPicker gesture lifecycle — onChangeComplete", () => {
     expect(ended.state).toBe(POINTER_GESTURE_IDLE);
   });
 });
+
+/**
+ * GradientEditor.tsx (a sibling file outside this task's scope) gained its own
+ * `onCommit` prop that mirrors this exact "onChange every tick, onCommit once
+ * per gesture" contract for gradient stop-position drags and angle-dial
+ * drags. DesignColorPicker's `<GradientEditor onCommit={notifyChangeComplete}
+ * />` call site wires that signal straight into the same
+ * `onChangeComplete` pipeline every other control in this file uses, so the
+ * shared primitive contract exercised above applies identically there —
+ * pinned here since GradientEditor's own pointer wiring isn't reachable
+ * from this template's jsdom-free test setup.
+ */
+describe("DesignColorPicker gesture lifecycle — GradientEditor stop/angle drags via onCommit passthrough", () => {
+  it("a gradient stop drag (many ticks) commits exactly once, matching SV/hue/alpha", () => {
+    const { onChangeCalls, onChangeCompleteCalls } = simulateDragGesture(12);
+    expect(onChangeCalls.length).toBe(13);
+    expect(onChangeCompleteCalls).toHaveLength(1);
+  });
+
+  it("an angle-dial drag with a single tick still commits exactly once", () => {
+    const { onChangeCompleteCalls } = simulateDragGesture(1);
+    expect(onChangeCompleteCalls).toHaveLength(1);
+  });
+});
+
+describe("DesignColorPicker gesture lifecycle — ScrubbyNumberInput click-drag scrub", () => {
+  it("a plain click (no movement past the threshold) never engages the drag flag", () => {
+    // The gesture object itself doesn't encode "past threshold"; that's the
+    // ScrubbyNumberInput pointermove handler's job. This documents the
+    // idle/start shape the component builds on: a fresh gesture starts
+    // `dragging: false` so a same-spot pointerup is treated as an ordinary
+    // click (focus + select-on-focus), never a commit.
+    const gesture = startScrubGesture(100, 50);
+    expect(gesture.active).toBe(true);
+    expect(gesture.dragging).toBe(false);
+    expect(gesture.startX).toBe(100);
+    expect(gesture.startValue).toBe(50);
+  });
+
+  it("SCRUB_GESTURE_IDLE is fully idle", () => {
+    expect(SCRUB_GESTURE_IDLE.active).toBe(false);
+    expect(SCRUB_GESTURE_IDLE.dragging).toBe(false);
+  });
+
+  it("computeScrubbedValue increases the value when dragging right", () => {
+    expect(computeScrubbedValue(50, 8, 0, 255, false)).toBeGreaterThan(50);
+  });
+
+  it("computeScrubbedValue decreases the value when dragging left", () => {
+    expect(computeScrubbedValue(50, -8, 0, 255, false)).toBeLessThan(50);
+  });
+
+  it("computeScrubbedValue is a no-op for sub-step movement", () => {
+    // 4px is the configured pixels-per-step at the normal rate; less than
+    // half of one step shouldn't round to a nonzero delta.
+    expect(computeScrubbedValue(50, 1, 0, 255, false)).toBe(50);
+  });
+
+  it("computeScrubbedValue clamps at the minimum", () => {
+    expect(computeScrubbedValue(2, -400, 0, 255, false)).toBe(0);
+  });
+
+  it("computeScrubbedValue clamps at the maximum", () => {
+    expect(computeScrubbedValue(250, 400, 0, 255, false)).toBe(255);
+  });
+
+  it("computeScrubbedValue applies a 10x coarser rate with Shift, matching the arrow-key step convention", () => {
+    const normal = computeScrubbedValue(0, 40, 0, 360, false);
+    const shifted = computeScrubbedValue(0, 40, 0, 360, true);
+    expect(shifted).toBe(normal * 10);
+  });
+
+  it("computeScrubbedValue returns exactly startValue for zero movement", () => {
+    expect(computeScrubbedValue(77, 0, 0, 255, false)).toBe(77);
+    expect(computeScrubbedValue(77, 0, 0, 255, true)).toBe(77);
+  });
+});
diff --git a/templates/design/app/components/design/inspector/DesignColorPicker.modes.test.ts b/templates/design/app/components/design/inspector/DesignColorPicker.modes.test.ts
index 4ecf37ba0e..ea4f852531 100644
--- a/templates/design/app/components/design/inspector/DesignColorPicker.modes.test.ts
+++ b/templates/design/app/components/design/inspector/DesignColorPicker.modes.test.ts
@@ -10,14 +10,18 @@
  *     back in on every render).
  */
 
+import { rgbaToHsl, hslToRgba, type RgbaColor } from "@shared/color-utils";
 import { describe, expect, it } from "vitest";
 
 import {
   expandHexShorthand,
   GRADIENT_PAINT_TYPES,
+  hasHexAlpha,
+  hsvToRgba,
   inferPaintType,
   parseNumericDraft,
   resolveActivePaint,
+  rgbaToHsv,
 } from "./DesignColorPicker";
 
 // ─── inferPaintType ───────────────────────────────────────────────────────────
@@ -267,3 +271,168 @@ describe("expandHexShorthand", () => {
     expect(expandHexShorthand("F0")).toBe("F0");
   });
 });
+
+// ─── hasHexAlpha ──────────────────────────────────────────────────────────────
+
+describe("hasHexAlpha", () => {
+  it("detects 4-digit shorthand hex-with-alpha (#RGBA)", () => {
+    expect(hasHexAlpha("F00A")).toBe(true);
+    expect(hasHexAlpha("#f00a")).toBe(true);
+  });
+
+  it("detects 8-digit hex-with-alpha (#RRGGBBAA)", () => {
+    expect(hasHexAlpha("FF0000AA")).toBe(true);
+    expect(hasHexAlpha("#ff0000aa")).toBe(true);
+  });
+
+  it("is case-insensitive", () => {
+    expect(hasHexAlpha("AABBCCDD")).toBe(true);
+    expect(hasHexAlpha("aabbccdd")).toBe(true);
+    expect(hasHexAlpha("AaBbCcDd")).toBe(true);
+  });
+
+  it("returns false for 3-digit and 6-digit hex (no alpha channel)", () => {
+    expect(hasHexAlpha("FFF")).toBe(false);
+    expect(hasHexAlpha("FFFFFF")).toBe(false);
+    expect(hasHexAlpha("#336699")).toBe(false);
+  });
+
+  it("returns false for non-hex or malformed input", () => {
+    expect(hasHexAlpha("")).toBe(false);
+    expect(hasHexAlpha("zzzz")).toBe(false);
+    expect(hasHexAlpha("FF")).toBe(false);
+    expect(hasHexAlpha("FFFFF")).toBe(false); // 5 digits — not a valid length
+  });
+
+  it("tolerates surrounding whitespace", () => {
+    expect(hasHexAlpha("  FF0000AA  ")).toBe(true);
+  });
+});
+
+// ─── RGB <-> HSL / HSB round-trip stability (no drift on repeated conversion) ──
+//
+// Classic bug: converting RGB -> HSL -> RGB (or RGB -> HSV -> RGB) repeatedly,
+// as happens every time a user nudges a value in one mode then switches to
+// another, can "creep" indefinitely if intermediate state is cached instead
+// of always re-derived from a single RGB source of truth. DesignColorPicker
+// always recomputes HSL/HSV fresh from the current RGB `value` on every
+// render (see `hsl`/`hsv` in the component body), so this suite pins that
+// no-cache invariant at the pure-function level.
+//
+// Note: because HSL/HSV store saturation/lightness/value as rounded 0-100
+// integers (matching Figma's own integer HSB/HSL fields), a handful of
+// arbitrary RGB triples are inherently off by ±1 per channel after the very
+// first round trip — that's unavoidable quantization from displaying a
+// continuous color in an integer percent field, not a bug. The bug this
+// suite actually guards against is *unbounded* drift: once an RGB value has
+// gone through one round trip, every further round trip of that same value
+// must reproduce it exactly — a fixed point, not a random walk that keeps
+// creeping every time the user nudges a field or switches modes.
+
+describe("RGB <-> HSL round-trip stability (shared/color-utils)", () => {
+  // Primaries, grayscale, black, and white are exactly representable in
+  // integer HSL and must round-trip losslessly on the very first pass.
+  const exactSamples: RgbaColor[] = [
+    { r: 255, g: 0, b: 0, a: 1 },
+    { r: 0, g: 255, b: 0, a: 1 },
+    { r: 0, g: 0, b: 255, a: 1 },
+    { r: 0, g: 0, b: 0, a: 1 },
+    { r: 255, g: 255, b: 255, a: 1 },
+    { r: 128, g: 128, b: 128, a: 1 },
+  ];
+  // Arbitrary triples that may shift by at most 1 per channel on the first
+  // trip (integer-percent quantization) but must then stay fixed forever.
+  const arbitrarySamples: RgbaColor[] = [
+    { r: 128, g: 64, b: 200, a: 1 },
+    { r: 17, g: 202, b: 91, a: 0.5 },
+    { r: 51, g: 143, b: 199, a: 1 },
+  ];
+
+  it("a single RGB -> HSL -> RGB round trip is exact for primaries/grayscale/black/white", () => {
+    for (const rgb of exactSamples) {
+      const back = hslToRgba(rgbaToHsl(rgb));
+      expect(back.r).toBe(rgb.r);
+      expect(back.g).toBe(rgb.g);
+      expect(back.b).toBe(rgb.b);
+    }
+  });
+
+  it("a single round trip never shifts an arbitrary RGB triple by more than 1 per channel", () => {
+    for (const rgb of arbitrarySamples) {
+      const back = hslToRgba(rgbaToHsl(rgb));
+      expect(Math.abs(back.r - rgb.r)).toBeLessThanOrEqual(1);
+      expect(Math.abs(back.g - rgb.g)).toBeLessThanOrEqual(1);
+      expect(Math.abs(back.b - rgb.b)).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it("repeated round trips do not creep further after the first one stabilizes", () => {
+    for (const rgb of [...exactSamples, ...arbitrarySamples]) {
+      let current = rgb;
+      const seen: RgbaColor[] = [];
+      for (let i = 0; i < 20; i++) {
+        current = hslToRgba(rgbaToHsl(current));
+        seen.push(current);
+      }
+      // Every trip after the first must reproduce the exact same RGB as the
+      // first trip's result — no slow drift across many conversions.
+      const stabilizedAt = seen[0];
+      for (const value of seen) {
+        expect(value.r).toBe(stabilizedAt.r);
+        expect(value.g).toBe(stabilizedAt.g);
+        expect(value.b).toBe(stabilizedAt.b);
+      }
+    }
+  });
+});
+
+describe("RGB <-> HSV round-trip stability (DesignColorPicker internal hsv helpers)", () => {
+  const exactSamples: RgbaColor[] = [
+    { r: 255, g: 0, b: 0, a: 1 },
+    { r: 0, g: 255, b: 0, a: 1 },
+    { r: 0, g: 0, b: 255, a: 1 },
+    { r: 0, g: 0, b: 0, a: 1 },
+    { r: 255, g: 255, b: 255, a: 1 },
+    { r: 128, g: 128, b: 128, a: 1 },
+  ];
+  const arbitrarySamples: RgbaColor[] = [
+    { r: 128, g: 64, b: 200, a: 1 },
+    { r: 17, g: 202, b: 91, a: 0.5 },
+    { r: 51, g: 143, b: 199, a: 1 },
+  ];
+
+  it("a single RGB -> HSV -> RGB round trip is exact for primaries/grayscale/black/white", () => {
+    for (const rgb of exactSamples) {
+      const back = hsvToRgba(rgbaToHsv(rgb));
+      expect(back.r).toBe(rgb.r);
+      expect(back.g).toBe(rgb.g);
+      expect(back.b).toBe(rgb.b);
+    }
+  });
+
+  it("a single round trip never shifts an arbitrary RGB triple by more than 1 per channel", () => {
+    for (const rgb of arbitrarySamples) {
+      const back = hsvToRgba(rgbaToHsv(rgb));
+      expect(Math.abs(back.r - rgb.r)).toBeLessThanOrEqual(1);
+      expect(Math.abs(back.g - rgb.g)).toBeLessThanOrEqual(1);
+      expect(Math.abs(back.b - rgb.b)).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it("repeated round trips do not creep further after the first one stabilizes", () => {
+    for (const rgb of [...exactSamples, ...arbitrarySamples]) {
+      let current = rgb;
+      const seen: RgbaColor[] = [];
+      for (let i = 0; i < 20; i++) {
+        current = hsvToRgba(rgbaToHsv(current));
+        seen.push(current);
+      }
+      const stabilizedAt = seen[0];
+      for (const value of seen) {
+        expect(value.r).toBe(stabilizedAt.r);
+        expect(value.g).toBe(stabilizedAt.g);
+        expect(value.b).toBe(stabilizedAt.b);
+      }
+    }
+  });
+});
diff --git a/templates/design/app/components/design/inspector/DesignColorPicker.tsx b/templates/design/app/components/design/inspector/DesignColorPicker.tsx
index 236ef3ab08..790fd48480 100644
--- a/templates/design/app/components/design/inspector/DesignColorPicker.tsx
+++ b/templates/design/app/components/design/inspector/DesignColorPicker.tsx
@@ -691,22 +691,17 @@ export function DesignColorPicker({
   blendMode,
   onBlendModeChange,
   showBlendMode = false,
-  fillRows: _fillRows,
-  selectedFillId: _selectedFillId,
-  onFillSelect: _onFillSelect,
-  onFillChange: _onFillChange,
-  onAddFill: _onAddFill,
-  onRemoveFill: _onRemoveFill,
+  // Note: fillRows/selectedFillId/onFillSelect/onFillChange/onAddFill/
+  // onRemoveFill and gradientStops/selectedStopId/onGradientStopSelect/
+  // onGradientStopChange/onAddGradientStop/onRemoveGradientStop are
+  // deliberately NOT destructured here — see the "These interfaces remain…"
+  // comment on DesignColorPickerProps above. The popover doesn't render a
+  // fills/gradient-stops list (fill-properties.tsx in edit-panel owns that
+  // UI directly), so binding them to local variables here was dead code.
   paintType,
   onPaintTypeChange,
   gradientType,
   onGradientTypeChange,
-  gradientStops: _gradientStops,
-  selectedStopId: _selectedStopId,
-  onGradientStopSelect: _onGradientStopSelect,
-  onGradientStopChange: _onGradientStopChange,
-  onAddGradientStop: _onAddGradientStop,
-  onRemoveGradientStop: _onRemoveGradientStop,
   documentColors,
   supportedPaintTypes,
   shaderContext,
@@ -752,6 +747,18 @@ export function DesignColorPicker({
   const [hexDraft, setHexDraft] = useState(() => toDisplayHex(color));
   const hexDraftRef = useRef(hexDraft);
   const [open, setOpen] = useState(false);
+  // Snapshot of value/opacity/paintType captured the instant the popover
+  // opens, so Escape can cancel the whole editing session — matching Figma:
+  // dragging hue/sat/alpha/gradient stops live-previews the color, but
+  // Escaping out reverts everything back to how it was before the popover
+  // opened, not just whatever field happens to be focused. Re-snapshotted
+  // only on the open transition (see the effect below), never while already
+  // open, so it doesn't chase the user's own edits.
+  const openSnapshotRef = useRef({
+    value,
+    opacity: effectiveOpacity,
+    paintType,
+  });
   const [picking, setPicking] = useState(false);
   const skipNextHexBlurCommitRef = useRef(false);
   // Preserve the last non-zero hue so dragging through an achromatic point
@@ -835,6 +842,16 @@ export function DesignColorPicker({
     setHexDraft(nextHex);
   }, [color.r, color.g, color.b]);
 
+  useEffect(() => {
+    if (open) {
+      openSnapshotRef.current = { value, opacity: effectiveOpacity, paintType };
+    }
+    // Deliberately only depends on `open`: this must capture the value as of
+    // the open transition, not re-run on every edit made while already open
+    // (that would defeat the point of an Escape-to-cancel snapshot).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
   // The local override (the user's explicit paint-type click) persists for the
   // life of the open popover so EditPanel bouncing `paintType` back to solid
   // can't wipe a just-selected gradient/image/shader. A new element selection
@@ -1015,15 +1032,31 @@ export function DesignColorPicker({
       onImageFillChange(next);
       return;
     }
+    // ImageFillControls has no drag surface of its own (URL entry, file
+    // pick, and fit selection are each already a discrete, complete action),
+    // so — unlike the SV field / hue / alpha tracks — every onChange call
+    // here is itself a final commit, never a live-preview tick.
     emitPaintValue(imageFillToCss(next));
+    notifyChangeComplete();
   };
 
   // ── Shader editing ──────────────────────────────────────────────────────────────
 
-  const emitShader = (descriptor: ShaderDescriptor, css: string) => {
+  // Cheap live preview — fires on every ShaderFillsPanel tuning tick. Must
+  // not call notifyChangeComplete (that's the expensive-commit signal), or
+  // every drag tick would dirty undo history the same way an un-split
+  // onChange/onChangeComplete would for color/gradient dragging.
+  const previewShader = (descriptor: ShaderDescriptor, css: string) => {
+    setShaderDescriptor(descriptor);
+    emitPaintValue(css);
+  };
+
+  // Fires once per gesture/discrete pick (see ShaderFillsPanel's onCommit).
+  const commitShader = (descriptor: ShaderDescriptor, css: string) => {
     setShaderDescriptor(descriptor);
     onShaderChange?.(descriptor, css);
     emitPaintValue(css);
+    notifyChangeComplete();
   };
 
   // ── Paint-type switching (does real work for every type) ──────────────────────
@@ -1134,6 +1167,29 @@ export function DesignColorPicker({
 
   const hasEyeDropper = hasEyeDropperSupport();
 
+  // Cancels the whole editing session back to the snapshot captured when the
+  // popover opened — the Escape-key contract (matches Figma: any live-preview
+  // dragging done while the popover was open gets thrown away, not just
+  // whatever field currently has focus). Resets every local override so the
+  // effective paint type / gradient / shader recompute cleanly from the
+  // reverted props on the next render.
+  const revertToOpenSnapshot = () => {
+    if (disabled) return;
+    const snapshot = openSnapshotRef.current;
+    setLocalPaintType(null);
+    setLocalGradient(null);
+    setSelectedStopId("");
+    setShaderDescriptor(null);
+    setView("picker");
+    if (onPaintTypeChange && snapshot.paintType !== undefined) {
+      onPaintTypeChange(snapshot.paintType);
+    }
+    if (onOpacityChange) onOpacityChange(snapshot.opacity);
+    lastEmittedValueRef.current = snapshot.value;
+    onChange(snapshot.value);
+    onChangeComplete?.(snapshot.value);
+  };
+
   // ── Value row inputs by mode ─────────────────────────────────────────────────
 
   function renderValueInputs() {
@@ -1185,6 +1241,7 @@ export function DesignColorPicker({
               max={255}
               disabled={disabled}
               onChange={(next) => emitFieldColor({ ...fieldColor, [ch]: next })}
+              onCommit={notifyChangeComplete}
             />
           ))}
         </div>
@@ -1200,6 +1257,7 @@ export function DesignColorPicker({
             max={360}
             disabled={disabled}
             onChange={(h) => emitFieldHsl({ ...fieldHsl, h })}
+            onCommit={notifyChangeComplete}
           />
           <ScrubbyNumberInput
             aria-label={copy.saturation}
@@ -1208,6 +1266,7 @@ export function DesignColorPicker({
             max={100}
             disabled={disabled}
             onChange={(s) => emitFieldHsl({ ...fieldHsl, s })}
+            onCommit={notifyChangeComplete}
           />
           <ScrubbyNumberInput
             aria-label={copy.lightness}
@@ -1216,6 +1275,7 @@ export function DesignColorPicker({
             max={100}
             disabled={disabled}
             onChange={(l) => emitFieldHsl({ ...fieldHsl, l })}
+            onCommit={notifyChangeComplete}
           />
         </div>
       );
@@ -1230,6 +1290,7 @@ export function DesignColorPicker({
           max={360}
           disabled={disabled}
           onChange={(h) => emitFieldHsv({ ...fieldHsv, h })}
+          onCommit={notifyChangeComplete}
         />
         <ScrubbyNumberInput
           aria-label={copy.saturation}
@@ -1238,6 +1299,7 @@ export function DesignColorPicker({
           max={100}
           disabled={disabled}
           onChange={(s) => emitFieldHsv({ ...fieldHsv, s })}
+          onCommit={notifyChangeComplete}
         />
         <ScrubbyNumberInput
           aria-label={copy.brightness}
@@ -1246,6 +1308,7 @@ export function DesignColorPicker({
           max={100}
           disabled={disabled}
           onChange={(v) => emitFieldHsv({ ...fieldHsv, v })}
+          onCommit={notifyChangeComplete}
         />
       </div>
     );
@@ -1298,6 +1361,11 @@ export function DesignColorPicker({
           // re-projection can't close the popover. Genuine pointer clicks
           // outside still close it via the default onInteractOutside behavior.
           onFocusOutside={(e) => e.preventDefault()}
+          // Escape cancels the whole editing session (see revertToOpenSnapshot)
+          // and then still closes the popover via Radix's default dismiss
+          // behavior — this only reverts the color/opacity/paint-type state,
+          // it doesn't call `e.preventDefault()`, so the close still happens.
+          onEscapeKeyDown={revertToOpenSnapshot}
         >
           <div className="rounded-md bg-popover text-popover-foreground">
             {view === "shader" && glslShaderContext ? (
@@ -1320,7 +1388,8 @@ export function DesignColorPicker({
                 descriptor={shaderDescriptor ?? undefined}
                 applyContext={shaderContext}
                 disabled={disabled}
-                onApply={emitShader}
+                onApply={previewShader}
+                onCommit={commitShader}
                 onBack={() => {
                   setView("picker");
                   if (effectivePaintType === "shader") {
@@ -1452,19 +1521,23 @@ export function DesignColorPicker({
                         if (e.key === "Enter") {
                           e.preventDefault();
                           const url = e.currentTarget.value.trim();
-                          if (url)
+                          if (url) {
                             emitPaintValue(
                               `url("${url}") center / cover no-repeat`,
                             );
+                            notifyChangeComplete();
+                          }
                           e.currentTarget.blur();
                         }
                       }}
                       onBlur={(e) => {
                         const url = e.currentTarget.value.trim();
-                        if (url)
+                        if (url) {
                           emitPaintValue(
                             `url("${url}") center / cover no-repeat`,
                           );
+                          notifyChangeComplete();
+                        }
                       }}
                     />
                   </div>
@@ -1479,6 +1552,7 @@ export function DesignColorPicker({
                       disabled={disabled}
                       onSelectStop={setSelectedStopId}
                       onChange={emitGradient}
+                      onCommit={notifyChangeComplete}
                     />
                   </div>
                 )}
@@ -1660,6 +1734,7 @@ export function DesignColorPicker({
                               setOpacity(next);
                             }
                           }}
+                          onCommit={notifyChangeComplete}
                           className="h-full min-w-0 flex-1 rounded-none border-0 bg-transparent px-1 !text-[11px] tabular-nums shadow-none focus-visible:ring-0"
                           compact
                         />
@@ -1959,7 +2034,7 @@ function SaturationBrightnessField({
       }}
       onKeyDown={stepWithKeyboard}
       className={cn(
-        "relative h-48 w-full cursor-crosshair overflow-hidden outline-none",
+        "relative h-48 w-full touch-none cursor-crosshair overflow-hidden outline-none",
         "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
         "active:cursor-grabbing",
         disabled && "cursor-not-allowed opacity-60",
@@ -2080,7 +2155,7 @@ function ColorTrack({
         if (ended.shouldCommit) onCommit?.();
       }}
       className={cn(
-        "relative h-3.5 cursor-pointer rounded-full border border-border/60 outline-none",
+        "relative h-3.5 touch-none cursor-pointer rounded-full border border-border/60 outline-none",
         "ring-offset-background focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
         "active:cursor-grabbing",
         disabled && "cursor-not-allowed opacity-60",
@@ -2097,7 +2172,14 @@ function ColorTrack({
 }
 
 /**
- * A number input with select-on-focus and Esc-to-revert.
+ * A number input with select-on-focus, Esc-to-revert, arrow-key nudging, and
+ * Figma-style click-drag "scrubbing": pressing down and dragging left/right
+ * decrements/increments the value continuously (Shift = 10x coarser step,
+ * matching the same shift convention as arrow-key nudges and the SV/hue/alpha
+ * tracks) without needing to type. A short press-release with no meaningful
+ * movement is treated as an ordinary click so focus + select-on-focus (and
+ * therefore typing) keep working exactly as before.
+ *
  * The `compact` prop removes inner padding for use inside bordered wrappers.
  */
 function ScrubbyNumberInput({
@@ -2107,6 +2189,7 @@ function ScrubbyNumberInput({
   max,
   disabled,
   onChange,
+  onCommit,
   className,
   compact = false,
 }: {
@@ -2116,12 +2199,22 @@ function ScrubbyNumberInput({
   max: number;
   disabled: boolean;
   onChange: (value: number) => void;
+  /**
+   * Fires once per discrete, complete edit: a blur/Enter commit (only when
+   * the draft actually parsed — not on a revert), each arrow-key step, and
+   * once at the end of a scrub drag (not per pointermove tick). Mirrors the
+   * `onCommit` contract used by SaturationBrightnessField/ColorTrack so every
+   * draggable/steppable control in this picker notifies
+   * `onChangeComplete` exactly once per gesture.
+   */
+  onCommit?: () => void;
   className?: string;
   compact?: boolean;
 }) {
   const [draft, setDraft] = useState<string>(() => String(value));
   const draftRef = useRef(draft);
   const skipBlurRef = useRef(false);
+  const scrubRef = useRef<ScrubGestureState>(SCRUB_GESTURE_IDLE);
 
   useEffect(() => {
     const nextDraft = String(value);
@@ -2138,6 +2231,7 @@ function ScrubbyNumberInput({
       return;
     }
     onChange(clamp(parsed, min, max));
+    onCommit?.();
   };
 
   return (
@@ -2149,8 +2243,15 @@ function ScrubbyNumberInput({
       max={max}
       disabled={disabled}
       className={cn(
-        "h-6 w-full rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] text-center !text-[11px] tabular-nums",
+        "h-6 w-full touch-none rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] text-center !text-[11px] tabular-nums",
         "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        // Figma's numeric fields never show the native up/down spinner —
+        // hide it in both engines so this reads as a plain scrubbable value,
+        // not a browser default number input. (The spinner buttons also
+        // bypassed this component's onChange/onCommit contract entirely,
+        // since native stepper clicks only mutate the draft string, not the
+        // color — hiding them removes that dead, contract-violating path.)
+        "[appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none",
         compact && "border-0 shadow-none focus-visible:ring-0",
         className,
       )}
@@ -2179,6 +2280,7 @@ function ScrubbyNumberInput({
           const parsed = Number(draftRef.current);
           const base = Number.isFinite(parsed) ? parsed : value;
           onChange(clamp(base + step, min, max));
+          onCommit?.();
         }
         if (e.key === "ArrowDown") {
           e.preventDefault();
@@ -2186,6 +2288,7 @@ function ScrubbyNumberInput({
           const parsed = Number(draftRef.current);
           const base = Number.isFinite(parsed) ? parsed : value;
           onChange(clamp(base - step, min, max));
+          onCommit?.();
         }
       }}
       onBlur={() => {
@@ -2195,6 +2298,58 @@ function ScrubbyNumberInput({
         }
         commit();
       }}
+      onPointerDown={(e) => {
+        if (disabled) return;
+        // Don't preventDefault here — a plain click (no subsequent movement
+        // past the threshold) must still focus the input normally so typing
+        // keeps working. Pointer capture just ensures a real drag keeps
+        // routing to this element even once the cursor leaves its bounds.
+        scrubRef.current = startScrubGesture(e.clientX, value);
+        e.currentTarget.setPointerCapture(e.pointerId);
+      }}
+      onPointerMove={(e) => {
+        if (disabled || !scrubRef.current.active) return;
+        const deltaX = e.clientX - scrubRef.current.startX;
+        if (!scrubRef.current.dragging) {
+          if (Math.abs(deltaX) < SCRUB_DRAG_THRESHOLD_PX) return;
+          scrubRef.current = { ...scrubRef.current, dragging: true };
+          // Now that this is a genuine drag (not a click), stop the browser
+          // from turning the pointer move into a text-selection drag.
+          window.getSelection?.()?.removeAllRanges();
+        }
+        e.preventDefault();
+        onChange(
+          computeScrubbedValue(
+            scrubRef.current.startValue,
+            deltaX,
+            min,
+            max,
+            e.shiftKey,
+          ),
+        );
+      }}
+      onPointerUp={(e) => {
+        const wasDragging = scrubRef.current.dragging;
+        scrubRef.current = SCRUB_GESTURE_IDLE;
+        if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+          e.currentTarget.releasePointerCapture(e.pointerId);
+        }
+        if (wasDragging) {
+          onCommit?.();
+          // A drag ended without focusing the field for text entry — match
+          // Figma (dragging a number field doesn't leave it in edit mode).
+          skipBlurRef.current = true;
+          e.currentTarget.blur();
+        }
+      }}
+      onPointerCancel={(e) => {
+        const wasDragging = scrubRef.current.dragging;
+        scrubRef.current = SCRUB_GESTURE_IDLE;
+        if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+          e.currentTarget.releasePointerCapture(e.pointerId);
+        }
+        if (wasDragging) onCommit?.();
+      }}
     />
   );
 }
@@ -2230,6 +2385,61 @@ export function endPointerGesture(state: PointerGestureState): {
   return { state: POINTER_GESTURE_IDLE, shouldCommit: state };
 }
 
+// ─── Click-drag "scrub" tracking for ScrubbyNumberInput ────────────────────────
+//
+// A plain pointerdown+pointerup with no meaningful movement must behave like
+// an ordinary click (focus the input, select-on-focus, allow typing) — it
+// only becomes a scrub once the pointer has moved past a small pixel
+// threshold, matching Figma's numeric fields (click to type, click-drag to
+// scrub). `dragging` flips true exactly once per gesture, the first time the
+// threshold is crossed.
+
+const SCRUB_DRAG_THRESHOLD_PX = 3;
+/** Pixels of drag per 1 unit of value change at the normal (non-Shift) rate. */
+const SCRUB_PIXELS_PER_STEP = 4;
+
+export interface ScrubGestureState {
+  /** True from pointerdown until the matching pointerup/pointercancel. */
+  active: boolean;
+  /** True once the drag has crossed the click-vs-drag threshold. */
+  dragging: boolean;
+  startX: number;
+  startValue: number;
+}
+
+export const SCRUB_GESTURE_IDLE: ScrubGestureState = {
+  active: false,
+  dragging: false,
+  startX: 0,
+  startValue: 0,
+};
+
+/** Call on pointerdown: starts tracking a new potential scrub gesture. */
+export function startScrubGesture(
+  startX: number,
+  startValue: number,
+): ScrubGestureState {
+  return { active: true, dragging: false, startX, startValue };
+}
+
+/**
+ * Pure math for one scrub tick: converts total horizontal drag distance
+ * (from the gesture's start position) into a new clamped value. Shift scales
+ * the rate 10x coarser, matching the same shift convention as arrow-key
+ * nudges and the SV/hue/alpha track keyboard steps.
+ */
+export function computeScrubbedValue(
+  startValue: number,
+  deltaX: number,
+  min: number,
+  max: number,
+  shiftKey: boolean,
+): number {
+  const rate = shiftKey ? 10 : 1;
+  const delta = Math.round(deltaX / SCRUB_PIXELS_PER_STEP) * rate;
+  return clamp(startValue + delta, min, max);
+}
+
 // ─── Utilities ─────────────────────────────────────────────────────────────────
 
 export function inferPaintType(
@@ -2388,7 +2598,7 @@ function alphaTrackBackground(color: RgbaColor): string {
   return `${CHECKERBOARD_IMAGE}, linear-gradient(90deg, rgba(${color.r}, ${color.g}, ${color.b}, 0), rgba(${color.r}, ${color.g}, ${color.b}, 1))`;
 }
 
-function rgbaToHsv(color: RgbaColor): HsvaColor {
+export function rgbaToHsv(color: RgbaColor): HsvaColor {
   const r = clampFloat(color.r / 255, 0, 1);
   const g = clampFloat(color.g / 255, 0, 1);
   const b = clampFloat(color.b / 255, 0, 1);
@@ -2413,7 +2623,7 @@ function rgbaToHsv(color: RgbaColor): HsvaColor {
   };
 }
 
-function hsvToRgba(color: HsvaColor): RgbaColor {
+export function hsvToRgba(color: HsvaColor): RgbaColor {
   const h = ((color.h % 360) + 360) % 360;
   const s = clampFloat(color.s, 0, 100) / 100;
   const v = clampFloat(color.v, 0, 100) / 100;
@@ -2449,7 +2659,7 @@ function clampFloat(value: number, min: number, max: number): number {
   return Math.max(min, Math.min(max, value));
 }
 
-function hasHexAlpha(value: string): boolean {
+export function hasHexAlpha(value: string): boolean {
   return /^#?(?:[0-9a-f]{4}|[0-9a-f]{8})$/i.test(value.trim());
 }
 
diff --git a/templates/design/app/components/design/inspector/GradientEditor.interaction.test.tsx b/templates/design/app/components/design/inspector/GradientEditor.interaction.test.tsx
new file mode 100644
index 0000000000..bb7cb4df6e
--- /dev/null
+++ b/templates/design/app/components/design/inspector/GradientEditor.interaction.test.tsx
@@ -0,0 +1,367 @@
+// @vitest-environment happy-dom
+
+/**
+ * Gesture-lifecycle tests for GradientEditor's `onCommit` (added alongside
+ * this test): `onChange` alone fires on every stop-drag / angle-drag
+ * pointermove tick (cheap live preview), while `onCommit` must fire exactly
+ * once per gesture — mirroring the onChange/onChangeComplete split already
+ * used by DesignColorPicker and the preview/commit `phase` split used by
+ * ScrubInput (see ScrubInput.gesture.test.ts). Before this fix, GradientEditor
+ * had no way at all to signal "this gesture is done" — every discrete action
+ * (add/remove a stop, drag a stop, drag the angle dial, commit a position/
+ * angle field) only ever called `onChange`, so a caller wired to persist on
+ * "commit" (like DesignColorPicker's `notifyChangeComplete`) never fired
+ * during gradient editing, or — if a caller (mis)treated every onChange as a
+ * commit — persisted a new history entry on every single pointermove tick of
+ * a drag ("commit storm").
+ */
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/components/ui/tooltip", () => ({
+  Tooltip: ({ children }: { children?: unknown }) => children as never,
+  TooltipTrigger: ({ children }: { children?: unknown }) => children as never,
+  TooltipContent: ({ children }: { children?: unknown }) => children as never,
+  TooltipProvider: ({ children }: { children?: unknown }) => children as never,
+}));
+
+import { GradientEditor, type GradientValue } from "./GradientEditor";
+
+const baseValue: GradientValue = {
+  kind: "linear",
+  angle: 90,
+  stops: [
+    { id: "a", color: "#ff0000", position: 0 },
+    { id: "b", color: "#0000ff", position: 100 },
+  ],
+};
+
+let container: HTMLDivElement;
+let root: ReturnType<typeof createRoot>;
+let originalRect: typeof HTMLElement.prototype.getBoundingClientRect;
+
+beforeEach(() => {
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+  // The bar's position math (`positionFromPointer`) divides by the bar's
+  // measured width, which happy-dom reports as 0 with no layout engine —
+  // stub a fixed 200px-wide rect starting at x=0 so clientX maps to a
+  // predictable 0-100 position.
+  originalRect = HTMLElement.prototype.getBoundingClientRect;
+  HTMLElement.prototype.getBoundingClientRect = function (this: HTMLElement) {
+    return {
+      x: 0,
+      y: 0,
+      top: 0,
+      left: 0,
+      right: 200,
+      bottom: 16,
+      width: 200,
+      height: 16,
+      toJSON() {
+        return {};
+      },
+    } as DOMRect;
+  };
+});
+
+afterEach(() => {
+  HTMLElement.prototype.getBoundingClientRect = originalRect;
+  act(() => root.unmount());
+  container.remove();
+});
+
+function pointerEvent(
+  type: string,
+  init: { clientX: number; pointerId?: number },
+) {
+  return new PointerEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    clientX: init.clientX,
+    pointerId: init.pointerId ?? 1,
+  });
+}
+
+describe("GradientEditor onCommit", () => {
+  it("fires onChange on every tick but onCommit exactly once when dragging a stop handle", () => {
+    const onChange = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <GradientEditor
+          value={baseValue}
+          onChange={onChange}
+          onCommit={onCommit}
+          selectedStopId="a"
+          onSelectStop={vi.fn()}
+        />,
+      );
+    });
+
+    const handle = container.querySelector<HTMLButtonElement>(
+      'button[aria-label^="#ff0000"]',
+    );
+    expect(handle).not.toBeNull();
+
+    act(() => {
+      handle!.dispatchEvent(pointerEvent("pointerdown", { clientX: 0 }));
+      handle!.dispatchEvent(pointerEvent("pointermove", { clientX: 20 }));
+      handle!.dispatchEvent(pointerEvent("pointermove", { clientX: 40 }));
+      handle!.dispatchEvent(pointerEvent("pointerup", { clientX: 40 }));
+    });
+
+    expect(onChange).toHaveBeenCalledTimes(2);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire onCommit for a plain click-to-select with no movement", () => {
+    const onChange = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <GradientEditor
+          value={baseValue}
+          onChange={onChange}
+          onCommit={onCommit}
+          selectedStopId="a"
+          onSelectStop={vi.fn()}
+        />,
+      );
+    });
+
+    const handle = container.querySelector<HTMLButtonElement>(
+      'button[aria-label^="#0000ff"]',
+    );
+    expect(handle).not.toBeNull();
+
+    act(() => {
+      handle!.dispatchEvent(pointerEvent("pointerdown", { clientX: 200 }));
+      handle!.dispatchEvent(pointerEvent("pointerup", { clientX: 200 }));
+    });
+
+    expect(onChange).not.toHaveBeenCalled();
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it("fires onChange and onCommit exactly once when adding a stop via a bar click", () => {
+    const onChange = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <GradientEditor
+          value={baseValue}
+          onChange={onChange}
+          onCommit={onCommit}
+          selectedStopId="a"
+          onSelectStop={vi.fn()}
+        />,
+      );
+    });
+
+    const bar = container.querySelector<HTMLDivElement>(
+      '[aria-label="Gradient stops"]',
+    );
+    expect(bar).not.toBeNull();
+
+    act(() => {
+      bar!.dispatchEvent(pointerEvent("pointerdown", { clientX: 100 }));
+      bar!.dispatchEvent(pointerEvent("pointerup", { clientX: 100 }));
+    });
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it("fires onCommit exactly once when removing the selected stop via the trash button", () => {
+    const onChange = vi.fn();
+    const onCommit = vi.fn();
+    // removeStop no-ops at exactly 2 stops (a gradient needs at least 2), so
+    // this needs a 3rd stop for the remove button to actually be enabled.
+    const threeStopValue: GradientValue = {
+      ...baseValue,
+      stops: [...baseValue.stops, { id: "c", color: "#00ff00", position: 50 }],
+    };
+
+    act(() => {
+      root.render(
+        <GradientEditor
+          value={threeStopValue}
+          onChange={onChange}
+          onCommit={onCommit}
+          selectedStopId="c"
+          onSelectStop={vi.fn()}
+        />,
+      );
+    });
+
+    const removeButton = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Remove stop"]',
+    );
+    expect(removeButton).not.toBeNull();
+
+    act(() => removeButton!.click());
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it("removes a stop on Backspace/Delete when its handle is focused", () => {
+    const onChange = vi.fn();
+    const onCommit = vi.fn();
+    const threeStopValue: GradientValue = {
+      ...baseValue,
+      stops: [...baseValue.stops, { id: "c", color: "#00ff00", position: 50 }],
+    };
+
+    act(() => {
+      root.render(
+        <GradientEditor
+          value={threeStopValue}
+          onChange={onChange}
+          onCommit={onCommit}
+          selectedStopId="c"
+          onSelectStop={vi.fn()}
+        />,
+      );
+    });
+
+    const handle = container.querySelector<HTMLButtonElement>(
+      'button[aria-label^="#00ff00"]',
+    );
+    expect(handle).not.toBeNull();
+
+    act(() => {
+      handle!.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "Backspace", bubbles: true }),
+      );
+    });
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange.mock.calls[0][0].stops).toHaveLength(2);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it("nudges a focused stop's position by 1 with ArrowRight/ArrowLeft and commits once per press", () => {
+    const onChange = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <GradientEditor
+          value={baseValue}
+          onChange={onChange}
+          onCommit={onCommit}
+          selectedStopId="a"
+          onSelectStop={vi.fn()}
+        />,
+      );
+    });
+
+    const handle = container.querySelector<HTMLButtonElement>(
+      'button[aria-label^="#ff0000"]',
+    );
+    expect(handle).not.toBeNull();
+
+    act(() => {
+      handle!.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "ArrowRight",
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+    });
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    const updatedStops = onChange.mock.calls[0][0].stops as Array<{
+      id: string;
+      position: number;
+    }>;
+    expect(updatedStops.find((s) => s.id === "a")?.position).toBe(1);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire onCommit when the angle field is focused and blurred without editing", () => {
+    const onChange = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <GradientEditor
+          value={baseValue}
+          onChange={onChange}
+          onCommit={onCommit}
+          selectedStopId="a"
+          onSelectStop={vi.fn()}
+        />,
+      );
+    });
+
+    const angleField = container.querySelector<HTMLInputElement>(
+      'input[aria-label="Gradient angle"]',
+    );
+    expect(angleField).not.toBeNull();
+
+    act(() => {
+      // React implements onBlur via the native (bubbling) "focusout" event
+      // rather than "blur" (which doesn't bubble) — see React's
+      // SimpleEventPlugin. Dispatch that here so the synthetic handler
+      // actually fires.
+      angleField!.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+      angleField!.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+    });
+
+    expect(onChange).not.toHaveBeenCalled();
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it("fires onCommit exactly once when the angle field is edited and blurred", () => {
+    const onChange = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <GradientEditor
+          value={baseValue}
+          onChange={onChange}
+          onCommit={onCommit}
+          selectedStopId="a"
+          onSelectStop={vi.fn()}
+        />,
+      );
+    });
+
+    const angleField = container.querySelector<HTMLInputElement>(
+      'input[aria-label="Gradient angle"]',
+    );
+    expect(angleField).not.toBeNull();
+
+    act(() => {
+      // Bypass React's tracked-value setter so the synthetic onChange
+      // handler actually observes the new value (a plain `.value =`
+      // assignment followed by a bare "input" event dispatch is a no-op
+      // under React's controlled-input change detection).
+      const setValue = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        "value",
+      )?.set;
+      setValue?.call(angleField, "180");
+      angleField!.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onCommit).not.toHaveBeenCalled();
+
+    act(() => {
+      angleField!.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+    });
+
+    expect(onCommit).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/templates/design/app/components/design/inspector/GradientEditor.tsx b/templates/design/app/components/design/inspector/GradientEditor.tsx
index 7b340ce9c9..05b3330bfd 100644
--- a/templates/design/app/components/design/inspector/GradientEditor.tsx
+++ b/templates/design/app/components/design/inspector/GradientEditor.tsx
@@ -285,11 +285,18 @@ export function parseGradientCss(
 interface AngleDialProps {
   angle: number;
   onChange: (angle: number) => void;
+  /** Fires once when a drag gesture ends (pointerup/pointercancel) — see GradientEditorProps.onCommit. */
+  onCommit?: () => void;
   disabled?: boolean;
 }
 
 /** design-editor circular dial for rotating gradient angle. */
-function AngleDial({ angle, onChange, disabled = false }: AngleDialProps) {
+function AngleDial({
+  angle,
+  onChange,
+  onCommit,
+  disabled = false,
+}: AngleDialProps) {
   const dialRef = useRef<HTMLDivElement>(null);
   const draggingRef = useRef(false);
 
@@ -319,10 +326,12 @@ function AngleDial({ angle, onChange, disabled = false }: AngleDialProps) {
   };
 
   const handlePointerUp = (e: ReactPointerEvent<HTMLDivElement>) => {
+    const wasDragging = draggingRef.current;
     draggingRef.current = false;
     if (e.currentTarget.hasPointerCapture(e.pointerId)) {
       e.currentTarget.releasePointerCapture(e.pointerId);
     }
+    if (wasDragging) onCommit?.();
   };
 
   const dotAngle = ((angle - 90) * Math.PI) / 180;
@@ -349,9 +358,11 @@ function AngleDial({ angle, onChange, disabled = false }: AngleDialProps) {
         if (e.key === "ArrowRight" || e.key === "ArrowUp") {
           e.preventDefault();
           onChange((angle + 1) % 360);
+          onCommit?.();
         } else if (e.key === "ArrowLeft" || e.key === "ArrowDown") {
           e.preventDefault();
           onChange((angle - 1 + 360) % 360);
+          onCommit?.();
         }
       }}
       className={cn(
@@ -394,6 +405,18 @@ function AngleDial({ angle, onChange, disabled = false }: AngleDialProps) {
 export interface GradientEditorProps {
   value: GradientValue;
   onChange: (value: GradientValue) => void;
+  /**
+   * Fires once per discrete edit or drag gesture — mirrors the
+   * `onChangeComplete` convention used by `DesignColorPickerProps` (see the
+   * doc comment there): `onChange` alone fires on every stop-drag/angle-drag
+   * pointermove tick (cheap live preview), while `onCommit` fires exactly
+   * once (stop added, stop removed, stop-drag pointerup, angle-drag
+   * pointerup, or a position/angle field committed via blur/Enter) so a
+   * caller that persists through history only records one entry per gesture
+   * instead of one per tick. Optional so existing callers that only wired
+   * `onChange` keep their current every-tick-is-final behavior.
+   */
+  onCommit?: () => void;
   selectedStopId: string;
   onSelectStop: (id: string) => void;
   disabled?: boolean;
@@ -412,6 +435,7 @@ const WRAPPER_HEIGHT = BAR_HEIGHT + HANDLE_AREA; // total component height
 export function GradientEditor({
   value,
   onChange,
+  onCommit,
   selectedStopId,
   onSelectStop,
   disabled = false,
@@ -419,6 +443,10 @@ export function GradientEditor({
 }: GradientEditorProps) {
   const barRef = useRef<HTMLDivElement>(null);
   const draggingStopRef = useRef<string | null>(null);
+  // Set once a stop-drag actually moves the pointer (vs a plain click that
+  // only selects the stop) — endStopDrag uses this to skip firing onCommit
+  // for a no-op "select" click where nothing actually changed.
+  const stopDragMovedRef = useRef(false);
   // Track whether a pointerdown on the bar started a drag (vs click-to-add).
   const barClickRef = useRef<{ moved: boolean; startX: number } | null>(null);
 
@@ -502,6 +530,7 @@ export function GradientEditor({
     };
     onChange({ ...value, stops: [...value.stops, newStop] });
     onSelectStop(newStop.id);
+    onCommit?.();
   };
 
   const startStopDrag = (
@@ -513,6 +542,7 @@ export function GradientEditor({
     event.preventDefault();
     onSelectStop(id);
     draggingStopRef.current = id;
+    stopDragMovedRef.current = false;
     event.currentTarget.setPointerCapture(event.pointerId);
   };
 
@@ -520,6 +550,7 @@ export function GradientEditor({
     event: ReactPointerEvent<HTMLButtonElement>,
   ) => {
     if (!draggingStopRef.current || disabled) return;
+    stopDragMovedRef.current = true;
     updateStopPosition(
       draggingStopRef.current,
       positionFromPointer(event.clientX),
@@ -527,10 +558,14 @@ export function GradientEditor({
   };
 
   const endStopDrag = (event: ReactPointerEvent<HTMLButtonElement>) => {
+    const wasDragging =
+      draggingStopRef.current !== null && stopDragMovedRef.current;
     draggingStopRef.current = null;
+    stopDragMovedRef.current = false;
     if (event.currentTarget.hasPointerCapture(event.pointerId)) {
       event.currentTarget.releasePointerCapture(event.pointerId);
     }
+    if (wasDragging) onCommit?.();
   };
 
   const removeStop = (id: string) => {
@@ -541,6 +576,7 @@ export function GradientEditor({
     if (selectedStopId === id) {
       onSelectStop(nearestStopId(nextStops, removed?.position) ?? "");
     }
+    onCommit?.();
   };
 
   const setAngle = (angle: number) => {
@@ -576,6 +612,7 @@ export function GradientEditor({
       return;
     }
     updateStopPosition(selectedStopId, parsed);
+    onCommit?.();
   };
 
   const revertPositionDraft = () => {
@@ -651,6 +688,28 @@ export function GradientEditor({
                 e.stopPropagation();
                 removeStop(stop.id);
               }}
+              onKeyDown={(e) => {
+                if (disabled) return;
+                // Figma parity: Delete/Backspace removes the focused stop,
+                // and Left/Right nudges its position (Shift for a bigger
+                // step) — mirrors the numeric position field's arrow-key
+                // behavior but works directly on the handle too.
+                if (e.key === "Delete" || e.key === "Backspace") {
+                  e.preventDefault();
+                  removeStop(stop.id);
+                  return;
+                }
+                if (e.key === "ArrowLeft" || e.key === "ArrowRight") {
+                  e.preventDefault();
+                  const step = e.shiftKey ? 10 : 1;
+                  const delta = e.key === "ArrowRight" ? step : -step;
+                  updateStopPosition(
+                    stop.id,
+                    clamp(stop.position + delta, 0, 100),
+                  );
+                  onCommit?.();
+                }
+              }}
               className={cn(
                 // Base: round handle with white border ring + outer accent ring
                 "absolute cursor-grab active:cursor-grabbing",
@@ -724,6 +783,7 @@ export function GradientEditor({
             <AngleDial
               angle={value.angle}
               onChange={setAngle}
+              onCommit={onCommit}
               disabled={disabled}
             />
             <div className="flex h-6 w-14 items-center overflow-hidden rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)]">
@@ -744,7 +804,17 @@ export function GradientEditor({
                     setAngleInput(e.target.value);
                   }
                 }}
-                onBlur={() => setAngleInput(null)}
+                onBlur={() => {
+                  // `angleInput` is only non-null once the user has actually
+                  // typed into this field (see onChange below) — mirrors the
+                  // sibling stop-position field's commitPositionDraft, which
+                  // only commits on an actual edit rather than unconditionally
+                  // on every blur (tabbing through/refocusing without typing
+                  // must not re-fire the commit).
+                  const changed = angleInput !== null;
+                  setAngleInput(null);
+                  if (changed) onCommit?.();
+                }}
                 className="h-full min-w-0 flex-1 bg-transparent px-1.5 !text-[11px] tabular-nums focus-visible:outline-none"
               />
               <span className="flex w-4 shrink-0 items-center justify-center text-[10px] text-muted-foreground">
diff --git a/templates/design/app/components/design/inspector/ScrubInput.gesture.test.ts b/templates/design/app/components/design/inspector/ScrubInput.gesture.test.ts
index c2790049ba..7294f57a36 100644
--- a/templates/design/app/components/design/inspector/ScrubInput.gesture.test.ts
+++ b/templates/design/app/components/design/inspector/ScrubInput.gesture.test.ts
@@ -28,7 +28,10 @@ import {
   updateScrubDrag,
   type ScrubDragState,
 } from "./scrub-input-utils";
-import type { ScrubInputChangeMeta } from "./ScrubInput";
+import {
+  resolvePendingScrubCommit,
+  type ScrubInputChangeMeta,
+} from "./ScrubInput";
 
 /**
  * Minimal re-implementation of ScrubInput's pointer handlers, built from the
@@ -315,6 +318,35 @@ describe("ScrubInput — pending-commit resolution predicate (B5-14 Enter reset)
   it("no pending commit means normal prop-driven resync", () => {
     expect(shouldResyncFromProp(null, 16)).toBe(true);
   });
+
+  it("keeps holding only while the incoming prop is the exact pre-commit baseline", () => {
+    expect(
+      resolvePendingScrubCommit({ value: 24, baseline: 16 }, 16, {
+        unit: "px",
+        precision: 1,
+      }),
+    ).toBe("hold");
+  });
+
+  it("accepts a different authoritative host value instead of staying stuck forever", () => {
+    // The host may clamp, normalize, reject, or replace a source write. The
+    // old equality-only guard kept showing 24 forever when 20 was the value
+    // that actually landed on canvas.
+    expect(
+      resolvePendingScrubCommit({ value: 24, baseline: 16 }, 20, {
+        unit: "px",
+        precision: 1,
+      }),
+    ).toBe("superseded");
+  });
+
+  it("recognizes a normalized echo as confirmation", () => {
+    expect(
+      resolvePendingScrubCommit({ value: 24, baseline: 16 }, 24.04, {
+        precision: 1,
+      }),
+    ).toBe("confirmed");
+  });
 });
 
 /**
diff --git a/templates/design/app/components/design/inspector/ScrubInput.tsx b/templates/design/app/components/design/inspector/ScrubInput.tsx
index 1d8a15c843..188e2d2e3d 100644
--- a/templates/design/app/components/design/inspector/ScrubInput.tsx
+++ b/templates/design/app/components/design/inspector/ScrubInput.tsx
@@ -78,6 +78,26 @@ export interface ScrubInputProps extends ScrubExpressionOptions {
   tooltipLabel?: string;
 }
 
+export interface PendingScrubCommit {
+  value: number;
+  /** Incoming prop value at commit time. While this exact value remains, the
+   * host has not acknowledged the write yet and the optimistic draft should
+   * stay visible. A different incoming value is authoritative host
+   * normalization/rejection and must supersede the optimistic draft. */
+  baseline: number;
+}
+
+export function resolvePendingScrubCommit(
+  pending: PendingScrubCommit | null,
+  incomingValue: number,
+  options: ScrubExpressionOptions,
+): "none" | "hold" | "confirmed" | "superseded" {
+  if (pending === null) return "none";
+  const incoming = normalizeScrubNumber(incomingValue, options);
+  if (incoming === pending.value) return "confirmed";
+  return incoming === pending.baseline ? "hold" : "superseded";
+}
+
 export function ScrubInput({
   label,
   value,
@@ -128,18 +148,27 @@ export function ScrubInput({
   // value back to the old one the instant focus leaves the input, which
   // reads as "Enter resets to the old value". Cleared as soon as a fresh
   // `value` prop confirms (or supersedes) the pending commit.
-  const pendingCommitRef = useRef<number | null>(null);
+  const pendingCommitRef = useRef<PendingScrubCommit | null>(null);
   const options = { unit, min, max, precision };
 
   useEffect(() => {
-    if (pendingCommitRef.current !== null) {
-      if (normalizeScrubNumber(value, options) === pendingCommitRef.current) {
-        // The host echoed back exactly what we committed — resolved, safe to
-        // resume syncing from the prop again.
+    if (mixed) pendingCommitRef.current = null;
+    const resolution = resolvePendingScrubCommit(
+      pendingCommitRef.current,
+      value,
+      options,
+    );
+    if (resolution !== "none") {
+      if (resolution === "confirmed" || resolution === "superseded") {
+        // The host either echoed exactly what we committed or returned a new,
+        // authoritative normalized/rejected value. In both cases resume prop
+        // synchronization. The old equality-only logic held forever on the
+        // second path, leaving the field permanently stuck on a value the
+        // canvas never accepted.
         pendingCommitRef.current = null;
       } else {
-        // Still waiting for the round-trip (or the host is reporting a
-        // different in-flight value) — don't stomp the optimistic draft.
+        // Still seeing the exact pre-commit prop — don't stomp the optimistic
+        // draft while the source-write round trip is pending.
         return;
       }
     }
@@ -151,7 +180,7 @@ export function ScrubInput({
       setDraft(formatted);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps -- `options` is a fresh object every render; the individual fields it's built from (unit/min/max/precision) are already listed below.
-  }, [focused, mixed, precision, unit, value]);
+  }, [focused, max, min, mixed, precision, unit, value]);
 
   const resolvedTooltipLabel = tooltipLabel ?? ariaLabel ?? label;
 
@@ -162,7 +191,12 @@ export function ScrubInput({
     // prop before the host's round-trip lands (see pendingCommitRef above).
     // Preview ticks don't need this: they're expected to be superseded by
     // the next tick or the gesture's own final commit almost immediately.
-    if (meta.phase === "commit") pendingCommitRef.current = normalized;
+    if (meta.phase === "commit") {
+      pendingCommitRef.current = {
+        value: normalized,
+        baseline: normalizeScrubNumber(value, options),
+      };
+    }
     onChange(normalized, meta);
     const formatted = formatScrubValue(normalized, options);
     draftRef.current = formatted;
@@ -192,7 +226,10 @@ export function ScrubInput({
     if (parsed.value !== value || mixed) {
       // See setNextValue's pendingCommitRef comment — this text-commit path
       // (Enter/blur) bypasses setNextValue, so mark it pending here too.
-      pendingCommitRef.current = parsed.value;
+      pendingCommitRef.current = {
+        value: parsed.value,
+        baseline: normalizeScrubNumber(value, options),
+      };
       onChange(parsed.value, {
         source: "commit",
         expression: currentDraft,
@@ -348,7 +385,10 @@ export function ScrubInput({
       // authoritative value as pending confirmation so releasing the drag
       // can't be clobbered back to the pre-drag value by a slow host
       // round-trip (same class of bug as the Enter/blur text-commit case).
-      pendingCommitRef.current = lastScrubValueRef.current;
+      pendingCommitRef.current = {
+        value: lastScrubValueRef.current,
+        baseline: normalizeScrubNumber(value, options),
+      };
       onChange(lastScrubValueRef.current, {
         source: "scrub",
         phase: "commit",
diff --git a/templates/design/app/components/design/inspector/ShaderFillsPanel.commit.test.tsx b/templates/design/app/components/design/inspector/ShaderFillsPanel.commit.test.tsx
new file mode 100644
index 0000000000..3b4002e3a0
--- /dev/null
+++ b/templates/design/app/components/design/inspector/ShaderFillsPanel.commit.test.tsx
@@ -0,0 +1,278 @@
+// @vitest-environment happy-dom
+
+/**
+ * Preview/commit gesture-lifecycle tests for ShaderFillsPanel (added
+ * alongside this fix): before this change, `ShaderControls`' `onChange`
+ * (fired on every continuous uniform-tuning tick — typing or dragging a
+ * slider) and a discrete preset/create-new pick both funneled through the
+ * same `commit()` path, which fired the expensive `apply-shader` codegen
+ * mutation on *every single tick* of a drag — a "commit storm" identical in
+ * spirit to the one GradientEditor's `onCommit` was added to fix (see
+ * GradientEditor.interaction.test.tsx).
+ *
+ * The fix splits `commit()` into `preview()` (cheap: local state + the
+ * caller's `onApply`, called on every tick) and `commitNow()` (expensive:
+ * the caller's `onCommit` + the `apply-shader` mutation, called exactly once
+ * per gesture/discrete pick). Gesture-end for a continuous ShaderControls
+ * drag is detected via pointerup/blur bubbling out of the tuning container,
+ * since ShaderControls doesn't surface its own ScrubInput gesture phase.
+ */
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mutateCalls: unknown[] = [];
+const mockUseActionMutation = vi.hoisted(() => vi.fn());
+
+vi.mock("@/components/ui/tooltip", () => ({
+  Tooltip: ({ children }: { children?: unknown }) => children as never,
+  TooltipTrigger: ({ children }: { children?: unknown }) => children as never,
+  TooltipContent: ({ children }: { children?: unknown }) => children as never,
+  TooltipProvider: ({ children }: { children?: unknown }) => children as never,
+}));
+
+vi.mock("@agent-native/core/client", () => ({
+  useActionMutation: (...args: unknown[]) => mockUseActionMutation(...args),
+  // `@/lib/utils`'s `cn` re-exports from this module — ShaderFillsPanel's
+  // browse view (rendered when no `descriptor` prop is passed) uses it for
+  // every button's className, so it must stay a real class-joining function
+  // rather than disappearing along with the rest of this mocked module.
+  cn: (...classes: unknown[]) => classes.filter(Boolean).join(" "),
+}));
+
+// Stub out ShaderControls entirely — it renders heavy shader canvases we
+// don't need for this gesture-lifecycle test. Expose a button that invokes
+// `onChange` with a tweaked descriptor, simulating one continuous-tuning
+// tick (e.g. one pointermove sample while dragging a uniform slider).
+vi.mock("./ShaderControls", () => ({
+  ShaderControls: ({
+    descriptor,
+    onChange,
+  }: {
+    descriptor: { preset: string; params: Record<string, number> };
+    onChange: (next: unknown) => void;
+  }) => (
+    <button
+      type="button"
+      data-testid="tick"
+      onClick={() =>
+        onChange({
+          ...descriptor,
+          params: { ...descriptor.params, intensity: 0.5 },
+        })
+      }
+    >
+      tick
+    </button>
+  ),
+}));
+
+import { ShaderFillsPanel } from "./ShaderFillsPanel";
+
+const baseDescriptor = {
+  preset: "MeshGradient" as const,
+  params: { intensity: 0.1 },
+  colors: ["#ff0000", "#0000ff"],
+  speed: 0,
+  frame: 0,
+};
+
+let container: HTMLDivElement;
+let root: ReturnType<typeof createRoot>;
+
+beforeEach(() => {
+  mutateCalls.length = 0;
+  mockUseActionMutation.mockReset();
+  mockUseActionMutation.mockImplementation(() => ({
+    mutate: (params: unknown) => {
+      mutateCalls.push(params);
+    },
+  }));
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+describe("ShaderFillsPanel preview/commit split", () => {
+  it("preview ticks call onApply but never onCommit or the apply-shader mutation", () => {
+    const onApply = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <ShaderFillsPanel
+          descriptor={baseDescriptor}
+          onApply={onApply}
+          onCommit={onCommit}
+          onBack={() => undefined}
+        />,
+      );
+    });
+
+    const tick = container.querySelector<HTMLButtonElement>(
+      '[data-testid="tick"]',
+    );
+    expect(tick).not.toBeNull();
+
+    act(() => {
+      tick?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    expect(onApply).toHaveBeenCalledTimes(1);
+    expect(onCommit).not.toHaveBeenCalled();
+    expect(mutateCalls).toHaveLength(0);
+  });
+
+  it("a pointerup bubbling out of the tuning area commits exactly once after several preview ticks", () => {
+    const onApply = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <ShaderFillsPanel
+          descriptor={baseDescriptor}
+          onApply={onApply}
+          onCommit={onCommit}
+          onBack={() => undefined}
+        />,
+      );
+    });
+
+    const tick = container.querySelector<HTMLButtonElement>(
+      '[data-testid="tick"]',
+    );
+
+    // Several drag ticks — each a cheap preview only.
+    act(() => {
+      tick?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      tick?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      tick?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    expect(onApply).toHaveBeenCalledTimes(3);
+    expect(onCommit).not.toHaveBeenCalled();
+    expect(mutateCalls).toHaveLength(0);
+
+    // Gesture ends: pointerup bubbles up from the (mocked) ShaderControls
+    // button through the wrapping div's onPointerUp handler.
+    act(() => {
+      tick?.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+    });
+
+    expect(onCommit).toHaveBeenCalledTimes(1);
+    expect(mutateCalls).toHaveLength(1);
+  });
+
+  it("a discrete preset pick commits immediately in the same tick", () => {
+    const onApply = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <ShaderFillsPanel
+          onApply={onApply}
+          onCommit={onCommit}
+          onBack={() => undefined}
+        />,
+      );
+    });
+
+    // Browse view — the "Create new" tile is a discrete, one-shot pick.
+    const createNew = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Create new shader"]',
+    );
+    expect(createNew).not.toBeNull();
+
+    act(() => {
+      createNew?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    expect(onApply).toHaveBeenCalledTimes(1);
+    expect(onCommit).toHaveBeenCalledTimes(1);
+    expect(mutateCalls).toHaveLength(1);
+  });
+
+  it("a bare pointerup with no preceding preview tick never commits (no-change click/blur regression)", () => {
+    // Simulates opening/closing a Select, clicking a checkbox, or tabbing
+    // between fields inside the tuning container: the pointerup/blur bubbles
+    // out to the wrapping div, but no descriptor actually changed. Before the
+    // dirty-flag fix, `lastAppliedRef` was seeded on mount and never cleared,
+    // so this alone re-fired the real apply-shader mutation on an unchanged
+    // descriptor.
+    const onApply = vi.fn();
+    const onCommit = vi.fn();
+
+    act(() => {
+      root.render(
+        <ShaderFillsPanel
+          descriptor={baseDescriptor}
+          onApply={onApply}
+          onCommit={onCommit}
+          onBack={() => undefined}
+        />,
+      );
+    });
+
+    const tuningContainer = container.querySelector(
+      '[data-testid="tick"]',
+    )?.parentElement;
+    expect(tuningContainer).not.toBeNull();
+
+    act(() => {
+      tuningContainer?.dispatchEvent(
+        new PointerEvent("pointerup", { bubbles: true }),
+      );
+    });
+    act(() => {
+      // React implements onBlur via the native (bubbling) "focusout" event
+      // rather than "blur" (which doesn't bubble) — see React's
+      // SimpleEventPlugin.
+      tuningContainer?.dispatchEvent(
+        new FocusEvent("focusout", { bubbles: true }),
+      );
+    });
+
+    expect(onApply).not.toHaveBeenCalled();
+    expect(onCommit).not.toHaveBeenCalled();
+    expect(mutateCalls).toHaveLength(0);
+  });
+
+  it("still commits via the apply-shader mutation when onCommit is omitted, but only after a preview tick", () => {
+    const onApply = vi.fn();
+
+    act(() => {
+      root.render(
+        <ShaderFillsPanel
+          descriptor={baseDescriptor}
+          onApply={onApply}
+          onBack={() => undefined}
+        />,
+      );
+    });
+
+    const tick = container.querySelector<HTMLButtonElement>(
+      '[data-testid="tick"]',
+    );
+
+    // Bare pointerup first, with no preview tick yet — must not commit.
+    act(() => {
+      tick?.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+    });
+    expect(mutateCalls).toHaveLength(0);
+
+    // A real tuning tick, then pointerup ends the gesture — commits once.
+    act(() => {
+      tick?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    act(() => {
+      tick?.dispatchEvent(new PointerEvent("pointerup", { bubbles: true }));
+    });
+
+    expect(mutateCalls).toHaveLength(1);
+  });
+});
diff --git a/templates/design/app/components/design/inspector/ShaderFillsPanel.tsx b/templates/design/app/components/design/inspector/ShaderFillsPanel.tsx
index 0022c468ae..dad92015dd 100644
--- a/templates/design/app/components/design/inspector/ShaderFillsPanel.tsx
+++ b/templates/design/app/components/design/inspector/ShaderFillsPanel.tsx
@@ -23,7 +23,7 @@ import {
   IconSearch,
   IconX,
 } from "@tabler/icons-react";
-import { Component, useMemo, useState, type ReactNode } from "react";
+import { Component, useMemo, useRef, useState, type ReactNode } from "react";
 
 import { Input } from "@/components/ui/input";
 import {
@@ -169,8 +169,27 @@ function ShaderThumbnail({
 export interface ShaderFillsPanelProps {
   /** Currently-applied shader descriptor, if the fill is already a shader. */
   descriptor?: ShaderDescriptor;
-  /** Emits when the user applies/tunes a shader. value = CSS fallback fill. */
+  /**
+   * Cheap live preview — fires on every ShaderControls tuning tick (typing
+   * or dragging a uniform) as well as once for a discrete preset/create-new
+   * pick. Should only update the visual CSS fallback fill; never trigger
+   * expensive persistence work.
+   */
   onApply: (descriptor: ShaderDescriptor, css: string) => void;
+  /**
+   * Fires once per gesture/discrete action with the same final
+   * descriptor+css already reported via `onApply` — mirrors GradientEditor's
+   * `onCommit` convention (see GradientEditor.tsx): `onApply` alone fires on
+   * every tuning tick for live preview, `onCommit` fires exactly once when a
+   * drag/type gesture ends (detected via pointerup/blur bubbling out of the
+   * tuning area below — `ShaderControls` doesn't surface its own ScrubInput
+   * gesture phase upward) or immediately for a discrete preset/create-new
+   * pick, so a caller that persists through undo history and the
+   * `apply-shader` codegen mutation only does so once per edit instead of
+   * once per tick. Optional so an existing caller that only wires `onApply`
+   * keeps that prop as the single source of truth.
+   */
+  onCommit?: (descriptor: ShaderDescriptor, css: string) => void;
   /** Close the shader panel and return to the color picker. */
   onBack: () => void;
   /** Optional design context forwarded to the apply-shader action. */
@@ -186,6 +205,7 @@ export interface ShaderFillsPanelProps {
 export function ShaderFillsPanel({
   descriptor,
   onApply,
+  onCommit,
   onBack,
   applyContext,
   disabled = false,
@@ -195,6 +215,18 @@ export function ShaderFillsPanel({
     descriptor ?? null,
   );
   const applyShader = useActionMutation("apply-shader");
+  // Last descriptor reported to `onApply`, so a bubbled pointerup/blur that
+  // ends a tuning gesture can re-commit that exact value once, without
+  // needing ShaderControls to surface its own gesture-end signal.
+  const lastAppliedRef = useRef<ShaderDescriptor | null>(descriptor ?? null);
+  // Whether `preview()` has applied a new descriptor since the last
+  // `commitNow()`. Any pointerup/blur that bubbles out of the tuning
+  // container — opening a Select, clicking a checkbox, tabbing between
+  // fields — would otherwise re-fire the real apply-shader mutation on an
+  // unchanged descriptor just because `lastAppliedRef` is seeded on mount.
+  // Gate `commitLastPreview` on this flag instead: only a real preview tick
+  // sets it, and every `commitNow` clears it.
+  const dirtyRef = useRef(false);
 
   const filtered = useMemo(() => {
     const query = search.trim().toLowerCase();
@@ -206,13 +238,26 @@ export function ShaderFillsPanel({
     );
   }, [search]);
 
-  /** Validate + surface the descriptor for the agent, then emit the CSS fill. */
-  const commit = (next: ShaderDescriptor) => {
+  /**
+   * Cheap live preview: updates the thumbnail/detail state and the caller's
+   * CSS fallback fill. Called on every ShaderControls tick — must never do
+   * the expensive apply-shader codegen mutation (see commitNow below).
+   */
+  const preview = (next: ShaderDescriptor) => {
     setActive(next);
+    lastAppliedRef.current = next;
+    dirtyRef.current = true;
+    onApply(next, shaderDescriptorToCss(next));
+  };
+
+  /** Validate + surface the descriptor for the agent exactly once. */
+  const commitNow = (next: ShaderDescriptor) => {
+    dirtyRef.current = false;
     const css = shaderDescriptorToCss(next);
-    onApply(next, css);
+    onCommit?.(next, css);
     // Fire-and-forget validation/codegen so the agent can write real shader
-    // code. The picker fill is applied immediately above regardless of result.
+    // code. The picker fill is already applied via `preview` above,
+    // regardless of this mutation's result.
     applyShader.mutate(
       {
         surface: SHADER_PRESET_MAP[next.preset]?.isEffect ? "effect" : "fill",
@@ -250,6 +295,25 @@ export function ShaderFillsPanel({
     );
   };
 
+  /** Discrete, one-shot pick (preset thumbnail / create-new tile): preview + commit in the same tick, same as before this change. */
+  const pick = (next: ShaderDescriptor) => {
+    preview(next);
+    commitNow(next);
+  };
+
+  /**
+   * Ends a ShaderControls tuning gesture: pointerup/blur bubbling out of the
+   * tuning area (see the wrapping div below). Gated on `dirtyRef` so any
+   * pointerup/blur that bubbles out without an intervening `preview()` tick —
+   * opening a Select, clicking a checkbox, tabbing between fields — is a
+   * no-op instead of re-committing the unchanged descriptor.
+   */
+  const commitLastPreview = () => {
+    if (dirtyRef.current && lastAppliedRef.current) {
+      commitNow(lastAppliedRef.current);
+    }
+  };
+
   // ── Detail view: a preset is selected → tune it with ShaderControls ───────
   if (active) {
     const preset = SHADER_PRESET_MAP[active.preset];
@@ -277,10 +341,19 @@ export function ShaderFillsPanel({
             <IconX className="size-3" />
           </button>
         </div>
-        <div className="border-t border-border/70 p-2">
+        {/* onPointerUp/onBlur here catch the bubbled event that ends a
+            ShaderControls drag/type gesture (pointer capture redirects the
+            event's target but it still bubbles through this ancestor), so
+            the expensive apply-shader mutation commits exactly once per
+            gesture instead of once per preview tick. */}
+        <div
+          className="border-t border-border/70 p-2"
+          onPointerUp={commitLastPreview}
+          onBlur={commitLastPreview}
+        >
           <ShaderControls
             descriptor={active}
-            onChange={(next) => commit(next)}
+            onChange={(next) => preview(next)}
           />
         </div>
       </div>
@@ -301,7 +374,7 @@ export function ShaderFillsPanel({
               type="button"
               aria-label={"Create new shader" /* i18n-ignore */}
               disabled={disabled}
-              onClick={() => commit(descriptorFromPreset(SHADER_PRESETS[0]))}
+              onClick={() => pick(descriptorFromPreset(SHADER_PRESETS[0]))}
               className="flex size-5 items-center justify-center rounded text-muted-foreground hover:bg-[var(--design-editor-control-bg)] hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40"
             >
               <IconPlus className="size-3.5" />
@@ -358,7 +431,7 @@ export function ShaderFillsPanel({
               <button
                 type="button"
                 disabled={disabled}
-                onClick={() => commit(descriptorFromPreset(SHADER_PRESETS[0]))}
+                onClick={() => pick(descriptorFromPreset(SHADER_PRESETS[0]))}
                 className={cn(
                   "group relative flex aspect-[4/3] w-full flex-col items-center justify-center gap-1 rounded-md border border-dashed border-[var(--design-editor-control-border)] text-muted-foreground transition-colors",
                   "hover:border-foreground/40 hover:text-foreground",
@@ -399,7 +472,7 @@ export function ShaderFillsPanel({
                       type="button"
                       disabled={disabled}
                       aria-label={preset.label}
-                      onClick={() => commit(descriptorFromPreset(preset))}
+                      onClick={() => pick(descriptorFromPreset(preset))}
                       className={cn(
                         "group flex flex-col gap-1 text-left focus-visible:outline-none",
                         disabled && "pointer-events-none opacity-40",
diff --git a/templates/design/app/components/design/inspector/index.ts b/templates/design/app/components/design/inspector/index.ts
index ba9bca8402..1847ea52b4 100644
--- a/templates/design/app/components/design/inspector/index.ts
+++ b/templates/design/app/components/design/inspector/index.ts
@@ -14,6 +14,9 @@ export {
 export {
   AutoLayoutMatrix,
   type AutoLayoutDirection,
+  type AutoLayoutFlow,
+  type AutoLayoutGridTrackSizing,
+  type AutoLayoutGridValue,
   type AutoLayoutMatrixLabels,
   type AutoLayoutMatrixProps,
   type AutoLayoutMatrixValue,
diff --git a/templates/design/app/components/design/keyboard-shortcuts.test.ts b/templates/design/app/components/design/keyboard-shortcuts.test.ts
new file mode 100644
index 0000000000..3303b6ad38
--- /dev/null
+++ b/templates/design/app/components/design/keyboard-shortcuts.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+
+import { createCoreCommands } from "./code-workbench/commands";
+import {
+  DESIGN_SHORTCUT_CATEGORIES,
+  DESIGN_SHORTCUTS,
+  formatShortcutKeycaps,
+} from "./keyboard-shortcuts";
+
+describe("keyboard shortcuts catalog", () => {
+  it("keeps the Figma category order and gives every category real commands", () => {
+    expect(DESIGN_SHORTCUT_CATEGORIES).toEqual([
+      "essential",
+      "tools",
+      "view",
+      "zoom",
+      "text",
+      "shape",
+      "selection",
+      "cursor",
+      "edit",
+      "transform",
+      "arrange",
+      "components",
+      "layout",
+    ]);
+    for (const category of DESIGN_SHORTCUT_CATEGORIES) {
+      expect(
+        DESIGN_SHORTCUTS.some((shortcut) => shortcut.category === category),
+      ).toBe(true);
+    }
+  });
+
+  it("has unique ids and only documents wired Design handler names", () => {
+    const ids = DESIGN_SHORTCUTS.map((shortcut) => shortcut.id);
+    expect(new Set(ids).size).toBe(ids.length);
+    for (const shortcut of DESIGN_SHORTCUTS) {
+      expect(shortcut.handler).toMatch(/^on[A-Z]/);
+      expect(shortcut.bindings.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("takes code-specific rows from the live workbench command registry", () => {
+    const commands = createCoreCommands().filter(
+      (command) => command.keybindings?.length,
+    );
+    expect(commands).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: "workbench.save",
+          keybindings: ["$mod+s"],
+        }),
+        expect.objectContaining({
+          id: "workbench.commandPalette",
+          keybindings: ["$mod+shift+p", "f1"],
+        }),
+      ]),
+    );
+  });
+
+  it("formats platform modifiers as individual keycaps", () => {
+    expect(formatShortcutKeycaps("$mod+shift+p", true)).toEqual([
+      "⇧",
+      "⌘",
+      "P",
+    ]);
+    expect(formatShortcutKeycaps("ctrl+shift+?", false)).toEqual([
+      "Ctrl",
+      "Shift",
+      "?",
+    ]);
+    expect(formatShortcutKeycaps("+", true)).toEqual(["+"]);
+  });
+});
diff --git a/templates/design/app/components/design/keyboard-shortcuts.ts b/templates/design/app/components/design/keyboard-shortcuts.ts
new file mode 100644
index 0000000000..dc4113a2b4
--- /dev/null
+++ b/templates/design/app/components/design/keyboard-shortcuts.ts
@@ -0,0 +1,552 @@
+import type { UseDesignHotkeysProps } from "@/hooks/useDesignHotkeys";
+
+export const DESIGN_SHORTCUT_CATEGORIES = [
+  "essential",
+  "tools",
+  "view",
+  "zoom",
+  "text",
+  "shape",
+  "selection",
+  "cursor",
+  "edit",
+  "transform",
+  "arrange",
+  "components",
+  "layout",
+] as const;
+
+export type DesignShortcutCategory =
+  (typeof DESIGN_SHORTCUT_CATEGORIES)[number];
+
+type DesignHotkeyHandlerKey = Exclude<
+  {
+    [K in keyof UseDesignHotkeysProps]: K extends `on${string}` ? K : never;
+  }[keyof UseDesignHotkeysProps],
+  undefined
+>;
+
+export interface DesignShortcutDefinition {
+  id: string;
+  category: DesignShortcutCategory;
+  bindings: readonly string[];
+  labelKey: `designEditor.keyboardShortcuts.commands.${string}`;
+  handler: DesignHotkeyHandlerKey;
+  context?: "screen";
+}
+
+const shortcut = (
+  definition: DesignShortcutDefinition,
+): DesignShortcutDefinition => definition;
+
+/**
+ * The user-facing Design shortcut catalog. Every row is tied to a real
+ * UseDesignHotkeys handler so the panel cannot quietly advertise a command the
+ * canvas does not dispatch. Code-workbench bindings are appended from its own
+ * command registry by KeyboardShortcutsPanel.
+ */
+export const DESIGN_SHORTCUTS: readonly DesignShortcutDefinition[] = [
+  shortcut({
+    id: "show-shortcuts",
+    category: "essential",
+    bindings: ["ctrl+shift+?"],
+    labelKey: "designEditor.keyboardShortcuts.commands.showShortcuts",
+    handler: "onShowKeyboardShortcuts",
+  }),
+  shortcut({
+    id: "undo",
+    category: "essential",
+    bindings: ["$mod+z"],
+    labelKey: "designEditor.keyboardShortcuts.commands.undo",
+    handler: "onUndo",
+  }),
+  shortcut({
+    id: "redo",
+    category: "essential",
+    bindings: ["$mod+shift+z", "$mod+y"],
+    labelKey: "designEditor.keyboardShortcuts.commands.redo",
+    handler: "onRedo",
+  }),
+
+  shortcut({
+    id: "move-tool",
+    category: "tools",
+    bindings: ["v"],
+    labelKey: "designEditor.keyboardShortcuts.commands.moveTool",
+    handler: "onMoveTool",
+  }),
+  shortcut({
+    id: "frame-tool",
+    category: "tools",
+    bindings: ["f"],
+    labelKey: "designEditor.keyboardShortcuts.commands.frameTool",
+    handler: "onFrameTool",
+  }),
+  shortcut({
+    id: "text-tool",
+    category: "tools",
+    bindings: ["t"],
+    labelKey: "designEditor.keyboardShortcuts.commands.textTool",
+    handler: "onTextTool",
+  }),
+  shortcut({
+    id: "pen-tool",
+    category: "tools",
+    bindings: ["p"],
+    labelKey: "designEditor.keyboardShortcuts.commands.penTool",
+    handler: "onPenTool",
+  }),
+  shortcut({
+    id: "hand-tool",
+    category: "tools",
+    bindings: ["h"],
+    labelKey: "designEditor.keyboardShortcuts.commands.handTool",
+    handler: "onHandTool",
+  }),
+  shortcut({
+    id: "scale-tool",
+    category: "tools",
+    bindings: ["k"],
+    labelKey: "designEditor.keyboardShortcuts.commands.scaleTool",
+    handler: "onScaleTool",
+  }),
+  shortcut({
+    id: "comment-tool",
+    category: "tools",
+    bindings: ["c"],
+    labelKey: "designEditor.keyboardShortcuts.commands.commentTool",
+    handler: "onCommentTool",
+  }),
+  shortcut({
+    id: "draw-tool",
+    category: "tools",
+    bindings: ["y"],
+    labelKey: "designEditor.keyboardShortcuts.commands.drawTool",
+    handler: "onDrawTool",
+  }),
+
+  shortcut({
+    id: "show-layers",
+    category: "view",
+    bindings: ["alt+1"],
+    labelKey: "designEditor.keyboardShortcuts.commands.showLayers",
+    handler: "onShowLayersPanel",
+  }),
+  shortcut({
+    id: "show-assets",
+    category: "view",
+    bindings: ["alt+2"],
+    labelKey: "designEditor.keyboardShortcuts.commands.showAssets",
+    handler: "onShowAssetsPanel",
+  }),
+  shortcut({
+    id: "toggle-ui",
+    category: "view",
+    bindings: ["$mod+\\"],
+    labelKey: "designEditor.keyboardShortcuts.commands.toggleUi",
+    handler: "onToggleUi",
+  }),
+  shortcut({
+    id: "toggle-comments",
+    category: "view",
+    bindings: ["shift+c"],
+    labelKey: "designEditor.keyboardShortcuts.commands.toggleComments",
+    handler: "onToggleComments",
+  }),
+
+  shortcut({
+    id: "zoom-in",
+    category: "zoom",
+    bindings: ["$mod+=", "+"],
+    labelKey: "designEditor.keyboardShortcuts.commands.zoomIn",
+    handler: "onZoomIn",
+  }),
+  shortcut({
+    id: "zoom-out",
+    category: "zoom",
+    bindings: ["$mod+-", "-"],
+    labelKey: "designEditor.keyboardShortcuts.commands.zoomOut",
+    handler: "onZoomOut",
+  }),
+  shortcut({
+    id: "zoom-reset",
+    category: "zoom",
+    bindings: ["$mod+0"],
+    labelKey: "designEditor.keyboardShortcuts.commands.zoomReset",
+    handler: "onZoomReset",
+  }),
+  shortcut({
+    id: "zoom-fit",
+    category: "zoom",
+    bindings: ["shift+1"],
+    labelKey: "designEditor.keyboardShortcuts.commands.zoomFit",
+    handler: "onZoomToFit",
+  }),
+  shortcut({
+    id: "zoom-selection",
+    category: "zoom",
+    bindings: ["shift+2"],
+    labelKey: "designEditor.keyboardShortcuts.commands.zoomSelection",
+    handler: "onZoomToSelection",
+  }),
+
+  shortcut({
+    id: "underline",
+    category: "text",
+    bindings: ["$mod+u"],
+    labelKey: "designEditor.keyboardShortcuts.commands.underline",
+    handler: "onToggleUnderline",
+  }),
+  shortcut({
+    id: "strikethrough",
+    category: "text",
+    bindings: ["$mod+shift+x"],
+    labelKey: "designEditor.keyboardShortcuts.commands.strikethrough",
+    handler: "onToggleStrikethrough",
+  }),
+
+  shortcut({
+    id: "rectangle",
+    category: "shape",
+    bindings: ["r"],
+    labelKey: "designEditor.keyboardShortcuts.commands.rectangle",
+    handler: "onRectangleTool",
+  }),
+  shortcut({
+    id: "ellipse",
+    category: "shape",
+    bindings: ["o"],
+    labelKey: "designEditor.keyboardShortcuts.commands.ellipse",
+    handler: "onEllipseTool",
+  }),
+  shortcut({
+    id: "line",
+    category: "shape",
+    bindings: ["l"],
+    labelKey: "designEditor.keyboardShortcuts.commands.line",
+    handler: "onLineTool",
+  }),
+  shortcut({
+    id: "arrow",
+    category: "shape",
+    bindings: ["shift+l"],
+    labelKey: "designEditor.keyboardShortcuts.commands.arrow",
+    handler: "onArrowTool",
+  }),
+
+  shortcut({
+    id: "select-all",
+    category: "selection",
+    bindings: ["$mod+a"],
+    labelKey: "designEditor.keyboardShortcuts.commands.selectAll",
+    handler: "onSelectAll",
+  }),
+  shortcut({
+    id: "select-parent",
+    category: "selection",
+    bindings: ["\\", "shift+enter"],
+    labelKey: "designEditor.keyboardShortcuts.commands.selectParent",
+    handler: "onSelectParent",
+  }),
+  shortcut({
+    id: "enter",
+    category: "selection",
+    bindings: ["enter"],
+    labelKey: "designEditor.keyboardShortcuts.commands.enterSelection",
+    handler: "onEnter",
+  }),
+  shortcut({
+    id: "next-sibling",
+    category: "selection",
+    bindings: ["tab"],
+    labelKey: "designEditor.keyboardShortcuts.commands.nextSibling",
+    handler: "onTab",
+  }),
+  shortcut({
+    id: "previous-sibling",
+    category: "selection",
+    bindings: ["shift+tab"],
+    labelKey: "designEditor.keyboardShortcuts.commands.previousSibling",
+    handler: "onTab",
+  }),
+  shortcut({
+    id: "next-screen",
+    category: "selection",
+    bindings: ["n"],
+    labelKey: "designEditor.keyboardShortcuts.commands.nextScreen",
+    handler: "onNextFrame",
+    context: "screen",
+  }),
+  shortcut({
+    id: "previous-screen",
+    category: "selection",
+    bindings: ["shift+n"],
+    labelKey: "designEditor.keyboardShortcuts.commands.previousScreen",
+    handler: "onPreviousFrame",
+    context: "screen",
+  }),
+
+  shortcut({
+    id: "nudge",
+    category: "cursor",
+    bindings: ["arrowup", "arrowright", "arrowdown", "arrowleft"],
+    labelKey: "designEditor.keyboardShortcuts.commands.nudge",
+    handler: "onNudge",
+  }),
+  shortcut({
+    id: "nudge-large",
+    category: "cursor",
+    bindings: [
+      "shift+arrowup",
+      "shift+arrowright",
+      "shift+arrowdown",
+      "shift+arrowleft",
+    ],
+    labelKey: "designEditor.keyboardShortcuts.commands.nudgeLarge",
+    handler: "onNudge",
+  }),
+
+  shortcut({
+    id: "copy",
+    category: "edit",
+    bindings: ["$mod+c"],
+    labelKey: "designEditor.keyboardShortcuts.commands.copy",
+    handler: "onCopy",
+  }),
+  shortcut({
+    id: "copy-png",
+    category: "edit",
+    bindings: ["$mod+shift+c"],
+    labelKey: "designEditor.keyboardShortcuts.commands.copyPng",
+    handler: "onCopyAsPng",
+  }),
+  shortcut({
+    id: "cut",
+    category: "edit",
+    bindings: ["$mod+x"],
+    labelKey: "designEditor.keyboardShortcuts.commands.cut",
+    handler: "onCut",
+  }),
+  shortcut({
+    id: "paste",
+    category: "edit",
+    bindings: ["$mod+v"],
+    labelKey: "designEditor.keyboardShortcuts.commands.paste",
+    handler: "onPaste",
+  }),
+  shortcut({
+    id: "paste-over",
+    category: "edit",
+    bindings: ["$mod+shift+v"],
+    labelKey: "designEditor.keyboardShortcuts.commands.pasteOver",
+    handler: "onPasteOver",
+  }),
+  shortcut({
+    id: "copy-properties",
+    category: "edit",
+    bindings: ["$mod+alt+c"],
+    labelKey: "designEditor.keyboardShortcuts.commands.copyProperties",
+    handler: "onCopyProps",
+  }),
+  shortcut({
+    id: "paste-properties",
+    category: "edit",
+    bindings: ["$mod+alt+v"],
+    labelKey: "designEditor.keyboardShortcuts.commands.pasteProperties",
+    handler: "onPasteProps",
+  }),
+  shortcut({
+    id: "paste-replace",
+    category: "edit",
+    bindings: ["$mod+shift+r"],
+    labelKey: "designEditor.keyboardShortcuts.commands.pasteReplace",
+    handler: "onPasteToReplace",
+  }),
+  shortcut({
+    id: "duplicate",
+    category: "edit",
+    bindings: ["$mod+d"],
+    labelKey: "designEditor.keyboardShortcuts.commands.duplicate",
+    handler: "onDuplicate",
+  }),
+  shortcut({
+    id: "delete",
+    category: "edit",
+    bindings: ["backspace", "delete"],
+    labelKey: "designEditor.keyboardShortcuts.commands.delete",
+    handler: "onDelete",
+  }),
+  shortcut({
+    id: "rename",
+    category: "edit",
+    bindings: ["$mod+r"],
+    labelKey: "designEditor.keyboardShortcuts.commands.rename",
+    handler: "onRename",
+  }),
+  shortcut({
+    id: "find",
+    category: "edit",
+    bindings: ["$mod+f"],
+    labelKey: "designEditor.keyboardShortcuts.commands.find",
+    handler: "onFind",
+  }),
+
+  shortcut({
+    id: "flip-horizontal",
+    category: "transform",
+    bindings: ["shift+h"],
+    labelKey: "designEditor.keyboardShortcuts.commands.flipHorizontal",
+    handler: "onFlipHorizontal",
+  }),
+  shortcut({
+    id: "flip-vertical",
+    category: "transform",
+    bindings: ["shift+v"],
+    labelKey: "designEditor.keyboardShortcuts.commands.flipVertical",
+    handler: "onFlipVertical",
+  }),
+  shortcut({
+    id: "swap-fill-stroke",
+    category: "transform",
+    bindings: ["shift+x"],
+    labelKey: "designEditor.keyboardShortcuts.commands.swapFillStroke",
+    handler: "onSwapFillStroke",
+  }),
+
+  shortcut({
+    id: "bring-forward",
+    category: "arrange",
+    bindings: ["$mod+]"],
+    labelKey: "designEditor.keyboardShortcuts.commands.bringForward",
+    handler: "onBringForward",
+  }),
+  shortcut({
+    id: "send-backward",
+    category: "arrange",
+    bindings: ["$mod+["],
+    labelKey: "designEditor.keyboardShortcuts.commands.sendBackward",
+    handler: "onSendBackward",
+  }),
+  shortcut({
+    id: "bring-front",
+    category: "arrange",
+    bindings: ["]"],
+    labelKey: "designEditor.keyboardShortcuts.commands.bringFront",
+    handler: "onBringToFront",
+  }),
+  shortcut({
+    id: "send-back",
+    category: "arrange",
+    bindings: ["["],
+    labelKey: "designEditor.keyboardShortcuts.commands.sendBack",
+    handler: "onSendToBack",
+  }),
+  shortcut({
+    id: "align-left",
+    category: "arrange",
+    bindings: ["alt+a"],
+    labelKey: "designEditor.keyboardShortcuts.commands.alignLeft",
+    handler: "onAlignSelection",
+  }),
+  shortcut({
+    id: "align-right",
+    category: "arrange",
+    bindings: ["alt+d"],
+    labelKey: "designEditor.keyboardShortcuts.commands.alignRight",
+    handler: "onAlignSelection",
+  }),
+  shortcut({
+    id: "align-top",
+    category: "arrange",
+    bindings: ["alt+w"],
+    labelKey: "designEditor.keyboardShortcuts.commands.alignTop",
+    handler: "onAlignSelection",
+  }),
+  shortcut({
+    id: "align-bottom",
+    category: "arrange",
+    bindings: ["alt+s"],
+    labelKey: "designEditor.keyboardShortcuts.commands.alignBottom",
+    handler: "onAlignSelection",
+  }),
+  shortcut({
+    id: "tidy",
+    category: "arrange",
+    bindings: ["ctrl+alt+t"],
+    labelKey: "designEditor.keyboardShortcuts.commands.tidy",
+    handler: "onTidyUp",
+  }),
+
+  shortcut({
+    id: "create-component",
+    category: "components",
+    bindings: ["$mod+alt+k"],
+    labelKey: "designEditor.keyboardShortcuts.commands.createComponent",
+    handler: "onCreateComponent",
+  }),
+  shortcut({
+    id: "detach-instance",
+    category: "components",
+    bindings: ["$mod+alt+b"],
+    labelKey: "designEditor.keyboardShortcuts.commands.detachInstance",
+    handler: "onDetachInstance",
+  }),
+
+  shortcut({
+    id: "group",
+    category: "layout",
+    bindings: ["$mod+g"],
+    labelKey: "designEditor.keyboardShortcuts.commands.group",
+    handler: "onGroup",
+  }),
+  shortcut({
+    id: "ungroup",
+    category: "layout",
+    bindings: ["$mod+backspace"],
+    labelKey: "designEditor.keyboardShortcuts.commands.ungroup",
+    handler: "onUngroup",
+  }),
+  shortcut({
+    id: "frame-selection",
+    category: "layout",
+    bindings: ["$mod+alt+g"],
+    labelKey: "designEditor.keyboardShortcuts.commands.frameSelection",
+    handler: "onFrameSelection",
+  }),
+  shortcut({
+    id: "auto-layout",
+    category: "layout",
+    bindings: ["shift+a"],
+    labelKey: "designEditor.keyboardShortcuts.commands.autoLayout",
+    handler: "onAddAutoLayout",
+  }),
+] as const;
+
+const KEY_LABELS: Record<string, string> = {
+  arrowleft: "←",
+  arrowright: "→",
+  arrowup: "↑",
+  arrowdown: "↓",
+  backspace: "⌫",
+  delete: "⌦",
+  enter: "↩",
+  escape: "Esc",
+  plus: "+",
+  tab: "Tab",
+};
+
+export function formatShortcutKeycaps(
+  binding: string,
+  applePlatform: boolean,
+): string[] {
+  if (binding === "+") return ["+"];
+  const tokens = binding.toLowerCase().split("+");
+  const key = tokens.pop() ?? "";
+  const keycaps: string[] = [];
+  if (tokens.includes("ctrl")) keycaps.push(applePlatform ? "⌃" : "Ctrl");
+  if (tokens.includes("alt")) keycaps.push(applePlatform ? "⌥" : "Alt");
+  if (tokens.includes("shift")) keycaps.push(applePlatform ? "⇧" : "Shift");
+  if (tokens.includes("$mod")) keycaps.push(applePlatform ? "⌘" : "Ctrl");
+  keycaps.push(KEY_LABELS[key] ?? (key.length === 1 ? key.toUpperCase() : key));
+  return keycaps;
+}
diff --git a/templates/design/app/components/design/motion-preview-bridge.test.ts b/templates/design/app/components/design/motion-preview-bridge.test.ts
index fa98880486..b51d492fec 100644
--- a/templates/design/app/components/design/motion-preview-bridge.test.ts
+++ b/templates/design/app/components/design/motion-preview-bridge.test.ts
@@ -35,6 +35,8 @@ function loadBridge(): {
   sendMessage: (data: unknown) => void;
   /** Register a fake element addressable by data-agent-native-node-id. */
   addElement: (nodeId: string) => FakeElement;
+  /** Simulate the node leaving the document (e.g. replaced by a host edit). */
+  removeElement: (nodeId: string) => void;
 } {
   // Import the compiled bridge string from the generated module. Using
   // require() so the import is synchronous and the function can be called
@@ -83,6 +85,15 @@ function loadBridge(): {
       const m = /\[data-agent-native-node-id="([^"]+)"\]/.exec(selector);
       return m ? (elements.get(m[1]) ?? null) : null;
     },
+    // The bridge's element cache (resolveTrackElement) checks
+    // `document.contains(cached)` before trusting a cached lookup, so the
+    // fake document needs to answer that too — "contained" here means
+    // still registered in this test's `elements` map (removeElement below
+    // simulates the node leaving the document, e.g. a host-applied edit
+    // replacing it).
+    contains(node: unknown): boolean {
+      return Array.from(elements.values()).includes(node as FakeElement);
+    },
   };
 
   // eslint-disable-next-line @typescript-eslint/no-implied-eval
@@ -103,6 +114,9 @@ function loadBridge(): {
       elements.set(nodeId, el);
       return el;
     },
+    removeElement: (nodeId: string) => {
+      elements.delete(nodeId);
+    },
   };
 }
 
@@ -372,6 +386,50 @@ describe("motion-preview bridge per-track offsets (span timing)", () => {
     expect(el.style.opacity).toBe("");
   });
 
+  it("caches the resolved element across preview ticks but re-resolves once it leaves the document", () => {
+    // Perf regression coverage: applyPreview used to call
+    // document.querySelector for every track on every single "motion-preview"
+    // tick (one per parent rAF frame), even though the target element almost
+    // never changes between ticks. Assert the cache (a) is actually used —
+    // repeated ticks with the node still present must keep hitting the SAME
+    // element instance — and (b) is safely invalidated when the node is no
+    // longer in the document (e.g. a host-applied edit replaced it), so a
+    // stale cached reference can never silently swallow further updates.
+    const fresh = loadBridge();
+    const originalEl = fresh.addElement("hero");
+    fresh.sendMessage({
+      type: "motion-load-tracks",
+      durationMs: 1000,
+      tracks: [
+        {
+          targetNodeId: "hero",
+          property: "opacity",
+          keyframes: [
+            { t: 0, value: "0", ease: "linear" },
+            { t: 1, value: "1", ease: "linear" },
+          ],
+        },
+      ],
+    });
+    fresh.sendMessage({ type: "motion-preview", t: 0.25, durationMs: 1000 });
+    expect(originalEl.style.opacity).toBe("0.25");
+    fresh.sendMessage({ type: "motion-preview", t: 0.5, durationMs: 1000 });
+    expect(originalEl.style.opacity).toBe("0.5");
+
+    // The node is replaced (removed, then a NEW element re-registered under
+    // the same nodeId) without any "motion-load-tracks" reload in between —
+    // exactly what a live DOM patch looks like from the bridge's perspective.
+    fresh.removeElement("hero");
+    const replacementEl = fresh.addElement("hero");
+    fresh.sendMessage({ type: "motion-preview", t: 0.75, durationMs: 1000 });
+
+    // The stale cached element must NOT keep receiving updates...
+    expect(originalEl.style.opacity).toBe("0.5");
+    // ...the NEW element must, proving the cache re-resolved instead of
+    // silently no-oping against a detached reference.
+    expect(replacementEl.style.opacity).toBe("0.75");
+  });
+
   it("previews modern individual transform properties (translate/scale/rotate)", () => {
     const fresh = loadBridge();
     const el = fresh.addElement("card");
diff --git a/templates/design/app/components/design/multi-screen/board-surface-html.ts b/templates/design/app/components/design/multi-screen/board-surface-html.ts
index dffdf41671..a42abb04ba 100644
--- a/templates/design/app/components/design/multi-screen/board-surface-html.ts
+++ b/templates/design/app/components/design/multi-screen/board-surface-html.ts
@@ -1,3 +1,5 @@
+import type { FrameGeometry } from "./types";
+
 export function hasBoardSurfaceContent(html: string | undefined) {
   if (!html) return false;
   const bodyMatch = html.match(/<body\b[^>]*>([\s\S]*?)<\/body>/i);
@@ -53,6 +55,108 @@ function getCssPixelValue(style: string, name: string) {
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+/**
+ * Returns the canvas-space bounds occupied by top-level board nodes.
+ *
+ * Board coordinates are persisted directly in each root node's absolute
+ * `left`/`top`. Keeping this parser string-only makes it usable during SSR and
+ * in the jsdom-less unit suite, while restricting the scan to root nodes keeps
+ * nested children from being counted twice with parent-relative coordinates.
+ */
+export function getBoardSurfaceContentBounds(
+  html: string | undefined,
+): FrameGeometry | null {
+  if (!html) return null;
+
+  const stack: Array<{
+    tagName: string;
+    nodeId: string;
+    offsetX: number;
+    offsetY: number;
+  }> = [];
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+
+  for (const match of html.matchAll(HTML_TAG_RE)) {
+    const token = match[0];
+    const tagName = match[1]?.toLowerCase();
+    if (!tagName) continue;
+
+    if (token.startsWith("</")) {
+      const index = findLastHtmlStackTagIndex(stack, tagName);
+      if (index >= 0) stack.splice(index);
+      continue;
+    }
+
+    const nodeId = getHtmlAttributeValue(token, "data-agent-native-node-id");
+    const style = getHtmlAttributeValue(token, "style");
+    const left = getCssPixelValue(style, "left") ?? 0;
+    const top = getCssPixelValue(style, "top") ?? 0;
+    const parentOffsetX = stack.reduce(
+      (total, entry) => total + entry.offsetX,
+      0,
+    );
+    const parentOffsetY = stack.reduce(
+      (total, entry) => total + entry.offsetY,
+      0,
+    );
+    const isDocumentRootTag =
+      tagName === "html" ||
+      tagName === "body" ||
+      tagName === "style" ||
+      tagName === "script";
+    if (nodeId && !isDocumentRootTag && !isAccidentalBoardBackdropTag(token)) {
+      const primitiveKind = getHtmlAttributeValue(
+        token,
+        "data-an-primitive",
+      ).toLowerCase();
+      // Auto-sized text has no persisted width/height. A one-pixel extent is
+      // not enough when it sits near a render-window edge. Reserve a modest
+      // intrinsic text box; the camera viewport remains the final authority
+      // for unusually long content.
+      const fallbackWidth = primitiveKind === "text" ? 256 : 1;
+      const fallbackHeight = primitiveKind === "text" ? 64 : 1;
+      const width = Math.max(
+        1,
+        getCssPixelValue(style, "width") ?? fallbackWidth,
+      );
+      const height = Math.max(
+        1,
+        getCssPixelValue(style, "height") ?? fallbackHeight,
+      );
+      const absoluteLeft = parentOffsetX + left;
+      const absoluteTop = parentOffsetY + top;
+      minX = Math.min(minX, absoluteLeft);
+      minY = Math.min(minY, absoluteTop);
+      maxX = Math.max(maxX, absoluteLeft + width);
+      maxY = Math.max(maxY, absoluteTop + height);
+    }
+
+    const selfClosing = token.endsWith("/>") || HTML_VOID_TAGS.has(tagName);
+    if (!selfClosing) {
+      stack.push({ tagName, nodeId, offsetX: left, offsetY: top });
+    }
+  }
+
+  if (
+    !Number.isFinite(minX) ||
+    !Number.isFinite(minY) ||
+    !Number.isFinite(maxX) ||
+    !Number.isFinite(maxY)
+  ) {
+    return null;
+  }
+
+  return {
+    x: minX,
+    y: minY,
+    width: Math.max(1, maxX - minX),
+    height: Math.max(1, maxY - minY),
+  };
+}
+
 function parseCssColor(value: string) {
   const trimmed = value.trim().toLowerCase();
   if (!trimmed || trimmed === "transparent") return null;
@@ -167,6 +271,59 @@ export function getBoardSurfaceRenderContent(html: string) {
   return `${BOARD_SURFACE_RENDER_STYLE}${renderHtml}`;
 }
 
+function stripExecutableStaticPreviewContent(html: string) {
+  return html
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, "") // i18n-ignore static-preview sanitizer regex, not visible UI copy
+    .replace(/<script\b[^>]*\/?\s*>/gi, "")
+    .replace(/<(iframe|object|audio|video)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, "") // i18n-ignore static-preview sanitizer regex, not visible UI copy
+    .replace(/<(?:iframe|object|embed|audio|video|source)\b[^>]*\/?\s*>/gi, "")
+    .replace(/<(?:link|meta|base)\b[^>]*>/gi, "")
+    .replace(/@import\s+(?:url\([^)]*\)|["'][^"']*["'])\s*[^;]*;/gi, "")
+    .replace(/url\(\s*(?:"[^"]*"|'[^']*'|[^)]*)\s*\)/gi, "none")
+    .replace(/<(?:img|image|use)\b[^>]*>/gi, (tag) =>
+      tag.replace(
+        /\s+(?:src|srcset|href|xlink:href)\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi,
+        "",
+      ),
+    )
+    .replace(/\s+on[a-z][\w:-]*\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "");
+}
+
+/**
+ * Produces the inert, compressed document painted behind the live board
+ * window at very low zoom. The document is also rendered in an iframe with an
+ * empty sandbox, but removing executable markup here is defense in depth and
+ * guarantees Alpine/React never starts a duplicate runtime.
+ *
+ * Root offsets use the same `translate` seam as the interactive finite board
+ * iframe. Scaling the body into a small browser-safe viewport makes the whole
+ * logical board paintable without allocating or scrolling a 131k iframe.
+ */
+export function getBoardSurfaceStaticPreviewContent(args: {
+  html: string;
+  logicalGeometry: FrameGeometry;
+  viewport: { width: number; height: number };
+}) {
+  const renderHtml = stripExecutableStaticPreviewContent(
+    getBoardSurfaceRenderContent(args.html),
+  );
+  const width = Math.max(1, args.logicalGeometry.width);
+  const height = Math.max(1, args.logicalGeometry.height);
+  const viewportWidth = Math.max(1, args.viewport.width);
+  const viewportHeight = Math.max(1, args.viewport.height);
+  const scale = Math.min(viewportWidth / width, viewportHeight / height);
+  const offsetX = -args.logicalGeometry.x;
+  const offsetY = -args.logicalGeometry.y;
+  const style = `<style data-agent-native-board-static-preview>*,*::before,*::after{animation:none!important;animation-delay:0s!important;transition:none!important;caret-color:transparent!important;}html{width:${viewportWidth}px!important;height:${viewportHeight}px!important;overflow:hidden!important;}body{margin:0!important;width:${width}px!important;height:${height}px!important;overflow:visible!important;transform:scale(${scale})!important;transform-origin:0 0!important;}body>[data-agent-native-node-id]{translate:${offsetX}px ${offsetY}px!important;}</style>`;
+  if (/<\/head>/i.test(renderHtml)) {
+    return renderHtml.replace(/<\/head>/i, `${style}</head>`);
+  }
+  if (/<body\b/i.test(renderHtml)) {
+    return renderHtml.replace(/<body\b/i, `${style}<body`);
+  }
+  return `${style}${renderHtml}`;
+}
+
 /** Simple djb2-xor string hash, used to build cheap cache keys elsewhere in
  *  the multi-screen canvas (board content signatures, primitive-parse cache
  *  keys, etc). */
diff --git a/templates/design/app/components/design/multi-screen/frame-geometry.test.ts b/templates/design/app/components/design/multi-screen/frame-geometry.test.ts
new file mode 100644
index 0000000000..5c8b430fd5
--- /dev/null
+++ b/templates/design/app/components/design/multi-screen/frame-geometry.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getCanonicalScreenStack,
+  reorderCanonicalScreenStack,
+} from "./frame-geometry";
+
+describe("canonical overview screen stack", () => {
+  const screens = [{ id: "a" }, { id: "b" }, { id: "c" }, { id: "d" }];
+
+  it("uses persisted z and source order as the stable tie-break", () => {
+    expect(
+      getCanonicalScreenStack(screens, {
+        a: { z: 20 },
+        b: { z: -5 },
+        c: { z: 20 },
+      }),
+    ).toEqual(["b", "d", "a", "c"]);
+  });
+
+  it("moves one or many screens below or above the target deterministically", () => {
+    expect(
+      reorderCanonicalScreenStack({
+        orderedIds: ["a", "b", "c", "d"],
+        draggedIds: ["b"],
+        targetId: "d",
+        placement: "after",
+      }),
+    ).toEqual(["a", "c", "d", "b"]);
+    expect(
+      reorderCanonicalScreenStack({
+        orderedIds: ["a", "b", "c", "d"],
+        draggedIds: ["c", "a"],
+        targetId: "b",
+        placement: "after",
+      }),
+    ).toEqual(["b", "a", "c", "d"]);
+  });
+
+  it("rejects inside, self-only, missing-target, and no-op moves", () => {
+    expect(
+      reorderCanonicalScreenStack({
+        orderedIds: ["a", "b"],
+        draggedIds: ["a"],
+        targetId: "b",
+        placement: "inside",
+      }),
+    ).toBeNull();
+    expect(
+      reorderCanonicalScreenStack({
+        orderedIds: ["a", "b"],
+        draggedIds: ["a"],
+        targetId: "a",
+        placement: "before",
+      }),
+    ).toBeNull();
+    expect(
+      reorderCanonicalScreenStack({
+        orderedIds: ["a", "b"],
+        draggedIds: ["a"],
+        targetId: "missing",
+        placement: "after",
+      }),
+    ).toBeNull();
+    expect(
+      reorderCanonicalScreenStack({
+        orderedIds: ["a", "b"],
+        draggedIds: ["a"],
+        targetId: "b",
+        placement: "before",
+      }),
+    ).toBeNull();
+  });
+});
diff --git a/templates/design/app/components/design/multi-screen/frame-geometry.ts b/templates/design/app/components/design/multi-screen/frame-geometry.ts
index ba2d587201..03b1a7b758 100644
--- a/templates/design/app/components/design/multi-screen/frame-geometry.ts
+++ b/templates/design/app/components/design/multi-screen/frame-geometry.ts
@@ -18,6 +18,59 @@ export interface ScreenViewportSize {
   height: number;
 }
 
+/** Canonical bottom-to-top screen stack. Persisted frame `z` wins; screens
+ * without one retain their source order, which is also the canvas DOM paint
+ * order. This is shared by the overview canvas and Layers projection so the
+ * two surfaces can never disagree about which screen is above another. */
+export function getCanonicalScreenStack(
+  screens: ReadonlyArray<{ id: string }>,
+  geometryById: Record<string, Partial<FrameGeometry> | undefined>,
+): string[] {
+  return screens
+    .map((screen, index) => ({
+      id: screen.id,
+      index,
+      z: Number.isFinite(geometryById[screen.id]?.z)
+        ? geometryById[screen.id]!.z!
+        : index,
+    }))
+    .sort((a, b) => a.z - b.z || a.index - b.index)
+    .map(({ id }) => id);
+}
+
+/** Reorders a canonical bottom-to-top stack using DOM placement semantics:
+ * `before` paints below the target and `after` paints above it. `inside` is
+ * not a screen-stack operation (it remains the layer-into-screen drop path). */
+export function reorderCanonicalScreenStack(args: {
+  orderedIds: readonly string[];
+  draggedIds: readonly string[];
+  targetId: string;
+  placement: "before" | "after" | "inside";
+}): string[] | null {
+  if (args.placement === "inside") return null;
+  const orderedIds = Array.from(new Set(args.orderedIds));
+  const orderedIdSet = new Set(orderedIds);
+  if (!orderedIdSet.has(args.targetId)) return null;
+  const draggedIdSet = new Set(
+    args.draggedIds.filter(
+      (id) => orderedIdSet.has(id) && id !== args.targetId,
+    ),
+  );
+  if (draggedIdSet.size === 0) return null;
+  const moving = orderedIds.filter((id) => draggedIdSet.has(id));
+  const remaining = orderedIds.filter((id) => !draggedIdSet.has(id));
+  const targetIndex = remaining.indexOf(args.targetId);
+  if (targetIndex < 0) return null;
+  const insertionIndex =
+    args.placement === "before" ? targetIndex : targetIndex + 1;
+  const next = [
+    ...remaining.slice(0, insertionIndex),
+    ...moving,
+    ...remaining.slice(insertionIndex),
+  ];
+  return next.every((id, index) => id === orderedIds[index]) ? null : next;
+}
+
 export function getBreakpointFrameGeometry(args: {
   widthPx: number;
   naturalAspect: number;
diff --git a/templates/design/app/components/design/multi-screen/overview-layout.ts b/templates/design/app/components/design/multi-screen/overview-layout.ts
index 622a748ec1..e38b3dc198 100644
--- a/templates/design/app/components/design/multi-screen/overview-layout.ts
+++ b/templates/design/app/components/design/multi-screen/overview-layout.ts
@@ -1,10 +1,23 @@
 import type { CSSProperties } from "react";
 
 import type { FrameGeometry } from "./types";
+import type { Point } from "./types";
 
 export const OVERVIEW_FRAME_WIDTH = 320;
 export const SURFACE_PADDING = 240;
 
+// Chromium does not reliably paint the far interior of the old
+// 131,072×131,072 board iframe. Keep the logical board that large for
+// persistence and hit testing, but render only a stable, chunk-snapped window
+// around the current design. Four-kilopixel chunks plus two chunks of minimum
+// extent leave ample room for nearby drawing/movement without re-keying the
+// iframe on every small edit.
+export const BOARD_SURFACE_RENDER_CHUNK = 4096;
+export const BOARD_SURFACE_RENDER_PADDING = 2048;
+export const BOARD_SURFACE_RENDER_MIN_SIZE = 8192;
+export const BOARD_SURFACE_RENDER_MAX_SIZE = 24_576;
+export const BOARD_SURFACE_STATIC_PREVIEW_SIZE = 4096;
+
 export const LINEUP_RECENTER_SUPPRESS_MAX_AGE_MS = 10_000;
 
 export interface LineupRecenterDuplicateArm {
@@ -60,3 +73,174 @@ export function getBoardSurfaceLayerStyle(args: {
     zIndex: 0,
   };
 }
+
+/**
+ * The interactive board iframe intentionally stays below Chromium's reliable
+ * paint limit. At very low zoom the visible world can be wider than that
+ * window, so a script-disabled static replica supplies visual coverage behind
+ * it. Keep the fallback off at ordinary zoom where the live window already
+ * covers the viewport.
+ */
+export function shouldRenderBoardSurfaceStaticPreview(args: {
+  zoom: number;
+  viewportGeometry?: FrameGeometry | null;
+  renderGeometry: FrameGeometry;
+}) {
+  if (args.viewportGeometry) {
+    return (
+      args.viewportGeometry.width > args.renderGeometry.width ||
+      args.viewportGeometry.height > args.renderGeometry.height
+    );
+  }
+  // ResizeObserver has not reported yet. The 5% fallback matches a 1229px
+  // viewport against the 24,576-world-pixel live cap and avoids one blank
+  // first paint at the minimum 2% zoom.
+  return args.zoom <= 5;
+}
+
+export function getBoardSurfaceStaticPreviewViewport(
+  logicalGeometry: FrameGeometry,
+) {
+  const longestAxis = Math.max(
+    1,
+    logicalGeometry.width,
+    logicalGeometry.height,
+  );
+  const scale = Math.min(1, BOARD_SURFACE_STATIC_PREVIEW_SIZE / longestAxis);
+  return {
+    width: Math.max(1, logicalGeometry.width * scale),
+    height: Math.max(1, logicalGeometry.height * scale),
+  };
+}
+
+function geometryExtent(geometry: FrameGeometry) {
+  return {
+    minX: geometry.x,
+    minY: geometry.y,
+    maxX: geometry.x + Math.max(1, geometry.width),
+    maxY: geometry.y + Math.max(1, geometry.height),
+  };
+}
+
+function fitRenderAxis(args: {
+  desiredMin: number;
+  desiredMax: number;
+  logicalMin: number;
+  logicalMax: number;
+  focus: number;
+}) {
+  const chunk = BOARD_SURFACE_RENDER_CHUNK;
+  const logicalSize = Math.max(1, args.logicalMax - args.logicalMin);
+  const maxSize = Math.min(BOARD_SURFACE_RENDER_MAX_SIZE, logicalSize);
+  const minSize = Math.min(BOARD_SURFACE_RENDER_MIN_SIZE, maxSize);
+  let min =
+    Math.floor((args.desiredMin - BOARD_SURFACE_RENDER_PADDING) / chunk) *
+    chunk;
+  let max =
+    Math.ceil((args.desiredMax + BOARD_SURFACE_RENDER_PADDING) / chunk) * chunk;
+
+  if (max - min < minSize) {
+    const center = (min + max) / 2;
+    min = Math.floor((center - minSize / 2) / chunk) * chunk;
+    max = min + minSize;
+  }
+
+  if (max - min > maxSize) {
+    // A single browser iframe cannot safely cover arbitrarily distant board
+    // islands. Prefer the active design focus while keeping the render window
+    // chunk-aligned; persistence and geometry hit testing still use the full
+    // logical board and remain lossless.
+    min = Math.floor((args.focus - maxSize / 2) / chunk) * chunk;
+    max = min + maxSize;
+  }
+
+  if (min < args.logicalMin) {
+    max += args.logicalMin - min;
+    min = args.logicalMin;
+  }
+  if (max > args.logicalMax) {
+    min -= max - args.logicalMax;
+    max = args.logicalMax;
+  }
+  min = Math.max(args.logicalMin, min);
+  max = Math.min(args.logicalMax, Math.max(min + 1, max));
+  return { origin: min, size: max - min };
+}
+
+/**
+ * Builds the finite iframe window used to paint the otherwise-infinite board.
+ * The returned geometry is deliberately separate from the logical board
+ * geometry so persisted coordinates and broad hit-testing retain their full
+ * range while Chromium only has to paint a browser-safe surface.
+ */
+export function getBoardSurfaceRenderGeometry(args: {
+  logicalGeometry: FrameGeometry;
+  contentBounds?: FrameGeometry | null;
+  screenGeometries?: readonly FrameGeometry[];
+  focus?: { x: number; y: number };
+}): FrameGeometry {
+  const candidates = [
+    ...(args.contentBounds ? [args.contentBounds] : []),
+    ...(args.screenGeometries ?? []),
+  ];
+  const logical = geometryExtent(args.logicalGeometry);
+  const extents = candidates.map(geometryExtent);
+  const desired =
+    extents.length > 0
+      ? {
+          minX: Math.min(...extents.map((extent) => extent.minX)),
+          minY: Math.min(...extents.map((extent) => extent.minY)),
+          maxX: Math.max(...extents.map((extent) => extent.maxX)),
+          maxY: Math.max(...extents.map((extent) => extent.maxY)),
+        }
+      : {
+          minX: 0,
+          minY: 0,
+          maxX: 1,
+          maxY: 1,
+        };
+  const focus = args.focus ?? {
+    x: (desired.minX + desired.maxX) / 2,
+    y: (desired.minY + desired.maxY) / 2,
+  };
+  const xAxis = fitRenderAxis({
+    desiredMin: desired.minX,
+    desiredMax: desired.maxX,
+    logicalMin: logical.minX,
+    logicalMax: logical.maxX,
+    focus: focus.x,
+  });
+  const yAxis = fitRenderAxis({
+    desiredMin: desired.minY,
+    desiredMax: desired.maxY,
+    logicalMin: logical.minY,
+    logicalMax: logical.maxY,
+    focus: focus.y,
+  });
+  return {
+    x: xAxis.origin,
+    y: yAxis.origin,
+    width: xAxis.size,
+    height: yAxis.size,
+  };
+}
+
+export function boardPointToBoardSurfaceLocalPoint(
+  point: Point,
+  renderGeometry: FrameGeometry,
+): Point {
+  return {
+    x: point.x - renderGeometry.x,
+    y: point.y - renderGeometry.y,
+  };
+}
+
+export function boardSurfaceLocalPointToBoardPoint(
+  point: Point,
+  renderGeometry: FrameGeometry,
+): Point {
+  return {
+    x: renderGeometry.x + point.x,
+    y: renderGeometry.y + point.y,
+  };
+}
diff --git a/templates/design/app/components/design/multi-screen/primitive-drop-target.test.ts b/templates/design/app/components/design/multi-screen/primitive-drop-target.test.ts
new file mode 100644
index 0000000000..08ca2c9757
--- /dev/null
+++ b/templates/design/app/components/design/multi-screen/primitive-drop-target.test.ts
@@ -0,0 +1,277 @@
+// @vitest-environment happy-dom
+
+import { rotatePoint } from "@shared/canvas-math";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import {
+  __clearPrimitiveParseCachesForTests,
+  findAutoLayoutInsertionAnchor,
+  getPrimitiveLowZoomHitRect,
+  getPrimitiveDropTargetForPoint,
+  parsePrimitivesFromScreen,
+} from "./primitive-drop-target";
+
+beforeEach(() => __clearPrimitiveParseCachesForTests());
+
+describe("primitive drop target authored layout fallback", () => {
+  it("accumulates nested absolute coordinates for frame targets", () => {
+    const screen = {
+      id: "screen",
+      filename: "screen.html",
+      content: `<!doctype html><html><body>
+        <div data-agent-native-node-id="parent" style="position:absolute;left:300px;top:100px;width:400px;height:300px">
+          <div data-agent-native-node-id="frame" data-an-primitive="frame" style="position:absolute;left:20px;top:30px;width:120px;height:90px"></div>
+        </div>
+      </body></html>`,
+    };
+
+    const frame = parsePrimitivesFromScreen(screen).find(
+      (primitive) => primitive.nodeId === "frame",
+    );
+    expect(frame).toMatchObject({
+      localLeft: 320,
+      localTop: 130,
+      localWidth: 120,
+      localHeight: 90,
+      isContainer: true,
+    });
+
+    expect(
+      getPrimitiveDropTargetForPoint(
+        { x: 350, y: 160 },
+        null,
+        [screen],
+        { screen: { x: 0, y: 0, width: 800, height: 600 } },
+        () => ({ width: 800, height: 600 }),
+      )?.nodeId,
+    ).toBe("frame");
+  });
+
+  it("accounts for padding, gap, and preceding siblings in a flex frame", () => {
+    const screen = {
+      id: "screen",
+      filename: "screen.html",
+      content: `<!doctype html><html><body>
+        <div data-agent-native-node-id="parent" style="position:absolute;left:300px;top:100px;width:500px;height:300px;display:flex;flex-direction:row;padding-left:20px;padding-top:15px;gap:10px">
+          <div data-agent-native-node-id="first" data-an-primitive="rectangle" style="width:50px;height:40px"></div>
+          <div data-agent-native-node-id="frame" data-an-primitive="frame" style="width:100px;height:80px"></div>
+        </div>
+      </body></html>`,
+    };
+
+    const frame = parsePrimitivesFromScreen(screen).find(
+      (primitive) => primitive.nodeId === "frame",
+    );
+    expect(frame).toMatchObject({
+      localLeft: 380,
+      localTop: 115,
+      localWidth: 100,
+      localHeight: 80,
+      isContainer: true,
+    });
+  });
+
+  it("derives intrinsic low-zoom hit bounds from drawn text typography and wrapping only", () => {
+    const screen = {
+      id: "board",
+      filename: "__board__.html",
+      content: `<!doctype html><html><body>
+        <div data-agent-native-node-id="label" data-an-primitive="text" style="position:absolute;left:35000px;top:100px">Edge label</div>
+        <div data-agent-native-node-id="large" data-an-primitive="text" style="position:absolute;left:35000px;top:300px;font-size:40px;letter-spacing:2px">MMMM</div>
+        <div data-agent-native-node-id="wrapped" data-an-primitive="text" style="position:absolute;left:35000px;top:500px;width:100px;font-size:20px;line-height:30px;white-space:normal">WWWWWWWWWWWWWWWWWWWW</div>
+        <div data-agent-native-node-id="sizeless-rect" data-an-primitive="rectangle" style="position:absolute;left:36000px;top:100px"></div>
+      </body></html>`,
+    };
+
+    const primitives = parsePrimitivesFromScreen(screen);
+    expect(primitives.map((primitive) => primitive.nodeId)).toEqual([
+      "label",
+      "large",
+      "wrapped",
+    ]);
+    expect(primitives[0]).toEqual(
+      expect.objectContaining({
+        nodeId: "label",
+        localLeft: 35000,
+        localTop: 100,
+        localWidth: expect.closeTo(77.6, 3),
+        localHeight: expect.closeTo(19.2, 3),
+      }),
+    );
+    expect(primitives[1]).toEqual(
+      expect.objectContaining({
+        nodeId: "large",
+        localWidth: expect.closeTo(137.2, 3),
+        localHeight: 48,
+      }),
+    );
+    expect(primitives[2]).toEqual(
+      expect.objectContaining({
+        nodeId: "wrapped",
+        localWidth: 100,
+        localHeight: 120,
+      }),
+    );
+    const lowZoomHitRect = getPrimitiveLowZoomHitRect(primitives[0]!, 2);
+    expect(lowZoomHitRect.x).toBeCloseTo(34888.8, 3);
+    expect(lowZoomHitRect.y).toBeCloseTo(-40.4, 3);
+    expect(lowZoomHitRect.width).toBe(300);
+    expect(lowZoomHitRect.height).toBe(300);
+  });
+});
+
+describe("auto-layout drop insertion anchor (WORK ITEM 1)", () => {
+  // A flex row with two children: "first" spans local x:[320,370], "second"
+  // spans local x:[380,440] (20px left padding + 10px gap, matching the
+  // "accounts for padding, gap, and preceding siblings" fixture above).
+  const flexScreen = {
+    id: "screen",
+    filename: "screen.html",
+    content: `<!doctype html><html><body>
+      <div data-agent-native-node-id="parent" data-an-primitive="frame" style="position:absolute;left:300px;top:100px;width:500px;height:300px;display:flex;flex-direction:row;padding-left:20px;padding-top:15px;gap:10px">
+        <div data-agent-native-node-id="first" data-an-primitive="rectangle" style="width:50px;height:40px"></div>
+        <div data-agent-native-node-id="second" data-an-primitive="rectangle" style="width:60px;height:40px"></div>
+      </div>
+    </body></html>`,
+  };
+  // 1:1 scale (frame geometry matches the metadata's own 800x600 content
+  // size), so board coords equal the authored local absolute-pixel coords
+  // directly — same convention the "accounts for padding" fixture above uses.
+  const identityFrameGeometry = {
+    screen: { x: 0, y: 0, width: 800, height: 600 },
+  };
+  const identityMetadata = () => ({ width: 800, height: 600 });
+
+  it("parses the flex container's own auto-layout axis and each child's parent link", () => {
+    const primitives = parsePrimitivesFromScreen(flexScreen);
+    const parent = primitives.find((p) => p.nodeId === "parent");
+    const first = primitives.find((p) => p.nodeId === "first");
+    const second = primitives.find((p) => p.nodeId === "second");
+    expect(parent?.autoLayoutAxis).toBe("x");
+    expect(first?.parentNodeId).toBe("parent");
+    expect(second?.parentNodeId).toBe("parent");
+    // Plain rectangle children are never themselves auto-layout containers.
+    expect(first?.autoLayoutAxis).toBeUndefined();
+  });
+
+  it("findAutoLayoutInsertionAnchor resolves 'before' the nearest child when the point sits in the leading padding", () => {
+    const primitives = parsePrimitivesFromScreen(flexScreen);
+    const parent = primitives.find((p) => p.nodeId === "parent")!;
+    // x=310 sits in the container's own left padding (content starts at 320),
+    // well left of "first"'s center (345) and far from "second"'s (410).
+    const anchor = findAutoLayoutInsertionAnchor(
+      parent,
+      primitives,
+      { x: 310, y: 135 },
+      null,
+    );
+    expect(anchor).toEqual({ anchorNodeId: "first", placement: "before" });
+  });
+
+  it("findAutoLayoutInsertionAnchor resolves 'after' the nearest child when the point sits in the gap between children", () => {
+    const primitives = parsePrimitivesFromScreen(flexScreen);
+    const parent = primitives.find((p) => p.nodeId === "parent")!;
+    // x=375 sits in the 10px gap between "first" (ends at 370) and "second"
+    // (starts at 380) — nearer to "first"'s center (345) than "second"'s (410).
+    const anchor = findAutoLayoutInsertionAnchor(
+      parent,
+      primitives,
+      { x: 375, y: 135 },
+      null,
+    );
+    expect(anchor).toEqual({ anchorNodeId: "first", placement: "after" });
+  });
+
+  it("findAutoLayoutInsertionAnchor excludes the dragged node itself (reordering within its own container)", () => {
+    const primitives = parsePrimitivesFromScreen(flexScreen);
+    const parent = primitives.find((p) => p.nodeId === "parent")!;
+    // Excluding "first" (e.g. it's the node being dragged) leaves "second" as
+    // the only candidate regardless of which side of it the point falls on.
+    const anchor = findAutoLayoutInsertionAnchor(
+      parent,
+      primitives,
+      { x: 310, y: 135 },
+      "first",
+    );
+    expect(anchor).toEqual({ anchorNodeId: "second", placement: "before" });
+  });
+
+  it("findAutoLayoutInsertionAnchor returns null for a non-auto-layout container", () => {
+    const primitives = parsePrimitivesFromScreen(flexScreen);
+    const first = primitives.find((p) => p.nodeId === "first")!;
+    expect(
+      findAutoLayoutInsertionAnchor(first, primitives, { x: 0, y: 0 }, null),
+    ).toBeNull();
+  });
+
+  it("getPrimitiveDropTargetForPoint resolves a before/after flow-insert anchor for a drop inside an auto-layout screen frame", () => {
+    // Board coords equal screen-local coords here (frame geometry matches the
+    // authored absolute offsets 1:1, viewport 800x600 wider than the frame's
+    // own 500x300 box — only the frame's own x/y/width/height matter for the
+    // 1:1 scale, matching the existing "accounts for padding" fixture).
+    const target = getPrimitiveDropTargetForPoint(
+      { x: 375, y: 135 },
+      null,
+      [flexScreen],
+      identityFrameGeometry,
+      identityMetadata,
+    );
+    expect(target?.nodeId).toBe("parent");
+    expect(target?.anchorNodeId).toBe("first");
+    expect(target?.placement).toBe("after");
+    expect(target?.axis).toBe("x");
+    // The rendered insertion-line rect should track the ANCHOR child's board
+    // rect (matching getCrossScreenDropGuideStyle's contract), not the whole
+    // container's rect.
+    expect(target?.boardRect.width).toBeCloseTo(50);
+  });
+
+  it("resolves the same auto-layout anchor/placement when the screen frame itself is rotated", () => {
+    // Adjacent coordinate-transform check (item 6): getPrimitiveDropTargetForPoint
+    // must map the incoming board-space point back into the screen's own
+    // LOCAL space (via boardPointToScreenLocalPoint, rotation-aware) before
+    // resolving the auto-layout anchor — otherwise a rotated screen frame
+    // would resolve the wrong sibling/placement even though the unrotated
+    // case (the "gap between children" test above) works.
+    const rotation = 90;
+    const frameGeometry = { x: 0, y: 0, width: 800, height: 600, rotation };
+    const center = {
+      x: frameGeometry.x + frameGeometry.width / 2,
+      y: frameGeometry.y + frameGeometry.height / 2,
+    };
+    // Same local drop point as the "gap between children" test (375, 135),
+    // mapped into board/world space through the frame's own rotation.
+    const worldPoint = rotatePoint({ x: 375, y: 135 }, center, rotation);
+    const target = getPrimitiveDropTargetForPoint(
+      worldPoint,
+      null,
+      [flexScreen],
+      { screen: frameGeometry },
+      identityMetadata,
+    );
+    expect(target?.nodeId).toBe("parent");
+    expect(target?.anchorNodeId).toBe("first");
+    expect(target?.placement).toBe("after");
+    expect(target?.axis).toBe("x");
+  });
+
+  it("getPrimitiveDropTargetForPoint falls back to 'inside' (no placement) for a plain non-auto-layout frame", () => {
+    const plainScreen = {
+      id: "plain",
+      filename: "plain.html",
+      content: `<!doctype html><html><body>
+        <div data-agent-native-node-id="frame" data-an-primitive="frame" style="position:absolute;left:0px;top:0px;width:400px;height:300px"></div>
+      </body></html>`,
+    };
+    const target = getPrimitiveDropTargetForPoint(
+      { x: 200, y: 150 },
+      null,
+      [plainScreen],
+      { plain: { x: 0, y: 0, width: 800, height: 600 } },
+      () => ({ width: 800, height: 600 }),
+    );
+    expect(target?.nodeId).toBe("frame");
+    expect(target?.placement).toBeUndefined();
+    expect(target?.anchorNodeId).toBeUndefined();
+  });
+});
diff --git a/templates/design/app/components/design/multi-screen/primitive-drop-target.ts b/templates/design/app/components/design/multi-screen/primitive-drop-target.ts
index be67227a14..49a32c056b 100644
--- a/templates/design/app/components/design/multi-screen/primitive-drop-target.ts
+++ b/templates/design/app/components/design/multi-screen/primitive-drop-target.ts
@@ -1,10 +1,15 @@
 import { hashString } from "./board-surface-html";
-import { screenLocalRectToBoardGeometry } from "./coordinate-transforms";
+import {
+  boardPointToScreenLocalPoint,
+  screenLocalRectToBoardGeometry,
+} from "./coordinate-transforms";
 import {
   geometryContainsGeometry,
   geometryContainsPoint,
 } from "./frame-geometry";
 import type {
+  CrossScreenDropAxis,
+  CrossScreenDropPlacement,
   FrameGeometry,
   FrameGeometryById,
   Point,
@@ -15,16 +20,164 @@ export interface PrimitiveDropTarget {
   nodeId: string;
   screenId: string;
   boardRect: FrameGeometry;
+  /**
+   * Set when the drop resolves to a flow-insert slot between two auto-layout
+   * (flex/grid) children instead of a plain "append inside" drop — mirrors
+   * the cross-screen hit-test's placement/axis contract (see
+   * getCrossScreenDropGuideForHitTest) so the overview canvas draws the same
+   * Figma-style insertion LINE, and the same anchor + placement can be
+   * threaded straight through onPrimitiveReparent. Undefined means "inside"
+   * (append as the last/only child of `nodeId`), matching pre-existing
+   * behavior.
+   */
+  placement?: CrossScreenDropPlacement;
+  axis?: CrossScreenDropAxis;
+  /**
+   * The sibling node to anchor a before/after flow-insert against. Only set
+   * when `placement` is "before" or "after" — `nodeId` still identifies the
+   * containing auto-layout primitive so callers can resolve the drop's
+   * screen/highlight, while `anchorNodeId` is what the actual moveNode/
+   * moveNodeBetweenDocuments call should target as its anchor.
+   */
+  anchorNodeId?: string;
 }
 
 export interface ParsedScreenPrimitive {
   nodeId: string;
   screenId: string;
+  /** data-agent-native-node-id of the nearest ancestor primitive, if any. */
+  parentNodeId?: string;
   localLeft: number;
   localTop: number;
   localWidth: number;
   localHeight: number;
   isContainer: boolean;
+  /**
+   * Set when this primitive is itself an auto-layout (flex/grid) container,
+   * to the flow axis new children are inserted along ("x" for a row flex/
+   * multi-column grid, "y" for column flex/single-column grid). Undefined
+   * for plain absolute/canvas-frame containers, which only ever accept an
+   * "inside" (append) drop.
+   */
+  autoLayoutAxis?: CrossScreenDropAxis;
+}
+
+/**
+ * Mirrors hit-test.bridge.ts's parentFlowAxis: resolves the flow axis new
+ * children are inserted along for a flex/grid container, or undefined when
+ * the element isn't an auto-layout container at all. Kept in sync with that
+ * bridge implementation (which runs against live computed styles inside the
+ * iframe) — this version only has the authored inline style available, which
+ * is sufficient since auto-layout is always inspector-authored inline CSS.
+ */
+function computeAutoLayoutAxis(style: {
+  display: string;
+  flexDirection: string;
+  flexWrap: string;
+  gridTemplateColumns: string;
+}): CrossScreenDropAxis | undefined {
+  if (style.display === "flex" || style.display === "inline-flex") {
+    const direction = style.flexDirection || "row";
+    const wraps =
+      style.flexWrap === "wrap" || style.flexWrap === "wrap-reverse";
+    const isRow = direction.startsWith("row");
+    return isRow && !wraps ? "x" : "y";
+  }
+  if (style.display === "grid" || style.display === "inline-grid") {
+    const columns = (style.gridTemplateColumns || "")
+      .split(" ")
+      .filter(Boolean).length;
+    return columns > 1 ? "x" : "y";
+  }
+  return undefined;
+}
+
+/**
+ * Resolves a between-children flow-insert slot inside `container` from a
+ * screen-local drop point — the nearest child (by flow-axis center) becomes
+ * the anchor with before/after placement, exactly mirroring hit-test.bridge.
+ * ts's nearestChildInsertionTarget so overview-canvas drag-drop and in-iframe
+ * cross-screen drag-drop produce the same Figma-style insertion behavior.
+ * Returns null when the container isn't auto-layout or has no eligible
+ * children (callers fall back to "inside" append).
+ */
+export function findAutoLayoutInsertionAnchor(
+  container: ParsedScreenPrimitive,
+  screenPrimitives: ParsedScreenPrimitive[],
+  localPoint: Point,
+  excludeNodeId: string | null,
+): { anchorNodeId: string; placement: "before" | "after" } | null {
+  const axis = container.autoLayoutAxis;
+  if (!axis) return null;
+  let best: ParsedScreenPrimitive | null = null;
+  let bestDistance = Infinity;
+  let placement: "before" | "after" = "after";
+  for (const sibling of screenPrimitives) {
+    if (sibling.parentNodeId !== container.nodeId) continue;
+    if (excludeNodeId && sibling.nodeId === excludeNodeId) continue;
+    const center =
+      axis === "x"
+        ? sibling.localLeft + sibling.localWidth / 2
+        : sibling.localTop + sibling.localHeight / 2;
+    const pointer = axis === "x" ? localPoint.x : localPoint.y;
+    const distance = Math.abs(pointer - center);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = sibling;
+      placement = pointer < center ? "before" : "after";
+    }
+  }
+  if (!best) return null;
+  return { anchorNodeId: best.nodeId, placement };
+}
+
+export function getPrimitiveLowZoomHitRect(
+  primitive: ParsedScreenPrimitive,
+  zoom: number,
+  minimumScreenPixels = 6,
+): FrameGeometry {
+  const scale = Math.max(0.0001, zoom / 100);
+  const minimumWorldSize = minimumScreenPixels / scale;
+  const width = Math.max(primitive.localWidth, minimumWorldSize);
+  const height = Math.max(primitive.localHeight, minimumWorldSize);
+  return {
+    x: primitive.localLeft - (width - primitive.localWidth) / 2,
+    y: primitive.localTop - (height - primitive.localHeight) / 2,
+    width,
+    height,
+  };
+}
+
+export function isPrimitiveContainer(args: {
+  tagName: string;
+  primitiveKind: string;
+  display: string;
+  borderRadius: string;
+}): boolean {
+  const isDiv = args.tagName.toLowerCase() === "div";
+  const primitiveKind = args.primitiveKind.toLowerCase();
+  const isEllipse =
+    args.borderRadius === "50%" || args.borderRadius === "50% 50% 50% 50%";
+  const isTextAutoSize = args.display === "inline-block";
+  const isAutoLayout =
+    args.display === "flex" ||
+    args.display === "inline-flex" ||
+    args.display === "grid" ||
+    args.display === "inline-grid";
+  // Canvas frames are structural containers even before Auto layout is
+  // enabled. Treating only rectangles as freeform containers made a freshly
+  // drawn frame reject child drops until the user changed its display mode.
+  const isCanvasContainer =
+    isDiv &&
+    (primitiveKind === "rectangle" ||
+      primitiveKind === "rect" ||
+      primitiveKind === "frame");
+  return (
+    isDiv &&
+    !isEllipse &&
+    !isTextAutoSize &&
+    (isAutoLayout || isCanvasContainer)
+  );
 }
 
 export const primitiveParseCache = new Map<string, ParsedScreenPrimitive[]>();
@@ -60,6 +213,175 @@ export function __getPrimitiveParseCacheSizesForTests() {
   };
 }
 
+type InlineNumericProperty =
+  | "width"
+  | "height"
+  | "left"
+  | "top"
+  | "paddingLeft"
+  | "paddingTop"
+  | "marginLeft"
+  | "marginRight"
+  | "marginTop"
+  | "marginBottom"
+  | "gap";
+
+function inlineNumber(element: Element, property: InlineNumericProperty) {
+  const value = (element as HTMLElement).style[property];
+  const parsed = Number.parseFloat(String(value || ""));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function elementInlineSize(element: Element, axis: "x" | "y") {
+  return inlineNumber(element, axis === "x" ? "width" : "height");
+}
+
+function cssPixelNumber(value: string | null | undefined) {
+  const match = String(value || "")
+    .trim()
+    .match(/^(-?\d+(?:\.\d+)?)px$/i);
+  const parsed = match?.[1] ? Number(match[1]) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function estimatedTextLineWidth(
+  text: string,
+  fontSize: number,
+  letterSpacing: number,
+) {
+  let width = 0;
+  for (const character of Array.from(text)) {
+    if (/\s/.test(character)) width += fontSize * 0.33;
+    else if (/[MW@#%&]/.test(character)) width += fontSize * 0.82;
+    else if (/[ilI1|.,'`:;]/.test(character)) width += fontSize * 0.3;
+    else if (character.codePointAt(0)! > 0xff) width += fontSize;
+    else width += fontSize * 0.56;
+  }
+  return Math.max(
+    1,
+    width + Math.max(0, Array.from(text).length - 1) * letterSpacing,
+  );
+}
+
+/**
+ * Deterministic, string/inline-style-only bounds for drawn auto-sized text.
+ * This intentionally avoids layout APIs so the same fallback works in SSR,
+ * tests, and before the live iframe answers. It is conservative enough for
+ * hit testing while honoring the authored typography and wrap contract.
+ */
+export function authoredTextIntrinsicSize(element: Element) {
+  const style = (element as HTMLElement).style;
+  const fontSize = Math.max(1, cssPixelNumber(style.fontSize) || 16);
+  const numericLineHeight = Number.parseFloat(style.lineHeight);
+  const lineHeight = Math.max(
+    1,
+    cssPixelNumber(style.lineHeight) ||
+      (Number.isFinite(numericLineHeight) && numericLineHeight > 0
+        ? numericLineHeight * fontSize
+        : fontSize * 1.2),
+  );
+  const letterSpacing = cssPixelNumber(style.letterSpacing);
+  const whiteSpace = style.whiteSpace || "normal";
+  const preservesLines = /^(?:pre|pre-wrap|pre-line|break-spaces)$/.test(
+    whiteSpace,
+  );
+  const rawText = element.textContent || "";
+  const lines = preservesLines
+    ? rawText.split(/\r?\n/)
+    : [rawText.replace(/\s+/g, " ").trim()];
+  const lineWidths = lines.map((line) =>
+    estimatedTextLineWidth(line, fontSize, letterSpacing),
+  );
+  const authoredWidth = cssPixelNumber(style.width);
+  const maxWidth = cssPixelNumber(style.maxWidth);
+  const wrapWidth = authoredWidth || maxWidth;
+  const mayWrap =
+    wrapWidth > 0 && whiteSpace !== "nowrap" && whiteSpace !== "pre";
+  const visualLineCount = lineWidths.reduce(
+    (count, width) =>
+      count + (mayWrap ? Math.max(1, Math.ceil(width / wrapWidth)) : 1),
+    0,
+  );
+  const naturalWidth = Math.max(1, ...lineWidths);
+  return {
+    width: Math.max(
+      1,
+      authoredWidth ||
+        (maxWidth ? Math.min(naturalWidth, maxWidth) : naturalWidth),
+    ),
+    height: Math.max(
+      1,
+      cssPixelNumber(style.height) || Math.max(1, visualLineCount) * lineHeight,
+    ),
+  };
+}
+
+/**
+ * Approximates an authored node's screen-local position from inline layout.
+ * This parser is the no-iframe fallback used while a live bridge is absent;
+ * absolute descendants must accumulate positioned ancestors, and common
+ * single-line flex/block flows need their preceding siblings accounted for.
+ *
+ * Exported so DesignEditor.tsx's getAbsolutePositioningForNodeInHtml can
+ * reuse the same ancestor-walking logic instead of reading a node's own
+ * inline left/top in isolation (which is only correct for direct children of
+ * the screen root — see that function's call sites for the nested-container
+ * reparent fix this enables).
+ */
+export function authoredElementPosition(element: Element): Point {
+  let x = 0;
+  let y = 0;
+  let cursor: Element | null = element;
+
+  while (cursor && cursor.parentElement) {
+    const htmlCursor = cursor as HTMLElement;
+    const style = htmlCursor.style;
+    const parent: Element = cursor.parentElement;
+    if (style.position === "fixed") {
+      x += inlineNumber(cursor, "left");
+      y += inlineNumber(cursor, "top");
+      break;
+    }
+    if (style.position === "absolute") {
+      x += inlineNumber(cursor, "left");
+      y += inlineNumber(cursor, "top");
+    } else {
+      const parentStyle = (parent as HTMLElement).style;
+      x += inlineNumber(parent, "paddingLeft");
+      y += inlineNumber(parent, "paddingTop");
+      const siblings: Element[] = Array.from(parent.children);
+      const index = siblings.indexOf(cursor);
+      if (index > 0) {
+        const previous = siblings.slice(0, index);
+        const gap = inlineNumber(parent, "gap");
+        const display = parentStyle.display;
+        const isFlex = display === "flex" || display === "inline-flex";
+        const isRow =
+          isFlex && !(parentStyle.flexDirection || "row").startsWith("column");
+        for (const sibling of previous as Element[]) {
+          if (isRow) {
+            x +=
+              elementInlineSize(sibling, "x") +
+              inlineNumber(sibling, "marginLeft") +
+              inlineNumber(sibling, "marginRight") +
+              gap;
+          } else {
+            y +=
+              elementInlineSize(sibling, "y") +
+              inlineNumber(sibling, "marginTop") +
+              inlineNumber(sibling, "marginBottom") +
+              (isFlex ? gap : 0);
+          }
+        }
+      }
+    }
+    cursor = parent;
+    if (cursor.tagName.toLowerCase() === "body") break;
+  }
+
+  return { x, y };
+}
+
 export function parsePrimitivesFromScreen(
   screen: ScreenFile,
 ): ParsedScreenPrimitive[] {
@@ -93,40 +415,50 @@ export function parsePrimitivesFromScreen(
       const primitiveKind = (
         element.getAttribute("data-an-primitive") || ""
       ).toLowerCase();
-      if (style.position !== "absolute") return;
-
-      const left = parseFloat(style.left) || 0;
-      const top = parseFloat(style.top) || 0;
-      const width = parseFloat(style.width) || 0;
-      const height = parseFloat(style.height) || 0;
+      const position = authoredElementPosition(element);
+      const intrinsicTextSize =
+        primitiveKind === "text" ? authoredTextIntrinsicSize(element) : null;
+      const width = parseFloat(style.width) || intrinsicTextSize?.width || 0;
+      const height = parseFloat(style.height) || intrinsicTextSize?.height || 0;
       if (width <= 0 || height <= 0) return;
 
-      const isDiv = tag === "div";
-      const isEllipse =
-        style.borderRadius === "50%" ||
-        style.borderRadius === "50% 50% 50% 50%";
-      const isTextAutoSize = style.display === "inline-block";
-      const isAutoLayout =
-        style.display === "flex" ||
-        style.display === "inline-flex" ||
-        style.display === "grid" ||
-        style.display === "inline-grid";
-      const isCanvasRectangle =
-        isDiv && (primitiveKind === "rectangle" || primitiveKind === "rect");
-      const isContainer =
-        isDiv &&
-        !isEllipse &&
-        !isTextAutoSize &&
-        (isAutoLayout || isCanvasRectangle);
+      const isContainer = isPrimitiveContainer({
+        tagName: tag,
+        primitiveKind,
+        display: style.display,
+        borderRadius: style.borderRadius,
+      });
+      const autoLayoutAxis = computeAutoLayoutAxis({
+        display: style.display,
+        flexDirection: style.flexDirection,
+        flexWrap: style.flexWrap,
+        gridTemplateColumns: style.gridTemplateColumns,
+      });
+
+      // Nearest ancestor primitive id, used to resolve direct children of a
+      // container for auto-layout before/after anchor resolution — see
+      // findAutoLayoutInsertionAnchor.
+      let parentNodeId: string | undefined;
+      let ancestor: Element | null = element.parentElement;
+      while (ancestor && ancestor.tagName.toLowerCase() !== "body") {
+        const ancestorId = ancestor.getAttribute("data-agent-native-node-id");
+        if (ancestorId) {
+          parentNodeId = ancestorId;
+          break;
+        }
+        ancestor = ancestor.parentElement;
+      }
 
       result.push({
         nodeId,
         screenId: screen.id,
-        localLeft: left,
-        localTop: top,
+        parentNodeId,
+        localLeft: position.x,
+        localTop: position.y,
         localWidth: width,
         localHeight: height,
         isContainer,
+        autoLayoutAxis,
       });
     });
   } catch {
@@ -266,6 +598,51 @@ export function getPrimitiveDropTargetForPoint(
       };
     }
   }
+
+  // Auto-layout drop participation: when the winning container is itself a
+  // flex/grid container, resolve the nearest before/after sibling slot
+  // instead of always appending "inside" — matches the cross-screen
+  // hit-test's nearestChildInsertionTarget so overview-canvas primitive
+  // drags into an existing auto-layout screen get the same Figma insertion
+  // index/indicator behavior.
+  if (best) {
+    const containerPrimitive = primitives.find(
+      (primitive) => primitive.nodeId === best!.nodeId,
+    );
+    if (containerPrimitive?.autoLayoutAxis) {
+      const localPoint = options.identityCoordinateScreenIds?.has(
+        topScreen.screen.id,
+      )
+        ? point
+        : boardPointToScreenLocalPoint(point, topScreen.geometry, metadata);
+      const anchor = findAutoLayoutInsertionAnchor(
+        containerPrimitive,
+        primitives,
+        localPoint,
+        draggedNodeId,
+      );
+      if (anchor) {
+        const anchorPrimitive = primitives.find(
+          (primitive) => primitive.nodeId === anchor.anchorNodeId,
+        );
+        if (anchorPrimitive) {
+          best = {
+            nodeId: containerPrimitive.nodeId,
+            screenId: topScreen.screen.id,
+            boardRect: toBoardRect(
+              anchorPrimitive,
+              topScreen.geometry,
+              metadata,
+            ),
+            anchorNodeId: anchor.anchorNodeId,
+            placement: anchor.placement,
+            axis: containerPrimitive.autoLayoutAxis,
+          };
+        }
+      }
+    }
+  }
+
   return best;
 }
 
diff --git a/templates/design/app/components/design/multi-screen/types.ts b/templates/design/app/components/design/multi-screen/types.ts
index ff3999246c..1e0a7d65ae 100644
--- a/templates/design/app/components/design/multi-screen/types.ts
+++ b/templates/design/app/components/design/multi-screen/types.ts
@@ -118,6 +118,12 @@ export interface MultiScreenCanvasProps {
   zoom: number;
   activeId?: string | null;
   selectedScreenIds?: string[];
+  /** Hidden screen/file rows retain geometry but do not render or participate
+   * in overview hit testing, fit, or selection until shown again. */
+  hiddenScreenIds?: ReadonlySet<string> | readonly string[];
+  /** Locked screen/file rows remain visible but cannot be selected or
+   * transformed directly from the overview canvas. */
+  lockedScreenIds?: ReadonlySet<string> | readonly string[];
   fullViewScreenIds?: string[];
   activeScreenHasHoveredChild?: boolean;
   hoveredChildScreenId?: string | null;
@@ -149,9 +155,22 @@ export interface MultiScreenCanvasProps {
   onPrimitiveReparent?: (args: {
     sourceNodeId: string;
     sourceScreenId: string;
+    /**
+     * The moveNode/moveNodeBetweenDocuments anchor: the containing primitive
+     * itself when `placement` is "inside" (append), or a sibling child of
+     * that container when `placement` is "before"/"after" (flow-insert at a
+     * specific index) — see PrimitiveDropTarget.anchorNodeId in
+     * primitive-drop-target.ts, which resolves which one to pass.
+     */
     targetNodeId: string;
     targetScreenId: string;
-    placement: "inside";
+    /**
+     * "inside" appends into the target container (absolute-drop parity with
+     * the historic behavior). "before"/"after" flow-inserts next to
+     * `targetNodeId` at the resolved auto-layout index, mirroring
+     * onCrossScreenElementDrop's targetAnchorPlacement contract.
+     */
+    placement: "before" | "after" | "inside";
   }) => void;
   onCreateScreenFrame?: (geometry: FrameGeometry) => void;
   onDeleteSelection?: (ids: string[]) => boolean | void;
diff --git a/templates/design/app/components/design/types.ts b/templates/design/app/components/design/types.ts
index fdad5e8abc..3419982296 100644
--- a/templates/design/app/components/design/types.ts
+++ b/templates/design/app/components/design/types.ts
@@ -1,3 +1,5 @@
+import type { ElementProvenance } from "@shared/source-mode";
+
 export interface PortableStyleSnapshotNode {
   sourceId?: string;
   path: number[];
@@ -10,11 +12,26 @@ export interface PortableStyleSnapshot {
   nodes: PortableStyleSnapshotNode[];
 }
 
+export interface RuntimeStructureMoveRequest {
+  requestId: number;
+  subject: { selector: string; sourceId?: string | null };
+  anchor: { selector: string; sourceId?: string | null };
+  placement: "before" | "after" | "inside";
+}
+
 export interface ElementInfo {
   tagName: string;
   componentName?: string;
   id?: string;
   sourceId?: string;
+  /**
+   * Source location reported by the canvas bridge. React development builds
+   * derive this from jsxDEV/Fiber debug frames; instrumented runtimes may emit
+   * the equivalent data-source-* attributes. This is provenance only, not a
+   * stable source identity: callers must still verify the file contents and
+   * location before any write.
+   */
+  provenance?: ElementProvenance;
   /**
    * Node-id integrity (id-on-demand): a durable candidate id the bridge minted
    * for this element because it has no stable `data-agent-native-node-id`
@@ -51,6 +68,15 @@ export interface ElementInfo {
   primitiveKind?: string;
   portableStyleSnapshot?: PortableStyleSnapshot;
   boundingRect: { x: number; y: number; width: number; height: number };
+  /** Exact bounds of the selected element's direct parent in the same
+   * document coordinate space as `boundingRect`. Constraint edits use this
+   * to preserve edge gaps, center offsets, and proportional Scale geometry. */
+  parentBoundingRect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
   textContent?: string;
   htmlContent?: string;
   /** Direct element children; text nodes are ignored. */
@@ -97,6 +123,13 @@ export interface ElementSelectionIntent {
   ctrlKey?: boolean;
 }
 
+export interface CanvasLayerHitCandidate {
+  key: string;
+  label: string;
+  screenId?: string;
+  info: ElementInfo;
+}
+
 export type DeviceFrameType = "none" | "desktop" | "tablet" | "mobile";
 
 export const DEVICE_FRAME_VIEWPORTS = {
diff --git a/templates/design/app/components/editor/PromptDialog.test.tsx b/templates/design/app/components/editor/PromptDialog.test.tsx
new file mode 100644
index 0000000000..4c2f770492
--- /dev/null
+++ b/templates/design/app/components/editor/PromptDialog.test.tsx
@@ -0,0 +1,211 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import PromptPopover from "./PromptDialog";
+
+interface ComposerStubProps {
+  draftScope?: string;
+  initialText?: string;
+  initialTextKey?: string | number;
+  onSubmit: (
+    text: string,
+    files: File[],
+    references: unknown[],
+    options: Record<string, unknown>,
+  ) => void;
+}
+
+vi.mock("@agent-native/core/client", () => ({
+  appBasePath: () => "",
+  useT:
+    () =>
+    (key: string, options?: Record<string, unknown>): string =>
+      options ? `${key}:${JSON.stringify(options)}` : key,
+  PromptComposer: (props: ComposerStubProps) => (
+    <div
+      data-testid="prompt-composer"
+      data-draft-scope={props.draftScope ?? ""}
+      data-initial-text={props.initialText ?? ""}
+      data-initial-text-key={String(props.initialTextKey ?? "")}
+    >
+      <button
+        type="button"
+        data-testid="composer-submit"
+        onClick={() => props.onSubmit("hello world", [], [], {})}
+      >
+        submit
+      </button>
+    </div>
+  ),
+}));
+
+vi.mock("@agent-native/core/embedding/react", () => ({
+  EmbeddedApp: () => null,
+}));
+
+vi.mock("@/components/ui/dialog", () => ({
+  Dialog: ({ open, children }: { open: boolean; children: unknown }) =>
+    open ? <div>{children as never}</div> : null,
+  DialogContent: ({ children }: { children: unknown }) => (
+    <div>{children as never}</div>
+  ),
+  DialogTitle: ({ children }: { children: unknown }) => (
+    <div>{children as never}</div>
+  ),
+}));
+
+vi.mock("@/components/ui/popover", () => ({
+  Popover: ({ open, children }: { open: boolean; children: unknown }) =>
+    open ? <div>{children as never}</div> : null,
+  PopoverAnchor: ({ children }: { children?: unknown }) => (
+    <>{children as never}</>
+  ),
+  PopoverContent: ({ children }: { children: unknown }) => (
+    <div>{children as never}</div>
+  ),
+  PopoverTrigger: ({ children }: { children: unknown }) => (
+    <>{children as never}</>
+  ),
+}));
+
+const toastError = vi.fn();
+vi.mock("sonner", () => ({
+  toast: { error: (...args: unknown[]) => toastError(...args) },
+}));
+
+let cleanup: (() => Promise<void>) | undefined;
+let root: Root | undefined;
+let container: HTMLDivElement | undefined;
+
+beforeEach(() => {
+  (
+    globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }
+  ).IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+afterEach(async () => {
+  await cleanup?.();
+  cleanup = undefined;
+  root = undefined;
+  container = undefined;
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+  toastError.mockClear();
+});
+
+async function renderPopover(props: Record<string, unknown>) {
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+  cleanup = async () => {
+    await act(async () => root?.unmount());
+    container?.remove();
+  };
+  await act(async () => {
+    root!.render(
+      <PromptPopover
+        open
+        onOpenChange={() => {}}
+        title="Generate design"
+        onSubmit={() => {}}
+        {...props}
+      />,
+    );
+  });
+}
+
+describe("PromptPopover draft isolation", () => {
+  it("scopes the composer draft key to this popover's title by default", async () => {
+    await renderPopover({ title: "Tweak design" });
+    const composer = container!.querySelector(
+      '[data-testid="prompt-composer"]',
+    );
+    expect(composer?.getAttribute("data-draft-scope")).toBe("Tweak design");
+  });
+
+  it("prefers an explicit draftScope over the title default", async () => {
+    await renderPopover({
+      title: "Generate design",
+      draftScope: "design:abc123:generate",
+    });
+    const composer = container!.querySelector(
+      '[data-testid="prompt-composer"]',
+    );
+    expect(composer?.getAttribute("data-draft-scope")).toBe(
+      "design:abc123:generate",
+    );
+  });
+});
+
+describe("PromptPopover submit failure recovery", () => {
+  it("restores the typed prompt into the composer instead of losing it when onSubmit rejects", async () => {
+    const onSubmit = vi.fn().mockRejectedValue(new Error("network down"));
+    await renderPopover({ onSubmit });
+
+    await act(async () => {
+      container!
+        .querySelector<HTMLButtonElement>('[data-testid="composer-submit"]')
+        ?.click();
+    });
+    // Let the async handleSubmit's rejection settle and re-render.
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(toastError).toHaveBeenCalledWith("network down");
+
+    const composer = container!.querySelector(
+      '[data-testid="prompt-composer"]',
+    );
+    // The composer optimistically clears its own text as soon as onSubmit is
+    // invoked, so the popover must feed the failed prompt back in via
+    // `initialText`/`initialTextKey` rather than let it vanish.
+    expect(composer?.getAttribute("data-initial-text")).toBe("hello world");
+    expect(composer?.getAttribute("data-initial-text-key")).not.toBe("");
+    expect(composer?.getAttribute("data-initial-text-key")).not.toBe("0");
+  });
+
+  it("does not surface a restore when onSubmit succeeds", async () => {
+    const onSubmit = vi.fn().mockResolvedValue(undefined);
+    await renderPopover({ onSubmit });
+
+    await act(async () => {
+      container!
+        .querySelector<HTMLButtonElement>('[data-testid="composer-submit"]')
+        ?.click();
+    });
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(toastError).not.toHaveBeenCalled();
+    const composer = container!.querySelector(
+      '[data-testid="prompt-composer"]',
+    );
+    expect(composer?.getAttribute("data-initial-text")).toBe("");
+  });
+});
+
+describe("PromptPopover skip affordance", () => {
+  it("falls back to the localized skip label when the caller doesn't pass one", async () => {
+    await renderPopover({ onSkip: vi.fn() });
+    const skipButton = Array.from(container!.querySelectorAll("button")).find(
+      (btn) => btn.textContent === "promptDialog.skipPrompt",
+    );
+    expect(skipButton).toBeTruthy();
+  });
+
+  it("uses an explicit skipLabel over the localized default", async () => {
+    await renderPopover({ onSkip: vi.fn(), skipLabel: "Not now" });
+    const skipButton = Array.from(container!.querySelectorAll("button")).find(
+      (btn) => btn.textContent === "Not now",
+    );
+    expect(skipButton).toBeTruthy();
+  });
+});
diff --git a/templates/design/app/components/editor/PromptDialog.tsx b/templates/design/app/components/editor/PromptDialog.tsx
index badf71ed72..92c1ef00bf 100644
--- a/templates/design/app/components/editor/PromptDialog.tsx
+++ b/templates/design/app/components/editor/PromptDialog.tsx
@@ -302,7 +302,7 @@ interface PromptPopoverProps {
     prompt: string,
     files: UploadedFile[],
     options: PromptComposerSubmitOptions,
-  ) => void;
+  ) => void | Promise<void>;
   loading?: boolean;
   anchorRef?: React.RefObject<HTMLElement | null>;
   centered?: boolean;
@@ -319,6 +319,16 @@ interface PromptPopoverProps {
    */
   creationMode?: PromptCreationMode;
   onCreationModeChange?: (mode: PromptCreationMode) => void;
+  /**
+   * Scopes the composer's localStorage draft key so an abandoned draft in
+   * this popover never bleeds into a different popover instance (e.g. the
+   * "generate design" and "tweak" popovers both mount unscoped composers
+   * that would otherwise share the same global draft key). Defaults to a
+   * scope derived from `title`, which is already distinct across the
+   * current call sites; pass an explicit value (e.g. including a design id)
+   * for finer isolation between instances that share the same title.
+   */
+  draftScope?: string;
 }
 
 export interface PromptDesignSystemOption {
@@ -372,7 +382,7 @@ export default function PromptPopover({
   title,
   placeholder,
   onSkip,
-  skipLabel = "Skip prompt",
+  skipLabel,
   onSubmit,
   loading = false,
   anchorRef,
@@ -384,12 +394,28 @@ export default function PromptPopover({
   onCreateDesignSystem,
   creationMode,
   onCreationModeChange,
+  draftScope,
 }: PromptPopoverProps) {
   const t = useT();
   const [uploading, setUploading] = useState(false);
   const [pickedAssets, setPickedAssets] = useState<UploadedFile[]>([]);
   const [selectedUploadFiles, setSelectedUploadFiles] = useState<File[]>([]);
   const [assetsPickerOpen, setAssetsPickerOpen] = useState(false);
+  // Restores a typed prompt into the composer after a failed submit. The
+  // composer optimistically clears its text as soon as onSubmit is invoked
+  // (see TiptapComposer.submitComposer), so without this an upload failure or
+  // a rejected onSubmit would silently erase what the user wrote. Left
+  // `undefined` in the common case so the composer's normal mount behavior
+  // (restore the last localStorage draft for this scope) still applies —
+  // passing a defined `initialText` (even `""`) would short-circuit that.
+  const [restoredPromptText, setRestoredPromptText] = useState<
+    string | undefined
+  >(undefined);
+  const [restoredPromptKey, setRestoredPromptKey] = useState(0);
+  const restorePromptText = useCallback((text: string) => {
+    setRestoredPromptText(text);
+    setRestoredPromptKey((key) => key + 1);
+  }, []);
   // While the nested design-system Select is open, Radix disables pointer
   // events on everything else and the click that closes the Select also
   // moves focus back to its trigger. That focus-return is itself reported to
@@ -428,6 +454,10 @@ export default function PromptPopover({
     setAssetsPickerOpen(false);
     setPickedAssets([]);
     setSelectedUploadFiles([]);
+    // Only sticks for the session immediately following a failed submit; a
+    // fresh open after a real close should fall back to the composer's own
+    // localStorage draft restore for this scope, not a stale failed prompt.
+    setRestoredPromptText(undefined);
   }, [open]);
 
   const uploadFiles = useCallback(
@@ -482,20 +512,39 @@ export default function PromptPopover({
       _references: unknown,
       options: PromptComposerSubmitOptions,
     ) => {
+      let uploaded: UploadedFile[];
       try {
-        const uploaded = await uploadFiles([...files, ...selectedUploadFiles]);
-        onSubmit(text.trim(), [...uploaded, ...pickedAssets], options);
+        uploaded = await uploadFiles([...files, ...selectedUploadFiles]);
+      } catch (error) {
+        restorePromptText(text);
+        toast.error(
+          error instanceof Error
+            ? error.message
+            : t("promptDialog.failedToUploadFile"),
+        );
+        return;
+      }
+      try {
+        await onSubmit(text.trim(), [...uploaded, ...pickedAssets], options);
         setPickedAssets([]);
         setSelectedUploadFiles([]);
       } catch (error) {
+        restorePromptText(text);
         toast.error(
           error instanceof Error
             ? error.message
-            : t("promptDialog.failedToUploadFile"),
+            : t("promptDialog.failedToSubmitPrompt"),
         );
       }
     },
-    [onSubmit, pickedAssets, selectedUploadFiles, uploadFiles],
+    [
+      onSubmit,
+      pickedAssets,
+      restorePromptText,
+      selectedUploadFiles,
+      t,
+      uploadFiles,
+    ],
   );
 
   const handleAssetsPickerReady = useCallback(
@@ -667,6 +716,9 @@ export default function PromptPopover({
             disabled={loading || uploading}
             placeholder={placeholder ?? t("home.describeBuild")}
             onSubmit={handleSubmit}
+            draftScope={draftScope ?? title}
+            initialText={restoredPromptText}
+            initialTextKey={restoredPromptKey}
             attachButton={
               <PromptAttachmentMenu
                 disabled={loading || uploading}
@@ -785,7 +837,7 @@ export default function PromptPopover({
               }}
               className="cursor-pointer text-xs text-[#609FF8] hover:text-[#7AB2FA]"
             >
-              {skipLabel}
+              {skipLabel ?? t("promptDialog.skipPrompt")}
             </button>
           </div>
         )}
diff --git a/templates/design/app/components/visual-editor/CanvasCommentPins.test.tsx b/templates/design/app/components/visual-editor/CanvasCommentPins.test.tsx
new file mode 100644
index 0000000000..3c52ca4467
--- /dev/null
+++ b/templates/design/app/components/visual-editor/CanvasCommentPins.test.tsx
@@ -0,0 +1,260 @@
+// @vitest-environment happy-dom
+
+import { act, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { CanvasCommentPins } from "./CanvasCommentPins";
+
+vi.mock("@agent-native/core/client", () => ({
+  cn: (...values: Array<string | false | null | undefined>) =>
+    values.filter(Boolean).join(" "),
+  useT:
+    () =>
+    (key: string, options?: Record<string, unknown>): string =>
+      options ? `${key}:${JSON.stringify(options)}` : key,
+}));
+
+vi.mock("@/components/ui/tooltip", () => ({
+  Tooltip: ({ children }: { children: ReactNode }) => children,
+  TooltipTrigger: ({ children }: { children: ReactNode }) => children,
+  TooltipContent: ({ children }: { children: ReactNode }) => (
+    <div data-tooltip-content>{children}</div>
+  ),
+}));
+
+const sendToDesignAgentChat = vi.fn((..._args: unknown[]) => "tab-1");
+vi.mock("@/lib/agent-chat", () => ({
+  sendToDesignAgentChat: (...args: unknown[]) => sendToDesignAgentChat(...args),
+}));
+
+const toastFn = vi.fn();
+vi.mock("sonner", () => ({ toast: (...args: unknown[]) => toastFn(...args) }));
+
+const CANVAS_RECT = {
+  x: 0,
+  y: 0,
+  left: 0,
+  top: 0,
+  right: 200,
+  bottom: 100,
+  width: 200,
+  height: 100,
+  toJSON: () => ({}),
+} as DOMRect;
+
+function clickAt(target: Element, clientX: number, clientY: number) {
+  target.dispatchEvent(
+    new MouseEvent("click", {
+      bubbles: true,
+      cancelable: true,
+      clientX,
+      clientY,
+    }),
+  );
+}
+
+function setTextareaValue(el: HTMLTextAreaElement, value: string) {
+  Object.getOwnPropertyDescriptor(
+    HTMLTextAreaElement.prototype,
+    "value",
+  )?.set?.call(el, value);
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+interface Rendered {
+  container: HTMLDivElement;
+  canvasEl: HTMLDivElement;
+  root: Root;
+  rerender: (props: Record<string, unknown>) => Promise<void>;
+  cleanup: () => Promise<void>;
+}
+
+async function renderPins(
+  props: Record<string, unknown> = {},
+): Promise<Rendered> {
+  // `canvasEl` stands in for the app's real slide/design canvas element,
+  // which always lives outside the React tree CanvasCommentPins itself
+  // renders into. It must be a *sibling* of `container`, not a child —
+  // `createRoot(container).render(...)` takes ownership of `container` and
+  // clears any DOM nodes placed inside it before the first commit, which
+  // would silently delete a pre-existing child and make `canvasSelector`
+  // resolve to nothing.
+  const container = document.createElement("div");
+  const canvasEl = document.createElement("div");
+  canvasEl.setAttribute("data-test-canvas", "");
+  document.body.append(canvasEl);
+  document.body.append(container);
+
+  Object.defineProperty(canvasEl, "getBoundingClientRect", {
+    configurable: true,
+    value: () => CANVAS_RECT,
+  });
+
+  const root = createRoot(container);
+  const baseProps = {
+    active: true,
+    canvasSelector: "[data-test-canvas]",
+    contextId: "slide-1",
+    contextLabel: "Slide 1",
+    onClose: vi.fn(),
+    ...props,
+  };
+
+  const rerender = async (nextProps: Record<string, unknown>) => {
+    await act(async () => {
+      root.render(<CanvasCommentPins {...baseProps} {...nextProps} />);
+    });
+    // Let the canvas-lookup retry effect's setTimeout(50) settle.
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 60));
+    });
+  };
+
+  await rerender({});
+
+  return {
+    container,
+    canvasEl,
+    root,
+    rerender,
+    cleanup: async () => {
+      await act(async () => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+let cleanup: (() => Promise<void>) | undefined;
+
+beforeEach(() => {
+  (
+    globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }
+  ).IS_REACT_ACT_ENVIRONMENT = true;
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe() {}
+      disconnect() {}
+    },
+  );
+});
+
+afterEach(async () => {
+  await cleanup?.();
+  cleanup = undefined;
+  document.body.replaceChildren();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  toastFn.mockClear();
+  sendToDesignAgentChat.mockClear();
+});
+
+describe("CanvasCommentPins anchoring and clustering", () => {
+  it("spreads two pins dropped at nearly the same spot instead of stacking them", async () => {
+    const rendered = await renderPins();
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      clickAt(rendered.canvasEl, 50, 50); // 25%, 50%
+      clickAt(rendered.canvasEl, 52, 51); // 26%, 51% — within the overlap threshold
+    });
+
+    const pinEls = rendered.container.querySelectorAll("[data-pin-id]");
+    expect(pinEls.length).toBe(2);
+
+    const firstLeft = parseFloat((pinEls[0] as HTMLElement).style.left);
+    const secondLeft = parseFloat((pinEls[1] as HTMLElement).style.left);
+    const secondTop = parseFloat((pinEls[1] as HTMLElement).style.top);
+
+    // The first pin renders at its exact percentage position; the second,
+    // clustering with it, must be nudged so both stay individually visible
+    // and clickable instead of rendering stacked on top of one another.
+    expect(firstLeft).toBeCloseTo(50, 5);
+    expect(secondLeft === 52 && secondTop === 51).toBe(false);
+  });
+
+  it("flags a pin whose anchored element has since been removed from the canvas", async () => {
+    const rendered = await renderPins();
+    cleanup = rendered.cleanup;
+
+    const anchored = document.createElement("button");
+    anchored.id = "hero-cta";
+    anchored.textContent = "Get started";
+    rendered.canvasEl.append(anchored);
+
+    await act(async () => {
+      anchored.dispatchEvent(
+        new MouseEvent("click", {
+          bubbles: true,
+          cancelable: true,
+          clientX: 40,
+          clientY: 20,
+        }),
+      );
+    });
+
+    const marker = () =>
+      rendered.container.querySelector<HTMLButtonElement>(
+        "[data-pin-id] button",
+      );
+    expect(marker()?.className).not.toContain("outline-dashed");
+
+    // Simulate the element being deleted elsewhere on the canvas (e.g. the
+    // agent or the user removed the layer), then force the component to
+    // re-evaluate via the same window-resize listener it already relies on
+    // to keep pins glued to the canvas — no dedicated poll needed.
+    anchored.remove();
+    await act(async () => {
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    expect(marker()?.className).toContain("outline-dashed");
+    const tooltip = rendered.container.querySelector("[data-tooltip-content]");
+    expect(tooltip?.textContent).toBe("visualEditor.staleAnchorDetail");
+  });
+});
+
+describe("CanvasCommentPins queued draft handling", () => {
+  it("warns instead of silently discarding a queued draft when the context changes", async () => {
+    const rendered = await renderPins({ submitMode: "queue" });
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      clickAt(rendered.canvasEl, 20, 20);
+    });
+
+    const textarea = rendered.container.querySelector<HTMLTextAreaElement>(
+      'textarea[placeholder="visualEditor.tellAgentWhatToChange"]',
+    );
+    if (!textarea) throw new Error("Pin composer did not render");
+    await act(async () => {
+      setTextareaValue(textarea, "Make this button bigger");
+    });
+
+    const queueButton = Array.from(
+      rendered.container.querySelectorAll("button"),
+    ).find((btn) => btn.textContent?.includes("visualEditor.queue"));
+    if (!queueButton) throw new Error("Queue button did not render");
+    await act(async () => {
+      queueButton.click();
+    });
+
+    // Switch to a different slide/design without submitting the queued draft.
+    await rendered.rerender({ contextId: "slide-2" });
+
+    expect(toastFn).toHaveBeenCalledTimes(1);
+    expect(toastFn.mock.calls[0]?.[0]).toContain(
+      "visualEditor.queuedCommentsDiscarded",
+    );
+  });
+
+  it("does not warn when there is nothing queued", async () => {
+    const rendered = await renderPins();
+    cleanup = rendered.cleanup;
+
+    await rendered.rerender({ contextId: "slide-2" });
+
+    expect(toastFn).not.toHaveBeenCalled();
+  });
+});
diff --git a/templates/design/app/components/visual-editor/CanvasCommentPins.tsx b/templates/design/app/components/visual-editor/CanvasCommentPins.tsx
index b322a1d317..2d42c9367c 100644
--- a/templates/design/app/components/visual-editor/CanvasCommentPins.tsx
+++ b/templates/design/app/components/visual-editor/CanvasCommentPins.tsx
@@ -9,6 +9,7 @@ import {
   IconX,
 } from "@tabler/icons-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
 import { Textarea } from "@/components/ui/textarea";
@@ -141,6 +142,26 @@ function escapeCssIdentifier(value: string): string {
   return value.replace(/[^a-zA-Z0-9_-]/g, "\\$&");
 }
 
+/**
+ * Best-effort check for whether a pin's captured anchor element still exists
+ * on the canvas. Only meaningful for parent-DOM canvases with a captured
+ * `targetSelector` — iframe canvases never capture one (see `dropPinAt`), so
+ * this naturally no-ops there rather than mislabeling every iframe pin as
+ * stale. Recomputed on each render (already triggered by scroll/resize/pins
+ * changes); this deliberately avoids adding a dedicated poll so idle canvas
+ * perf is unaffected.
+ */
+function pinAnchorStillPresent(canvas: HTMLElement, pin: CanvasPin): boolean {
+  if (!pin.targetSelector) return true;
+  try {
+    return canvas.querySelector(pin.targetSelector) !== null;
+  } catch {
+    // A selector that no longer parses shouldn't be reported as "stale" —
+    // that's a different failure mode than "the element was removed".
+    return true;
+  }
+}
+
 function getTargetAnchor(target?: HTMLElement | null): {
   targetSelector?: string;
   targetAnchorId?: string;
@@ -207,6 +228,46 @@ function pinsLikelyOverlap(pin: CanvasPin, other: CanvasPin): boolean {
   return xDelta <= 4 && yDelta <= 4;
 }
 
+/**
+ * Purely visual "same spot" check used to spread overlapping markers apart on
+ * screen. Unlike `pinsLikelyOverlap` (which only flags *live* conflicts and
+ * ignores already-submitted pins), this also considers submitted pins so a
+ * new pin dropped on top of an earlier confirmation marker doesn't render
+ * fully hidden/unclickable underneath it.
+ */
+function pinsAtSameSpot(pin: CanvasPin, other: CanvasPin): boolean {
+  if (pin.id === other.id) return false;
+  const xDelta = Math.abs(pin.xPct - other.xPct);
+  const yDelta = Math.abs(pin.yPct - other.yPct);
+  return xDelta <= 3 && yDelta <= 3;
+}
+
+/**
+ * Deterministic pixel nudge for a pin whose marker would otherwise render
+ * stacked exactly on top of an earlier pin at (approximately) the same
+ * canvas position. Pins are placed in a small golden-angle spiral around
+ * their true position so every marker in a cluster stays visible and
+ * individually clickable; the stored `xPct`/`yPct` (and the position sent to
+ * the agent) are unaffected.
+ */
+function pinClusterOffset(
+  pin: CanvasPin,
+  indexInPins: number,
+  pins: CanvasPin[],
+): { dx: number; dy: number } {
+  let clusterIndex = 0;
+  for (let i = 0; i < indexInPins; i++) {
+    if (pinsAtSameSpot(pin, pins[i]!)) clusterIndex += 1;
+  }
+  if (clusterIndex === 0) return { dx: 0, dy: 0 };
+  const angle = clusterIndex * 2.4; // golden angle (radians) for even spread
+  const radius = 9 + clusterIndex * 5;
+  return {
+    dx: Math.round(Math.cos(angle) * radius),
+    dy: Math.round(Math.sin(angle) * radius),
+  };
+}
+
 function derivePinStatus(pin: CanvasPin, pins: CanvasPin[]): PinStatusMeta {
   const text = (pin.draft || "").toLowerCase();
   const anchored = Boolean(pin.targetSelector || pin.targetAnchorId);
@@ -298,6 +359,11 @@ export function CanvasCommentPins({
 }: CanvasCommentPinsProps) {
   const t = useT();
   const [pins, setPins] = useState<CanvasPin[]>([]);
+  // Mirrors `pins` so the context-change reset effect below can inspect what
+  // was on the canvas the instant `contextId` changes, without re-running on
+  // every pin edit (it should only fire once, on the context switch itself).
+  const pinsRef = useRef<CanvasPin[]>(pins);
+  pinsRef.current = pins;
   const [activePinId, setActivePinId] = useState<string | null>(null);
   const containerRef = useRef<HTMLElement | null>(null);
   const lastSubmitQueuedSignalRef = useRef(submitQueuedSignal);
@@ -308,9 +374,25 @@ export function CanvasCommentPins({
 
   // Reset pins when the context (slide) changes — they're scoped to one view.
   useEffect(() => {
+    // Queued-but-unsent comment drafts don't survive a context switch (pins
+    // are intentionally scoped to one view). Losing them is unavoidable here
+    // since we don't control cross-view navigation, but it must never be
+    // silent — warn instead of quietly wiping the user's typed drafts.
+    const discardedDraftCount = pinsRef.current.filter(
+      (pin) => pin.queued && !pin.submitted && (pin.draft || "").trim(),
+    ).length;
+    if (discardedDraftCount > 0) {
+      toast(
+        t("visualEditor.queuedCommentsDiscarded", {
+          count: discardedDraftCount,
+        }),
+      );
+    }
     setPins([]);
     setActivePinId(null);
     setCanvasEl(null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- only fire on an
+    // actual context (slide/design) switch, not on every pins/t change.
   }, [contextId]);
 
   // Find the canvas container the pins overlay
@@ -724,12 +806,19 @@ export function CanvasCommentPins({
       )}
 
       {/* Pin overlays */}
-      {pins.map((pin) => {
-        const left = rect.left + (pin.xPct / 100) * rect.width;
-        const top = rect.top + (pin.yPct / 100) * rect.height;
+      {pins.map((pin, pinIndex) => {
+        const { dx, dy } = pinClusterOffset(pin, pinIndex, pins);
+        const left = rect.left + (pin.xPct / 100) * rect.width + dx;
+        const top = rect.top + (pin.yPct / 100) * rect.height + dy;
         const isActive = activePinId === pin.id;
         const PinIcon = pin.submitted ? IconMessageCheck : IconMessage;
         const status = localizePinStatus(derivePinStatus(pin, pins), t);
+        // Not submitted yet + claims a specific anchor that's no longer on
+        // the canvas (e.g. the element was deleted or the design was edited
+        // elsewhere) — flag it instead of silently pretending the position
+        // is still meaningful.
+        const isStaleAnchor =
+          !pin.submitted && !pinAnchorStillPresent(canvas, pin);
         return (
           <div
             key={pin.id}
@@ -754,22 +843,26 @@ export function CanvasCommentPins({
                     "absolute -mt-1 flex size-7 -translate-x-1/2 -translate-y-full cursor-pointer items-center justify-center rounded-full rounded-bl-none shadow-lg ring-2 transition-transform hover:scale-110",
                     status.markerClassName,
                     pin.submitted && "opacity-95",
+                    isStaleAnchor &&
+                      "outline outline-2 outline-dashed outline-offset-2 outline-muted-foreground/70",
                   )}
                 >
                   <PinIcon className="size-3.5" />
                 </button>
               </TooltipTrigger>
               <TooltipContent className="pointer-events-none">
-                {pin.queued
-                  ? t("visualEditor.queuedStatus", { status: status.label })
-                  : pin.draft ||
-                    (pin.submitted
-                      ? t("visualEditor.commentSentStatus", {
-                          status: status.label,
-                        })
-                      : t("visualEditor.commentStatus", {
-                          status: status.label,
-                        }))}
+                {isStaleAnchor
+                  ? t("visualEditor.staleAnchorDetail")
+                  : pin.queued
+                    ? t("visualEditor.queuedStatus", { status: status.label })
+                    : pin.draft ||
+                      (pin.submitted
+                        ? t("visualEditor.commentSentStatus", {
+                            status: status.label,
+                          })
+                        : t("visualEditor.commentStatus", {
+                            status: status.label,
+                          }))}
               </TooltipContent>
             </Tooltip>
             <span
@@ -846,10 +939,19 @@ export function CanvasCommentPins({
                       {status.detail}
                     </p>
                     {pin.targetAnchorId && (
-                      <div className="mt-1 truncate rounded-md bg-muted/45 px-2 py-1 text-[10px] text-muted-foreground">
-                        {t("visualEditor.anchorLabel", {
-                          id: pin.targetAnchorId,
-                        })}
+                      <div
+                        className={cn(
+                          "mt-1 truncate rounded-md px-2 py-1 text-[10px]",
+                          isStaleAnchor
+                            ? "bg-destructive/10 text-destructive"
+                            : "bg-muted/45 text-muted-foreground",
+                        )}
+                      >
+                        {isStaleAnchor
+                          ? t("visualEditor.staleAnchorDetail")
+                          : t("visualEditor.anchorLabel", {
+                              id: pin.targetAnchorId,
+                            })}
                       </div>
                     )}
                     {pin.targetText && (
diff --git a/templates/design/app/components/visual-editor/DrawOverlay.test.tsx b/templates/design/app/components/visual-editor/DrawOverlay.test.tsx
index a96104ebec..3ad925fef5 100644
--- a/templates/design/app/components/visual-editor/DrawOverlay.test.tsx
+++ b/templates/design/app/components/visual-editor/DrawOverlay.test.tsx
@@ -2,6 +2,7 @@
 
 import { act, type ReactNode } from "react";
 import { createRoot, type Root } from "react-dom/client";
+import { toast } from "sonner";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { DrawOverlay, type DrawAnnotation } from "./DrawOverlay";
@@ -36,7 +37,13 @@ interface RenderedOverlay {
   canvas: HTMLCanvasElement;
   root: Root;
   container: HTMLDivElement;
-  rerender: (visible: boolean) => Promise<void>;
+  onClose: ReturnType<typeof vi.fn>;
+  rerender: (
+    visible: boolean,
+    sending?: boolean,
+    clearSignal?: number,
+    scopeKey?: string,
+  ) => Promise<void>;
   cleanup: () => Promise<void>;
 }
 
@@ -65,25 +72,37 @@ async function renderOverlay(
     canvasSize: { width: number; height: number },
   ) => void,
   queuedAnnotationCount = 0,
+  initialVisible = true,
+  initialScopeKey?: string,
 ): Promise<RenderedOverlay> {
   const container = document.createElement("div");
   document.body.append(container);
   const root = createRoot(container);
-
-  const render = async (visible: boolean) => {
+  const onClose = vi.fn();
+
+  const render = async (
+    visible: boolean,
+    sending = false,
+    clearSignal?: number,
+    scopeKey?: string,
+  ) => {
     await act(async () => {
       root.render(
         <DrawOverlay
           queuedAnnotationCount={queuedAnnotationCount}
           visible={visible}
-          onClose={vi.fn()}
+          sending={sending}
+          clearSignal={clearSignal}
+          scopeKey={scopeKey}
+          retainSurfaceWhenHidden
+          onClose={onClose}
           onSend={onSend}
         />,
       );
     });
   };
 
-  await render(true);
+  await render(initialVisible, false, undefined, initialScopeKey);
   const canvas =
     container.querySelector<HTMLCanvasElement>("[data-draw-canvas]");
   if (!canvas) throw new Error("Draw canvas did not render");
@@ -113,6 +132,7 @@ async function renderOverlay(
     canvas,
     root,
     container,
+    onClose,
     rerender: render,
     cleanup: async () => {
       await act(async () => root.unmount());
@@ -122,6 +142,15 @@ async function renderOverlay(
 }
 
 let cleanup: (() => Promise<void>) | undefined;
+let canvasContext: {
+  beginPath: ReturnType<typeof vi.fn>;
+  clearRect: ReturnType<typeof vi.fn>;
+  lineTo: ReturnType<typeof vi.fn>;
+  moveTo: ReturnType<typeof vi.fn>;
+  scale: ReturnType<typeof vi.fn>;
+  stroke: ReturnType<typeof vi.fn>;
+};
+let resizeObserve: ReturnType<typeof vi.fn>;
 
 beforeEach(() => {
   (
@@ -141,24 +170,26 @@ beforeEach(() => {
     "cancelAnimationFrame",
     vi.fn((id: number) => frames.delete(id)),
   );
+  resizeObserve = vi.fn();
   vi.stubGlobal(
     "ResizeObserver",
     class {
-      observe() {}
+      observe = resizeObserve;
       disconnect() {}
     },
   );
 
+  canvasContext = {
+    beginPath: vi.fn(),
+    clearRect: vi.fn(),
+    lineTo: vi.fn(),
+    moveTo: vi.fn(),
+    scale: vi.fn(),
+    stroke: vi.fn(),
+  };
   Object.defineProperty(HTMLCanvasElement.prototype, "getContext", {
     configurable: true,
-    value: () => ({
-      beginPath: vi.fn(),
-      clearRect: vi.fn(),
-      lineTo: vi.fn(),
-      moveTo: vi.fn(),
-      scale: vi.fn(),
-      stroke: vi.fn(),
-    }),
+    value: () => canvasContext,
   });
 });
 
@@ -251,7 +282,13 @@ describe("DrawOverlay pointer gesture robustness", () => {
     );
   });
 
-  it("clears completed and active gestures when draw mode is hidden", async () => {
+  it("preserves a completed stroke across a hide/show that has no clearSignal bump", async () => {
+    // Regression test: `visible` toggling off must NOT discard already-
+    // committed annotations. Only switching tools/views/panels (which flips
+    // `drawMode` without the caller treating it as a deliberate discard)
+    // should behave this way — the strokes survive so the user can re-enter
+    // Annotate and still send what they drew. Text mode itself still resets
+    // since that's transient tool-selection state, not committed content.
     const onSend = vi.fn();
     const rendered = await renderOverlay(onSend);
     cleanup = rendered.cleanup;
@@ -269,10 +306,142 @@ describe("DrawOverlay pointer gesture robustness", () => {
     expect(
       document.querySelector<HTMLButtonElement>('[data-testid="draw-send"]')
         ?.disabled,
-    ).toBe(true);
+    ).toBe(false);
     expect(
       rendered.container.querySelector("[data-draw-canvas]")?.className,
     ).toContain("cursor-crosshair");
+
+    await act(async () => {
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-send"]')
+        ?.click();
+    });
+    expect(onSend).toHaveBeenCalledTimes(1);
+    expect(onSend.mock.calls[0][0]).toEqual([
+      expect.objectContaining({ type: "path" }),
+    ]);
+  });
+
+  it("repaints preserved strokes before a hidden overlay becomes visible again", async () => {
+    const rendered = await renderOverlay(vi.fn());
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 20, 20));
+      rendered.canvas.dispatchEvent(pointerEvent("pointerup", 60, 40));
+    });
+    const paintedBeforeHide = canvasContext.stroke.mock.calls.length;
+    expect(paintedBeforeHide).toBeGreaterThan(0);
+
+    await rendered.rerender(false);
+    expect(rendered.container.querySelector("[data-draw-canvas]")).toBe(
+      rendered.canvas,
+    );
+    await rendered.rerender(true);
+
+    expect(canvasContext.stroke.mock.calls.length).toBeGreaterThan(
+      paintedBeforeHide,
+    );
+  });
+
+  it("installs canvas resize observation even when initially hidden", async () => {
+    const rendered = await renderOverlay(vi.fn(), 0, false);
+    cleanup = rendered.cleanup;
+
+    expect(resizeObserve).toHaveBeenCalledWith(rendered.canvas);
+    expect(rendered.container.querySelector("[data-draw-canvas]")).toBe(
+      rendered.canvas,
+    );
+  });
+
+  it("commits (rather than discards) a still-open pending text label on hide", async () => {
+    const onSend = vi.fn();
+    const rendered = await renderOverlay(onSend);
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-text-mode"]')
+        ?.click();
+    });
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 50, 25));
+    });
+    const input = rendered.container.querySelector<HTMLInputElement>(
+      'input[placeholder="visualEditor.typeAnnotationFancy"]',
+    );
+    if (!input) throw new Error("Pending text input did not render");
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "value",
+      )?.set?.call(input, "Still typing this");
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+
+    // Hide without ever clicking Send or blurring the input — e.g. the user
+    // switched tools mid-label.
+    await rendered.rerender(false);
+    await rendered.rerender(true);
+
+    await act(async () => {
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-send"]')
+        ?.click();
+    });
+    expect(onSend).toHaveBeenCalledTimes(1);
+    expect(onSend.mock.calls[0][0]).toEqual([
+      expect.objectContaining({
+        type: "text",
+        text: "Still typing this",
+      }),
+    ]);
+  });
+
+  it("clears strokes/text only when clearSignal is bumped (deliberate close or confirmed send)", async () => {
+    const onSend = vi.fn();
+    const rendered = await renderOverlay(onSend);
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 20, 20));
+      rendered.canvas.dispatchEvent(pointerEvent("pointerup", 60, 40));
+    });
+    expect(
+      document.querySelector<HTMLButtonElement>('[data-testid="draw-send"]')
+        ?.disabled,
+    ).toBe(false);
+
+    // Same transition a real "X" close or confirmed-send exit performs: hide
+    // AND bump clearSignal together.
+    await rendered.rerender(false, false, 1);
+    await rendered.rerender(true, false, 1);
+
+    expect(
+      document.querySelector<HTMLButtonElement>('[data-testid="draw-send"]')
+        ?.disabled,
+    ).toBe(true);
+  });
+
+  it("clears and warns when a preserved batch changes screen scope", async () => {
+    const onSend = vi.fn();
+    const rendered = await renderOverlay(onSend, 0, true, "screen-a");
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 20, 20));
+      rendered.canvas.dispatchEvent(pointerEvent("pointerup", 60, 40));
+    });
+    await rendered.rerender(false, false, undefined, "screen-b");
+    await rendered.rerender(true, false, undefined, "screen-b");
+
+    expect(
+      document.querySelector<HTMLButtonElement>('[data-testid="draw-send"]')
+        ?.disabled,
+    ).toBe(true);
+    expect(vi.mocked(toast)).toHaveBeenCalledWith(
+      "visualEditor.annotationsDiscardedOnViewChange",
+    );
   });
 
   it("disables native touch panning on the drawing surface", async () => {
@@ -327,6 +496,74 @@ describe("DrawOverlay pointer gesture robustness", () => {
     ]);
   });
 
+  it("commits a still-typed text label instead of discarding it when a new spot is clicked", async () => {
+    const onSend = vi.fn();
+    const rendered = await renderOverlay(onSend);
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-text-mode"]')
+        ?.click();
+    });
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 20, 20));
+    });
+
+    const firstInput = rendered.container.querySelector<HTMLInputElement>(
+      'input[placeholder="visualEditor.typeAnnotationFancy"]',
+    );
+    if (!firstInput) throw new Error("First pending text input did not render");
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "value",
+      )?.set?.call(firstInput, "First label");
+      firstInput.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+
+    // Click a second spot before the first label's blur has a chance to run
+    // (mirrors a real browser, where pointerdown on the canvas fires before
+    // the outgoing input's native blur). Without committing the outgoing box
+    // first, this used to silently discard "First label".
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 120, 60));
+    });
+
+    const secondInput = rendered.container.querySelector<HTMLInputElement>(
+      'input[placeholder="visualEditor.typeAnnotationFancy"]',
+    );
+    if (!secondInput)
+      throw new Error("Second pending text input did not render");
+    expect(secondInput.value).toBe("");
+    await act(async () => {
+      Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        "value",
+      )?.set?.call(secondInput, "Second label");
+      secondInput.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+
+    const send = document.querySelector<HTMLButtonElement>(
+      '[data-testid="draw-send"]',
+    );
+    await act(async () => send?.click());
+
+    expect(onSend).toHaveBeenCalledTimes(1);
+    expect(onSend.mock.calls[0][0]).toEqual([
+      expect.objectContaining({
+        type: "text",
+        text: "First label",
+        position: { x: 20, y: 20 },
+      }),
+      expect.objectContaining({
+        type: "text",
+        text: "Second label",
+        position: { x: 120, y: 60 },
+      }),
+    ]);
+  });
+
   it("submits sibling comment pins when there is no local drawing", async () => {
     const onSend = vi.fn();
     const rendered = await renderOverlay(onSend, 1);
@@ -343,4 +580,96 @@ describe("DrawOverlay pointer gesture robustness", () => {
       height: 100,
     });
   });
+
+  it("disables Send and swaps its label while a capture is in flight", async () => {
+    const onSend = vi.fn();
+    const rendered = await renderOverlay(onSend);
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 20, 20));
+      rendered.canvas.dispatchEvent(pointerEvent("pointermove", 40, 30));
+      rendered.canvas.dispatchEvent(pointerEvent("pointerup", 60, 40));
+    });
+    const send = () =>
+      document.querySelector<HTMLButtonElement>('[data-testid="draw-send"]');
+    expect(send()?.disabled).toBe(false);
+    expect(send()?.textContent).toContain("visualEditor.send");
+
+    await rendered.rerender(true, true);
+
+    expect(send()?.disabled).toBe(true);
+    expect(send()?.textContent).toContain("visualEditor.sendingDrawing");
+
+    await rendered.rerender(true, false);
+    expect(send()?.disabled).toBe(false);
+    expect(send()?.textContent).toContain("visualEditor.send");
+  });
+
+  it("ignores Enter while a submission is already in flight", async () => {
+    const onSend = vi.fn();
+    const rendered = await renderOverlay(onSend, 1);
+    cleanup = rendered.cleanup;
+    await rendered.rerender(true, true);
+
+    const instruction = document.querySelector<HTMLInputElement>(
+      'input[placeholder="visualEditor.tellAgentWhatToDo"]',
+    );
+    expect(instruction).not.toBeNull();
+    await act(async () => {
+      instruction?.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "Enter", bubbles: true }),
+      );
+    });
+
+    expect(onSend).not.toHaveBeenCalled();
+  });
+
+  it("freezes every annotation mutation while a submission is in flight", async () => {
+    const onSend = vi.fn();
+    const rendered = await renderOverlay(onSend);
+    cleanup = rendered.cleanup;
+
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 20, 20));
+      rendered.canvas.dispatchEvent(pointerEvent("pointerup", 60, 40));
+    });
+    await rendered.rerender(true, true);
+
+    await act(async () => {
+      rendered.canvas.dispatchEvent(pointerEvent("pointerdown", 100, 50, 2));
+      rendered.canvas.dispatchEvent(pointerEvent("pointerup", 140, 70, 2));
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-undo"]')
+        ?.click();
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-clear-all"]')
+        ?.click();
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-text-mode"]')
+        ?.click();
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-exit"]')
+        ?.click();
+    });
+
+    expect(rendered.onClose).not.toHaveBeenCalled();
+    expect(onSend).not.toHaveBeenCalled();
+    expect(rendered.canvas.className).toContain("pointer-events-none");
+
+    await rendered.rerender(true, false);
+    await act(async () => {
+      document
+        .querySelector<HTMLButtonElement>('[data-testid="draw-send"]')
+        ?.click();
+    });
+
+    expect(onSend).toHaveBeenCalledTimes(1);
+    expect(onSend.mock.calls[0][0]).toEqual([
+      expect.objectContaining({
+        type: "path",
+        pathData: "M20.0,20.0 L60.0,40.0",
+      }),
+    ]);
+  });
 });
diff --git a/templates/design/app/components/visual-editor/DrawOverlay.tsx b/templates/design/app/components/visual-editor/DrawOverlay.tsx
index 5bf303e065..193f36b6a0 100644
--- a/templates/design/app/components/visual-editor/DrawOverlay.tsx
+++ b/templates/design/app/components/visual-editor/DrawOverlay.tsx
@@ -3,6 +3,7 @@ import {
   IconEraser,
   IconArrowBackUp,
   IconArrowForwardUp,
+  IconLoader2,
   IconSend,
   IconCursorText,
   IconX,
@@ -12,6 +13,7 @@ import {
   useRef,
   useCallback,
   useEffect,
+  useLayoutEffect,
   type ReactNode,
 } from "react";
 import { createPortal } from "react-dom";
@@ -69,6 +71,42 @@ interface DrawOverlayProps {
   ) => void;
   /** Called when the user cancels / closes the draw mode */
   onClose: () => void;
+  /**
+   * True while the caller is capturing/compositing/uploading the annotated
+   * screenshot for a just-submitted drawing (see the design app's
+   * design-canvas/annotation-snapshot.ts). Disables Send and swaps its icon
+   * for a spinner so a slow capture can't be triggered twice from the same
+   * drawing. The entire overlay becomes inert while true so edits made after
+   * the submitted snapshot cannot be erased when that submission is later
+   * confirmed and the caller clears the batch.
+   */
+  sending?: boolean;
+  /**
+   * Bump this (e.g. a counter) exactly when the caller wants to discard the
+   * current strokes/text annotations — after `onClose` or a confirmed Send.
+   * Strokes/text are intentionally NOT cleared merely because `visible`
+   * turns false: `visible` can toggle off for reasons that have nothing to
+   * do with the user wanting to discard their work (switching tools, views,
+   * or side panels), and doing so silently would destroy annotations the
+   * user never got a chance to send. Only an in-progress (uncommitted)
+   * gesture is reset on hide; a pending text label is committed so its typed
+   * content survives.
+   */
+  clearSignal?: number;
+  /**
+   * Identity of the canvas this annotation batch belongs to. When the host
+   * reuses one DrawOverlay instance for a different screen, the old batch is
+   * cleared with a warning instead of being silently reinterpreted against
+   * the new screen's pixels and submitted with the wrong screenshot.
+   */
+  scopeKey?: string;
+  /**
+   * Keep the canvas DOM/bitmap alive while hidden. Use for the one active
+   * editor overlay whose work must survive mode/view toggles; leave false for
+   * large preview grids so every dormant screen does not allocate a canvas
+   * and ResizeObserver.
+   */
+  retainSurfaceWhenHidden?: boolean;
 }
 
 const PRESET_COLORS = [
@@ -111,6 +149,18 @@ interface PendingTextInput {
   /** Fractional y (0..1) of the visual rect. */
   yFrac: number;
   value: string;
+  /**
+   * Monotonic generation id. A click that opens a new pending text box while
+   * an earlier one is still focused fires pointerdown (which replaces the
+   * ref synchronously) before the outgoing box's native `blur` event runs.
+   * Without this, that trailing blur reads the *new* (empty) pending input
+   * out of the ref and wipes it via `commitTextAnnotation`'s unconditional
+   * `setPendingTextInput(null)` before the user can type anything. Callers
+   * pass the generation captured at their own render so a stale blur/Enter/
+   * Escape from a since-replaced box is a no-op instead of clobbering the
+   * newer one.
+   */
+  generation: number;
 }
 
 /**
@@ -200,6 +250,10 @@ export function DrawOverlay({
   zoom = 100,
   onSend,
   onClose,
+  sending = false,
+  clearSignal,
+  scopeKey,
+  retainSurfaceWhenHidden = false,
 }: DrawOverlayProps) {
   const t = useT();
   const containerRef = useRef<HTMLDivElement>(null);
@@ -227,12 +281,14 @@ export function DrawOverlay({
   const [textMode, setTextMode] = useState(false);
   const [textInput, setTextInput] = useState<PendingTextInput | null>(null);
   const textInputStateRef = useRef<PendingTextInput | null>(null);
+  const textInputGenerationRef = useRef(0);
   const textInputRef = useRef<HTMLInputElement>(null);
   // Escape cancels the pending text annotation, but unmounting the input also
   // fires its blur handler, which would commit the very annotation the user
   // just cancelled. This flag lets the blur handler skip that commit.
   const cancelingTextRef = useRef(false);
   const [instruction, setInstruction] = useState("");
+  const instructionRef = useRef("");
   const drawing = useRef(false);
   const canvasSizeRef = useRef({ w: 0, h: 0 });
   // Resize tick: bumped by ResizeObserver so the redraw effect re-runs when
@@ -241,6 +297,36 @@ export function DrawOverlay({
 
   const scale = Math.max(zoom / 100, 0.01);
 
+  // A host can still unmount the active editor entirely (route/design close,
+  // or focused canvas teardown) rather than merely hiding this component.
+  // Losing unsent work in that teardown must never be silent. Normal
+  // overview/focused visibility changes retain their active surface and do
+  // not hit this cleanup; only a real component unmount does.
+  useEffect(() => {
+    return () => {
+      // A true unmount never runs the `!visible` effect above (the prop
+      // never transitions — the component is simply gone), so a still-open
+      // pending text box never gets its usual commit-on-hide chance. Count
+      // it here too, or a label the user was mid-typing would vanish
+      // without even counting toward the warning.
+      const pendingText = textInputStateRef.current?.value.trim();
+      const discardedCount =
+        strokesRef.current.length +
+        textAnnotationsRef.current.length +
+        (pendingText ? 1 : 0) +
+        (instructionRef.current.trim() ? 1 : 0);
+      if (discardedCount > 0) {
+        toast(
+          t("visualEditor.annotationsDiscardedOnViewChange", {
+            count: discardedCount,
+          }),
+        );
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- must only run
+    // its cleanup on actual unmount, not on every `t`/locale change.
+  }, []);
+
   const cancelScheduledStrokeFrame = useCallback(() => {
     if (currentStrokeFrameRef.current === null) return;
     window.cancelAnimationFrame(currentStrokeFrameRef.current);
@@ -287,22 +373,35 @@ export function DrawOverlay({
     [],
   );
 
-  // Clear all state on hide so the next open starts fresh.
+  const clearAnnotationState = useCallback(() => {
+    resetActiveStroke();
+    strokesRef.current = [];
+    textAnnotationsRef.current = [];
+    setStrokes([]);
+    setTextAnnotations([]);
+    setRedoStack([]);
+    setPendingTextInput(null);
+    setTextMode(false);
+    instructionRef.current = "";
+    setInstruction("");
+    cancelingTextRef.current = false;
+    lastCreatedAtRef.current = 0;
+    textInputGenerationRef.current = 0;
+  }, [resetActiveStroke, setPendingTextInput]);
+
+  // Hiding ends whatever the user was mid-gesture on, but must NOT discard
+  // already-committed strokes/text: `visible` can turn false for reasons
+  // that have nothing to do with the user wanting to abandon their
+  // annotations (switching tools, views, or side panels). Only reset the
+  // transient in-flight state here — the committed `strokes`/
+  // `textAnnotations` arrays are cleared exclusively by `clearSignal` below.
   useEffect(() => {
     if (!visible) {
       resetActiveStroke();
-      strokesRef.current = [];
-      textAnnotationsRef.current = [];
-      setStrokes([]);
-      setTextAnnotations([]);
-      setRedoStack([]);
-      setPendingTextInput(null);
       setTextMode(false);
-      setInstruction("");
       cancelingTextRef.current = false;
-      lastCreatedAtRef.current = 0;
     }
-  }, [resetActiveStroke, setPendingTextInput, visible]);
+  }, [resetActiveStroke, visible]);
 
   // Comment-pin mode can temporarily leave the toolbar visible while making
   // the drawing surface inert. Never retain a half-finished gesture across
@@ -320,26 +419,34 @@ export function DrawOverlay({
 
   const shouldFocusTextInput = textInput !== null;
   useEffect(() => {
-    if (!shouldFocusTextInput) return;
+    if (!visible || !shouldFocusTextInput) return;
     const id = window.requestAnimationFrame(() => {
       textInputRef.current?.focus();
     });
     return () => window.cancelAnimationFrame(id);
-  }, [shouldFocusTextInput]);
+  }, [shouldFocusTextInput, visible]);
 
-  // ResizeObserver: bump resizeTick whenever the canvas changes CSS size so
-  // the redraw effect re-runs and the backing store is resized correctly.
+  // Retained editor surfaces keep their canvas mounted while hidden, so a
+  // hidden-first host installs its observer and the bitmap does not flash
+  // blank when the user re-enters annotate mode. Non-retained preview-grid
+  // overlays attach only while visible to avoid idle canvas/observer cost.
   useEffect(() => {
+    if (!visible && !retainSurfaceWhenHidden) return;
     const canvas = canvasRef.current;
     if (!canvas) return;
     if (typeof ResizeObserver === "undefined") return;
     const ro = new ResizeObserver(() => setResizeTick((t) => t + 1));
     ro.observe(canvas);
     return () => ro.disconnect();
-  }, []);
-
-  // Redraw canvas whenever strokes change or the canvas is resized.
-  useEffect(() => {
+  }, [retainSurfaceWhenHidden, visible]);
+
+  // Redraw before paint whenever strokes change, the canvas is resized, or a
+  // preserved batch becomes visible again. The visible dependency is
+  // intentional even though the DOM stays mounted: browsers may discard a
+  // hidden canvas backing store under memory pressure, and re-entry must
+  // never expose a blank frame before the next pointer event.
+  useLayoutEffect(() => {
+    if (!visible) return;
     const canvas = canvasRef.current;
     if (!canvas) return;
     const ctx = canvas.getContext("2d");
@@ -387,22 +494,109 @@ export function DrawOverlay({
     // which changes getBoundingClientRect() without firing ResizeObserver — the
     // effect must re-run on zoom change to redraw the fraction-based strokes at
     // the new visual size.
-  }, [strokes, currentStroke, color, lineWidth, resizeTick, zoom]);
+  }, [strokes, currentStroke, color, lineWidth, resizeTick, visible, zoom]);
+
+  /**
+   * Commits the pending text annotation (if any) and clears the pending
+   * input. `expectedGeneration`, when passed, guards against a stale
+   * blur/Enter/Escape belonging to a pending text box that has since been
+   * replaced or already cleared — see `PendingTextInput.generation`. Called
+   * with no argument to force-commit whatever is currently pending (e.g.
+   * before opening a new text box, or right before Send).
+   */
+  const commitTextAnnotation = useCallback(
+    (expectedGeneration?: number) => {
+      const pendingText = textInputStateRef.current;
+      if (
+        !pendingText ||
+        (expectedGeneration !== undefined &&
+          pendingText.generation !== expectedGeneration)
+      ) {
+        return;
+      }
+      // Clear the authoritative pending value first. Enter, blur, and Send can
+      // all occur in the same browser turn; any later handler becomes a no-op
+      // instead of duplicating the label.
+      setPendingTextInput(null);
+      if (!pendingText.value.trim()) return;
+
+      const ann: DrawAnnotation = {
+        id: crypto.randomUUID(),
+        type: "text",
+        text: pendingText.value.trim(),
+        // Store fractional position so the label stays anchored across zoom changes.
+        position: { x: pendingText.xFrac, y: pendingText.yFrac },
+        color,
+        lineWidth,
+        createdAt: nextCreatedAt(),
+      };
+      const nextTexts = [...textAnnotationsRef.current, ann];
+      textAnnotationsRef.current = nextTexts;
+      setTextAnnotations(nextTexts);
+      // A new text annotation also clears the redo stack.
+      setRedoStack([]);
+    },
+    [color, lineWidth, nextCreatedAt, setPendingTextInput],
+  );
+
+  // Hiding removes the pending-text input from interaction. Commit whatever
+  // was typed explicitly so a still-open label survives an unrelated exit
+  // instead of relying on incidental native blur ordering.
+  useEffect(() => {
+    if (!visible) commitTextAnnotation();
+  }, [visible, commitTextAnnotation]);
+
+  // The explicit-discard path: the caller bumps `clearSignal` exactly when
+  // the user deliberately closes the overlay (X/Escape) or a Send is
+  // confirmed delivered. A scope change below is the only other reset path,
+  // guarding against submitting one screen's geometry against another.
+  const lastClearSignalRef = useRef(clearSignal);
+  useLayoutEffect(() => {
+    if (clearSignal === lastClearSignalRef.current) return;
+    lastClearSignalRef.current = clearSignal;
+    clearAnnotationState();
+  }, [clearAnnotationState, clearSignal]);
+
+  const lastScopeKeyRef = useRef(scopeKey);
+  useLayoutEffect(() => {
+    if (scopeKey === lastScopeKeyRef.current) return;
+    lastScopeKeyRef.current = scopeKey;
+    const pendingText = textInputStateRef.current?.value.trim();
+    const discardedCount =
+      strokesRef.current.length +
+      textAnnotationsRef.current.length +
+      (pendingText ? 1 : 0) +
+      (instructionRef.current.trim() ? 1 : 0);
+    if (discardedCount > 0) {
+      toast(
+        t("visualEditor.annotationsDiscardedOnViewChange", {
+          count: discardedCount,
+        }),
+      );
+    }
+    clearAnnotationState();
+  }, [clearAnnotationState, scopeKey, t]);
 
   const handlePointerDown = useCallback(
     (e: React.PointerEvent) => {
       const rect = canvasRef.current?.getBoundingClientRect();
       if (!rect || rect.width <= 0 || rect.height <= 0) return;
-      if (!canvasInteractive || drawing.current) return;
+      if (!canvasInteractive || sending || drawing.current) return;
       if (e.pointerType === "mouse" && e.button !== 0) return;
 
       if (textMode) {
         e.preventDefault();
         cancelingTextRef.current = false;
+        // Commit whatever text box was still open (using the current ref,
+        // which still holds the outgoing box at this point) before replacing
+        // it, so clicking a new spot never silently drops the previous label.
+        commitTextAnnotation();
+        textInputGenerationRef.current += 1;
         setPendingTextInput({
           xFrac: (e.clientX - rect.left) / rect.width,
           yFrac: (e.clientY - rect.top) / rect.height,
           value: "",
+          generation: textInputGenerationRef.current,
         });
         return;
       }
@@ -422,7 +616,15 @@ export function DrawOverlay({
         // gesture. The pointer-id guard still prevents cross-pointer mixing.
       }
     },
-    [canvasInteractive, color, lineWidth, setPendingTextInput, textMode],
+    [
+      canvasInteractive,
+      color,
+      commitTextAnnotation,
+      lineWidth,
+      sending,
+      setPendingTextInput,
+      textMode,
+    ],
   );
 
   const handlePointerMove = useCallback(
@@ -529,6 +731,7 @@ export function DrawOverlay({
    * creation order and pushes it onto the unified redo stack.
    */
   const undo = () => {
+    if (sending) return;
     const currentStrokes = strokesRef.current;
     const currentTexts = textAnnotationsRef.current;
     const lastStroke =
@@ -558,6 +761,7 @@ export function DrawOverlay({
   };
 
   const redo = () => {
+    if (sending) return;
     setRedoStack((stack) => {
       if (stack.length === 0) return stack;
       const top = stack[stack.length - 1];
@@ -581,6 +785,7 @@ export function DrawOverlay({
   };
 
   const clear = () => {
+    if (sending) return;
     if (strokes.length === 0 && textAnnotations.length === 0) return;
     const prevStrokes = strokesRef.current;
     const prevTexts = textAnnotationsRef.current;
@@ -609,32 +814,8 @@ export function DrawOverlay({
     });
   };
 
-  const commitTextAnnotation = () => {
-    const pendingText = textInputStateRef.current;
-    // Clear the authoritative pending value first. Enter, blur, and Send can
-    // all occur in the same browser turn; any later handler becomes a no-op
-    // instead of duplicating the label.
-    setPendingTextInput(null);
-    if (!pendingText || !pendingText.value.trim()) return;
-
-    const ann: DrawAnnotation = {
-      id: crypto.randomUUID(),
-      type: "text",
-      text: pendingText.value.trim(),
-      // Store fractional position so the label stays anchored across zoom changes.
-      position: { x: pendingText.xFrac, y: pendingText.yFrac },
-      color,
-      lineWidth,
-      createdAt: nextCreatedAt(),
-    };
-    const nextTexts = [...textAnnotationsRef.current, ann];
-    textAnnotationsRef.current = nextTexts;
-    setTextAnnotations(nextTexts);
-    // A new text annotation also clears the redo stack.
-    setRedoStack([]);
-  };
-
   const send = () => {
+    if (sending) return;
     const canvas = canvasRef.current;
     if (!canvas) return;
     // A focused text label normally commits on blur before the Send click, but
@@ -680,7 +861,7 @@ export function DrawOverlay({
     });
   };
 
-  if (!visible) return null;
+  if (!visible && !retainSurfaceWhenHidden) return null;
 
   const hasContent =
     strokes.length > 0 ||
@@ -706,7 +887,10 @@ export function DrawOverlay({
                 type="button"
                 aria-label={preset.label}
                 data-testid={`draw-color-${preset.label.toLowerCase()}`}
-                onClick={() => setColor(preset.color)}
+                onClick={() => {
+                  if (!sending) setColor(preset.color);
+                }}
+                disabled={sending}
                 className={cn(
                   "h-5 w-5 cursor-pointer rounded-full",
                   color === preset.color
@@ -732,7 +916,10 @@ export function DrawOverlay({
                 type="button"
                 aria-label={lw.label}
                 data-testid={`draw-line-width-${lw.label.toLowerCase()}`}
-                onClick={() => setLineWidth(lw.value)}
+                onClick={() => {
+                  if (!sending) setLineWidth(lw.value);
+                }}
+                disabled={sending}
                 className={cn(
                   "flex h-6 w-6 cursor-pointer items-center justify-center rounded",
                   lineWidth === lw.value
@@ -760,7 +947,10 @@ export function DrawOverlay({
             type="button"
             aria-label={t("visualEditor.typeAnywhereOnCanvas")}
             data-testid="draw-text-mode"
-            onClick={() => setTextMode(!textMode)}
+            onClick={() => {
+              if (!sending) setTextMode(!textMode);
+            }}
+            disabled={sending}
             className={cn(
               "flex h-6 w-6 cursor-pointer items-center justify-center rounded",
               textMode
@@ -784,7 +974,7 @@ export function DrawOverlay({
             aria-label={t("visualEditor.undoStroke")}
             data-testid="draw-undo"
             onClick={undo}
-            disabled={!canUndo}
+            disabled={!canUndo || sending}
             className="flex h-6 w-6 cursor-pointer items-center justify-center rounded text-muted-foreground hover:text-foreground disabled:cursor-default disabled:opacity-30"
           >
             <IconArrowBackUp className="h-3.5 w-3.5" />
@@ -801,7 +991,7 @@ export function DrawOverlay({
             aria-label={t("visualEditor.redoStroke")}
             data-testid="draw-redo"
             onClick={redo}
-            disabled={!canRedo}
+            disabled={!canRedo || sending}
             className="flex h-6 w-6 cursor-pointer items-center justify-center rounded text-muted-foreground hover:text-foreground disabled:cursor-default disabled:opacity-30"
           >
             <IconArrowForwardUp className="h-3.5 w-3.5" />
@@ -818,7 +1008,9 @@ export function DrawOverlay({
             aria-label={t("visualEditor.clearAll")}
             data-testid="draw-clear-all"
             onClick={clear}
-            disabled={strokes.length === 0 && textAnnotations.length === 0}
+            disabled={
+              sending || (strokes.length === 0 && textAnnotations.length === 0)
+            }
             className="flex h-6 w-6 cursor-pointer items-center justify-center rounded text-muted-foreground hover:text-foreground disabled:cursor-default disabled:opacity-30"
           >
             <IconEraser className="h-3.5 w-3.5" />
@@ -832,12 +1024,17 @@ export function DrawOverlay({
       {/* Instruction input */}
       <Input
         value={instruction}
-        onChange={(e) => setInstruction(e.target.value)}
+        onChange={(e) => {
+          if (sending) return;
+          instructionRef.current = e.target.value;
+          setInstruction(e.target.value);
+        }}
         onKeyDown={(e) => {
-          if (e.key === "Enter" && hasContent) send();
+          if (e.key === "Enter" && hasContent && !sending) send();
           if (e.key === "Escape") onClose();
         }}
         placeholder={t("visualEditor.tellAgentWhatToDo")}
+        disabled={sending}
         className="h-7 w-56 border-border bg-background text-xs"
       />
 
@@ -847,10 +1044,14 @@ export function DrawOverlay({
         data-testid="draw-send"
         className="h-7 gap-1 px-3 !text-[11px] cursor-pointer"
         onClick={send}
-        disabled={!hasContent}
+        disabled={!hasContent || sending}
       >
-        <IconSend className="h-3 w-3" />
-        {t("visualEditor.send")}
+        {sending ? (
+          <IconLoader2 className="h-3 w-3 animate-spin" />
+        ) : (
+          <IconSend className="h-3 w-3" />
+        )}
+        {sending ? t("visualEditor.sendingDrawing") : t("visualEditor.send")}
       </Button>
 
       {/* Close */}
@@ -861,6 +1062,7 @@ export function DrawOverlay({
             aria-label={t("visualEditor.exitDrawMode")}
             data-testid="draw-exit"
             onClick={onClose}
+            disabled={sending}
             className="flex h-6 w-6 cursor-pointer items-center justify-center rounded text-muted-foreground hover:text-foreground"
           >
             <IconX className="h-3.5 w-3.5" />
@@ -875,9 +1077,13 @@ export function DrawOverlay({
     <div
       ref={containerRef}
       data-draw-overlay
+      aria-hidden={!visible}
       className={cn(
         "absolute inset-0 z-[100]",
-        canvasInteractive ? "pointer-events-auto" : "pointer-events-none",
+        visible ? "visible" : "invisible pointer-events-none",
+        canvasInteractive && !sending
+          ? "pointer-events-auto"
+          : "pointer-events-none",
       )}
     >
       {/* Drawing canvas */}
@@ -887,7 +1093,7 @@ export function DrawOverlay({
         className={cn(
           "absolute inset-0 h-full w-full touch-none",
           textMode ? "cursor-text" : "cursor-crosshair",
-          !canvasInteractive && "pointer-events-none",
+          (!canvasInteractive || sending) && "pointer-events-none",
         )}
         onPointerDown={handlePointerDown}
         onPointerMove={handlePointerMove}
@@ -946,6 +1152,7 @@ export function DrawOverlay({
                 ref={textInputRef}
                 value={textInput.value}
                 onChange={(e) =>
+                  !sending &&
                   setPendingTextInput((prev) =>
                     prev ? { ...prev, value: e.target.value } : null,
                   )
@@ -957,7 +1164,11 @@ export function DrawOverlay({
                     cancelingTextRef.current = false;
                     return;
                   }
-                  commitTextAnnotation();
+                  // Pass this render's generation so a trailing blur that
+                  // arrives after pointerdown has already opened a *newer*
+                  // text box (see PendingTextInput.generation) is a no-op
+                  // instead of wiping the box the user just started typing.
+                  commitTextAnnotation(textInput.generation);
                 }}
                 onKeyDown={(e) => {
                   if (e.key === "Enter") {
@@ -965,7 +1176,7 @@ export function DrawOverlay({
                     // Committing unmounts the focused input, which can emit a
                     // blur event in the same turn. Skip that second commit.
                     cancelingTextRef.current = true;
-                    commitTextAnnotation();
+                    commitTextAnnotation(textInput.generation);
                   }
                   if (e.key === "Escape") {
                     cancelingTextRef.current = true;
@@ -973,6 +1184,7 @@ export function DrawOverlay({
                   }
                 }}
                 className="h-7 w-48 border-primary bg-background text-sm"
+                disabled={sending}
                 autoFocus
                 placeholder={t("visualEditor.typeAnnotationFancy")}
               />
@@ -980,7 +1192,7 @@ export function DrawOverlay({
           );
         })()}
 
-      <DrawToolbarPortal>{toolbar}</DrawToolbarPortal>
+      {visible ? <DrawToolbarPortal>{toolbar}</DrawToolbarPortal> : null}
     </div>
   );
 }
diff --git a/templates/design/app/hooks/use-question-flow.test.tsx b/templates/design/app/hooks/use-question-flow.test.tsx
new file mode 100644
index 0000000000..910c1b5cc0
--- /dev/null
+++ b/templates/design/app/hooks/use-question-flow.test.tsx
@@ -0,0 +1,130 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const coreClientMocks = vi.hoisted(() => ({
+  useGuidedQuestionFlow: vi.fn(),
+  formatGuidedAnswersForAgent: vi.fn((answers: Record<string, unknown>) =>
+    JSON.stringify(answers),
+  ),
+}));
+
+vi.mock("@agent-native/core/client", () => coreClientMocks);
+
+const agentChatMocks = vi.hoisted(() => ({
+  sendToDesignAgentChat: vi.fn(
+    (_opts: { message: string; tabId?: string; newTab?: boolean }) =>
+      "generated-tab-id",
+  ),
+}));
+
+vi.mock("@/lib/agent-chat", () => agentChatMocks);
+
+import { useQuestionFlow } from "./use-question-flow";
+
+let latestHook: ReturnType<typeof useQuestionFlow> | null = null;
+
+function Probe(props: {
+  designId?: string;
+  continuationTabId?: string | null;
+  onContinue?: (tabId: string) => void;
+}) {
+  latestHook = useQuestionFlow(props.designId, {
+    continuationTabId: props.continuationTabId,
+    onContinue: props.onContinue,
+  });
+  return null;
+}
+
+async function renderProbe(props: {
+  designId?: string;
+  continuationTabId?: string | null;
+  onContinue?: (tabId: string) => void;
+}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  await act(async () => {
+    root.render(<Probe {...props} />);
+  });
+  return {
+    async cleanup() {
+      await act(async () => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+describe("useQuestionFlow sendContinuation tab tracking", () => {
+  const clearMock = vi.fn();
+
+  beforeEach(() => {
+    clearMock.mockClear();
+    agentChatMocks.sendToDesignAgentChat.mockClear();
+    agentChatMocks.sendToDesignAgentChat.mockImplementation(
+      () => "generated-tab-id",
+    );
+    coreClientMocks.useGuidedQuestionFlow.mockReturnValue({
+      payload: null,
+      questions: null,
+      title: undefined,
+      description: undefined,
+      skipLabel: undefined,
+      submitLabel: undefined,
+      clear: clearMock,
+      // These are intentionally shadowed by useQuestionFlow's own
+      // handleSubmit/handleSkip — see the hook's inline comment.
+      handleSubmit: vi.fn(),
+      handleSkip: vi.fn(),
+    });
+  });
+
+  it("always requests newTab so the returned tabId matches the thread that actually receives the message, even with no prior continuation tab", async () => {
+    const onContinue = vi.fn();
+    const { cleanup } = await renderProbe({
+      designId: "design-1",
+      continuationTabId: null,
+      onContinue,
+    });
+
+    await act(async () => {
+      latestHook!.handleSubmit({ q1: "answer" });
+    });
+
+    expect(agentChatMocks.sendToDesignAgentChat).toHaveBeenCalledTimes(1);
+    const call = agentChatMocks.sendToDesignAgentChat.mock.calls[0]![0];
+    // Regression guard: without `newTab: true` here, the message would be
+    // posted to whichever tab is currently active while the caller is told
+    // a different, never-actually-used tabId — desyncing generation tracking
+    // (false "stopped, please retry" toasts; completion never detected).
+    expect(call.newTab).toBe(true);
+    expect(call.tabId).toBeUndefined();
+    expect(onContinue).toHaveBeenCalledWith("generated-tab-id");
+    expect(clearMock).toHaveBeenCalledTimes(1);
+
+    await cleanup();
+  });
+
+  it("reuses the tracked continuation tab id while still requesting newTab", async () => {
+    const onContinue = vi.fn();
+    const { cleanup } = await renderProbe({
+      designId: "design-1",
+      continuationTabId: "existing-tab",
+      onContinue,
+    });
+
+    await act(async () => {
+      latestHook!.handleSkip();
+    });
+
+    expect(agentChatMocks.sendToDesignAgentChat).toHaveBeenCalledTimes(1);
+    const call = agentChatMocks.sendToDesignAgentChat.mock.calls[0]![0];
+    expect(call.newTab).toBe(true);
+    expect(call.tabId).toBe("existing-tab");
+    expect(onContinue).toHaveBeenCalledWith("generated-tab-id");
+
+    await cleanup();
+  });
+});
diff --git a/templates/design/app/hooks/use-question-flow.ts b/templates/design/app/hooks/use-question-flow.ts
index 748a314364..12881017ed 100644
--- a/templates/design/app/hooks/use-question-flow.ts
+++ b/templates/design/app/hooks/use-question-flow.ts
@@ -54,13 +54,24 @@ export function useQuestionFlow(
 
   const sendContinuation = useCallback(
     (message: string, context?: string) => {
+      // Always request `newTab` (mirroring useAgentGenerating.submit's
+      // default). Without it, when there is no continuationTabId yet the
+      // message goes to whatever tab is currently active, but the id we
+      // return here would still be a freshly generated one that was never
+      // actually used — trackAgentGeneration/onContinue would then watch a
+      // tabId that never matches real chatRunning events, so the design
+      // "generating" UI silently desyncs (false "stopped, please retry"
+      // toasts, completion never detected). Passing tabId only when we have
+      // a continuationTabId still reuses that existing thread (addOptimistic
+      // thread is idempotent for known ids); omitting it lets a fresh id be
+      // generated and actually created, so the returned tabId is always the
+      // real destination thread.
       const tabId = sendToDesignAgentChat({
         message,
         context,
         submit: true,
-        ...(continuationTabId
-          ? { tabId: continuationTabId, newTab: true }
-          : {}),
+        newTab: true,
+        ...(continuationTabId ? { tabId: continuationTabId } : {}),
       });
       onContinue?.(tabId);
       flow.clear();
diff --git a/templates/design/app/hooks/useDesignHotkeys.test.tsx b/templates/design/app/hooks/useDesignHotkeys.test.tsx
index fec4bf6a65..2906319a0b 100644
--- a/templates/design/app/hooks/useDesignHotkeys.test.tsx
+++ b/templates/design/app/hooks/useDesignHotkeys.test.tsx
@@ -53,6 +53,7 @@ async function withHotkeys(
 function dispatchKey(
   key: string,
   init: KeyboardEventInit & { code?: string } = {},
+  target: EventTarget = window,
 ) {
   const event = new KeyboardEvent("keydown", {
     key,
@@ -60,7 +61,7 @@ function dispatchKey(
     cancelable: true,
     ...init,
   });
-  window.dispatchEvent(event);
+  target.dispatchEvent(event);
   return event;
 }
 
@@ -85,6 +86,42 @@ async function withNavigatorPlatform(
 }
 
 describe("useDesignHotkeys — current Figma tool bindings", () => {
+  it("opens keyboard shortcuts with literal Ctrl+Shift+?", async () => {
+    const onShowKeyboardShortcuts = vi.fn();
+    await withHotkeys({ onShowKeyboardShortcuts }, () => {
+      dispatchKey("?", {
+        code: "Slash",
+        ctrlKey: true,
+        shiftKey: true,
+      });
+      dispatchKey("?", {
+        code: "Slash",
+        metaKey: true,
+        shiftKey: true,
+      });
+    });
+    expect(onShowKeyboardShortcuts).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps shortcut help global without routing editing keys from editable targets", async () => {
+    const onShowKeyboardShortcuts = vi.fn();
+    const onTextTool = vi.fn();
+    const input = document.createElement("input");
+    document.body.append(input);
+    await withHotkeys({ onShowKeyboardShortcuts, onTextTool }, () => {
+      const helpEvent = dispatchKey(
+        "?",
+        { code: "Slash", ctrlKey: true, shiftKey: true },
+        input,
+      );
+      dispatchKey("t", {}, input);
+      expect(helpEvent.defaultPrevented).toBe(true);
+    });
+    expect(onShowKeyboardShortcuts).toHaveBeenCalledTimes(1);
+    expect(onTextTool).not.toHaveBeenCalled();
+    input.remove();
+  });
+
   it("Y arms the annotation/draw tool", async () => {
     const onDrawTool = vi.fn();
     const onToolChange = vi.fn();
@@ -191,6 +228,25 @@ describe("useDesignHotkeys — Figma selection and frame traversal", () => {
     expect(onToggleUi).not.toHaveBeenCalled();
   });
 
+  it("uses Enter to drill in and Shift+Enter as its select-parent sibling", async () => {
+    const onEnter = vi.fn();
+    const onSelectParent = vi.fn();
+    await withHotkeys({ onEnter, onSelectParent }, () => {
+      dispatchKey("Enter");
+      dispatchKey("Enter", { shiftKey: true });
+    });
+    expect(onEnter).toHaveBeenCalledTimes(1);
+    expect(onSelectParent).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to onEnter for Shift+Enter when onSelectParent isn't wired", async () => {
+    const onEnter = vi.fn();
+    await withHotkeys({ onEnter }, () => {
+      dispatchKey("Enter", { shiftKey: true });
+    });
+    expect(onEnter).toHaveBeenCalledTimes(1);
+  });
+
   it("does not turn inverse/matching-selection shortcuts into Select all", async () => {
     const onSelectAll = vi.fn();
     await withHotkeys({ onSelectAll }, () => {
@@ -297,6 +353,77 @@ describe("useDesignHotkeys — selection toggles (Cmd+Shift+H / Cmd+Shift+L)", (
   });
 });
 
+describe("useDesignHotkeys — typography toggles (Cmd+U / Cmd+Shift+X)", () => {
+  it("fires onToggleUnderline for Cmd+U", async () => {
+    const onToggleUnderline = vi.fn();
+    await withHotkeys({ onToggleUnderline }, () => {
+      dispatchKey("u", { metaKey: true });
+    });
+    expect(onToggleUnderline).toHaveBeenCalledTimes(1);
+  });
+
+  it("fires onToggleStrikethrough for Cmd+Shift+X and does not also fire onCut", async () => {
+    const onToggleStrikethrough = vi.fn();
+    const onCut = vi.fn();
+    await withHotkeys({ onToggleStrikethrough, onCut }, () => {
+      dispatchKey("x", { metaKey: true, shiftKey: true });
+    });
+    expect(onToggleStrikethrough).toHaveBeenCalledTimes(1);
+    expect(onCut).not.toHaveBeenCalled();
+  });
+
+  it("plain Cmd+X still cuts and does not fire onToggleStrikethrough", async () => {
+    const onToggleStrikethrough = vi.fn();
+    const onCut = vi.fn();
+    await withHotkeys({ onToggleStrikethrough, onCut }, () => {
+      dispatchKey("x", { metaKey: true });
+    });
+    expect(onCut).toHaveBeenCalledTimes(1);
+    expect(onToggleStrikethrough).not.toHaveBeenCalled();
+  });
+
+  it("Shift+X (no primary) still swaps fill/stroke, not strikethrough", async () => {
+    const onToggleStrikethrough = vi.fn();
+    const onSwapFillStroke = vi.fn();
+    await withHotkeys({ onToggleStrikethrough, onSwapFillStroke }, () => {
+      dispatchKey("x", { shiftKey: true });
+    });
+    expect(onSwapFillStroke).toHaveBeenCalledTimes(1);
+    expect(onToggleStrikethrough).not.toHaveBeenCalled();
+  });
+
+  it("does not fire underline/strikethrough hotkeys inside editable targets", async () => {
+    const onToggleUnderline = vi.fn();
+    const onToggleStrikethrough = vi.fn();
+    const input = document.createElement("input");
+    document.body.append(input);
+    input.focus();
+    try {
+      await withHotkeys({ onToggleUnderline, onToggleStrikethrough }, () => {
+        const event = new KeyboardEvent("keydown", {
+          key: "u",
+          metaKey: true,
+          bubbles: true,
+          cancelable: true,
+        });
+        input.dispatchEvent(event);
+        const event2 = new KeyboardEvent("keydown", {
+          key: "x",
+          metaKey: true,
+          shiftKey: true,
+          bubbles: true,
+          cancelable: true,
+        });
+        input.dispatchEvent(event2);
+      });
+      expect(onToggleUnderline).not.toHaveBeenCalled();
+      expect(onToggleStrikethrough).not.toHaveBeenCalled();
+    } finally {
+      input.remove();
+    }
+  });
+});
+
 describe("useDesignHotkeys — group/ungroup/frame (Cmd+G family)", () => {
   it("Cmd+G groups", async () => {
     const onGroup = vi.fn();
@@ -316,13 +443,13 @@ describe("useDesignHotkeys — group/ungroup/frame (Cmd+G family)", () => {
     expect(onFrameSelection).not.toHaveBeenCalled();
   });
 
-  it("does not retain the historical Shift+Cmd+G ungroup binding", async () => {
+  it("Shift+Cmd+G also ungroups (BUG-UNGROUP-HOTKEY: matches the context-menu Ungroup action, which is dead without this)", async () => {
     const onUngroup = vi.fn();
     const onGroup = vi.fn();
     await withHotkeys({ onUngroup, onGroup }, () => {
       dispatchKey("g", { metaKey: true, shiftKey: true });
     });
-    expect(onUngroup).not.toHaveBeenCalled();
+    expect(onUngroup).toHaveBeenCalledTimes(1);
     expect(onGroup).not.toHaveBeenCalled();
   });
 
@@ -472,6 +599,16 @@ describe("useDesignHotkeys — selection alignment (Alt+A/D/W/S/H/V)", () => {
     expect(onFrameSelection).toHaveBeenCalledTimes(1);
     expect(onAlignSelection).not.toHaveBeenCalled();
   });
+
+  it("Cmd+Alt+B detaches the selected instance and does not fire align", async () => {
+    const onAlignSelection = vi.fn();
+    const onDetachInstance = vi.fn();
+    await withHotkeys({ onAlignSelection, onDetachInstance }, () => {
+      dispatchKey("b", { metaKey: true, altKey: true });
+    });
+    expect(onDetachInstance).toHaveBeenCalledTimes(1);
+    expect(onAlignSelection).not.toHaveBeenCalled();
+  });
 });
 
 describe("useDesignHotkeys — distribute (Ctrl+Alt+H/V) and Tidy up (Ctrl+Alt+T)", () => {
diff --git a/templates/design/app/hooks/useDesignHotkeys.ts b/templates/design/app/hooks/useDesignHotkeys.ts
index 58f0a04c01..726d1b213b 100644
--- a/templates/design/app/hooks/useDesignHotkeys.ts
+++ b/templates/design/app/hooks/useDesignHotkeys.ts
@@ -144,6 +144,11 @@ export interface UseDesignHotkeysProps {
   onZoomToSelection?: DesignHotkeyHandler;
   /** Figma's Cmd+Alt+K — create component from the current selection. */
   onCreateComponent?: DesignHotkeyHandler;
+  /**
+   * Figma's Cmd+Alt+B — Detach instance: convert the selected component
+   * instance into a plain, unlinked element.
+   */
+  onDetachInstance?: DesignHotkeyHandler;
   /**
    * Figma's plain digit 1-9 / 0 — set selection opacity (10-90%, 0 = 100%).
    * Only fires when a layer is selected (caller decides via presence of the
@@ -156,6 +161,12 @@ export interface UseDesignHotkeysProps {
   onToggleHidden?: DesignHotkeyHandler;
   /** Figma's Cmd+Shift+L — toggle lock/unlock for the current selection. */
   onToggleLocked?: DesignHotkeyHandler;
+  /** Figma's Cmd+U — toggle underline on the current text selection. */
+  onToggleUnderline?: DesignHotkeyHandler;
+  /** Figma's Cmd+Shift+X — toggle strikethrough on the current text
+   *  selection. Checked before plain Cmd+X (cut) so the shift-held combo
+   *  doesn't fall through to cut. */
+  onToggleStrikethrough?: DesignHotkeyHandler;
   /** Figma's Shift+H — flip the current selection horizontally. */
   onFlipHorizontal?: DesignHotkeyHandler;
   /** Figma's Shift+V — flip the current selection vertically. */
@@ -197,6 +208,8 @@ export interface UseDesignHotkeysProps {
   onToggleUi?: DesignHotkeyHandler;
   /** Figma's Shift+C — toggle Show/Hide comments (comment pins). */
   onToggleComments?: DesignHotkeyHandler;
+  /** Figma's Ctrl+Shift+? — open the keyboard-shortcuts reference panel. */
+  onShowKeyboardShortcuts?: DesignHotkeyHandler;
 }
 
 const TOOL_SHORTCUTS: Record<
@@ -269,6 +282,15 @@ export function isDesignHotkeyEditableTarget(target: EventTarget | null) {
   return tagName === "input" || tagName === "textarea" || tagName === "select";
 }
 
+export function isShowKeyboardShortcutsHotkey(event: KeyboardEvent) {
+  return (
+    (event.ctrlKey || event.metaKey) &&
+    event.shiftKey &&
+    !event.altKey &&
+    normalizedKey(event) === "?"
+  );
+}
+
 function isFocusableChromeTarget(target: EventTarget | null) {
   if (!target || typeof Element === "undefined") return false;
   if (!(target instanceof Element)) return false;
@@ -317,7 +339,8 @@ export function useDesignHotkeys(props: UseDesignHotkeysProps) {
         return;
       if (
         current.ignoreEditableTargets !== false &&
-        isDesignHotkeyEditableTarget(event.target)
+        isDesignHotkeyEditableTarget(event.target) &&
+        !isShowKeyboardShortcutsHotkey(event)
       ) {
         return;
       }
@@ -336,7 +359,7 @@ export function useDesignHotkeys(props: UseDesignHotkeysProps) {
   }, [props.capture, props.enabled, props.target]);
 }
 
-function handleDesignHotkey(
+export function handleDesignHotkey(
   event: KeyboardEvent,
   props: UseDesignHotkeysProps,
 ) {
@@ -398,6 +421,12 @@ function handleDesignHotkey(
     return true;
   };
 
+  // Keep shortcut help global, including while an inspector field or code
+  // editor owns focus. No other editing shortcut bypasses the editable guard.
+  if (isShowKeyboardShortcutsHotkey(event)) {
+    return run(props.onShowKeyboardShortcuts);
+  }
+
   if (!primary && !event.altKey && event.shiftKey) {
     // H1: shift+key variant (e.g. Shift+L → arrow tool) takes priority over
     // the base binding for the same key while shift is held.
@@ -425,7 +454,18 @@ function handleDesignHotkey(
   }
 
   if (event.key === "Escape") return run(props.onEscape);
-  if (event.key === "Enter") return run(props.onEnter);
+  if (event.key === "Enter") {
+    // Figma: Enter drills into the selection (selects its first child /
+    // begins text editing); Shift+Enter is its sibling — select the
+    // selection's PARENT. Checked before the plain onEnter fallback so
+    // Shift+Enter doesn't just drill in again; falls back to onEnter when
+    // onSelectParent isn't wired so callers that haven't adopted it yet see
+    // unchanged behavior.
+    if (event.shiftKey && props.onSelectParent) {
+      return run(props.onSelectParent);
+    }
+    return run(props.onEnter);
+  }
   if (!primary && !event.altKey && !event.shiftKey && key === "\\") {
     return run(props.onSelectParent);
   }
@@ -450,9 +490,9 @@ function handleDesignHotkey(
     return run(props.onDelete);
   }
 
-  // Current Figma: Cmd+Backspace ungroups. This intentionally differs from
-  // the historical Shift+Cmd+G binding and must be checked after plain
-  // Backspace deletion has been ruled out.
+  // Current Figma: Cmd+Backspace ungroups. Checked after plain Backspace
+  // deletion has been ruled out. Shift+Cmd+G (below, in the Cmd+G family) is
+  // a second, equally-supported binding for the same onUngroup handler.
   if (primary && !event.altKey && !event.shiftKey && key === "Backspace") {
     return run(props.onUngroup);
   }
@@ -476,7 +516,16 @@ function handleDesignHotkey(
   if (primary && !event.altKey && !event.shiftKey && key === "a") {
     return run(props.onSelectAll);
   }
+  // Figma's Cmd+Shift+X — toggle strikethrough. Must be checked before plain
+  // Cmd+X (cut) below, since that check doesn't itself gate on shiftKey.
+  if (primary && event.shiftKey && key === "x") {
+    return run(props.onToggleStrikethrough);
+  }
   if (primary && key === "x") return run(props.onCut);
+  // Figma's Cmd+U — toggle underline. No existing binding claims plain "u".
+  if (primary && !event.altKey && !event.shiftKey && key === "u") {
+    return run(props.onToggleUnderline);
+  }
 
   // Current Figma: Ctrl+Alt+H / Ctrl+Alt+V — distribute evenly. These use
   // literal Control even on macOS, so resolve them before the primary+V
@@ -527,11 +576,14 @@ function handleDesignHotkey(
     return run(props.onToggleLocked);
   }
   if (primary && key === "g") {
-    // Figma: ⌥⌘G is "Frame selection". Current Figma ungroups with
-    // Cmd+Backspace, so the historical Shift+Cmd+G binding is deliberately
-    // left unhandled.
+    // Figma: ⌥⌘G is "Frame selection". Current Figma's primary ungroup chord
+    // is Cmd+Backspace (see below), but Shift+Cmd+G is the long-standing
+    // historical ungroup binding and the app's own context-menu "Ungroup"
+    // item performs the identical action (handleUngroupSelection) — leaving
+    // this chord dead while the menu item works is a regression users hit,
+    // not an intentional gap. Support both bindings for ungroup.
     if (event.altKey) return run(props.onFrameSelection);
-    if (event.shiftKey) return false;
+    if (event.shiftKey) return run(props.onUngroup);
     return run(props.onGroup);
   }
 
@@ -563,6 +615,11 @@ function handleDesignHotkey(
     return run(props.onCreateComponent);
   }
 
+  // Figma's Cmd+Alt+B — Detach instance.
+  if (primary && event.altKey && key === "b") {
+    return run(props.onDetachInstance);
+  }
+
   const digit = digitFromEvent(event);
   // Figma navigation tabs use literal Option/Alt, on both platforms. Resolve
   // these before digit opacity so the physical Digit1/Digit2 keys never leak
diff --git a/templates/design/app/i18n-data.ts b/templates/design/app/i18n-data.ts
index 98350c6086..97f15d1d9a 100644
--- a/templates/design/app/i18n-data.ts
+++ b/templates/design/app/i18n-data.ts
@@ -1,6 +1,11 @@
 import type { LocaleCode } from "@agent-native/core/client";
 
 import { breakpointBarOverrides } from "./i18n-breakpoints";
+import {
+  attachLocalizedKeyboardShortcuts,
+  keyboardKeyLabels,
+  keyboardShortcutLabels,
+} from "./i18n-keyboard-shortcuts";
 import { motionDockOverrides } from "./i18n-motion";
 import zhTW from "./i18n/zh-TW";
 
@@ -264,6 +269,22 @@ const enUS = {
       right: "Right",
       justify: "Justify",
     },
+    textDecorations: {
+      underline: "Underline",
+      strikethrough: "Strikethrough",
+    },
+    textCases: {
+      none: "None",
+      uppercase: "Uppercase",
+      lowercase: "Lowercase",
+      capitalize: "Capitalize",
+    },
+    typographyDetails: {
+      basicsTab: "Basics",
+      detailsTab: "Details",
+      decorationLabel: "Decoration",
+      caseLabel: "Case",
+    },
     flexDirections: {
       row: "Row",
       column: "Column",
@@ -330,6 +351,41 @@ const enUS = {
   },
   designEditor: {
     askAgent: "Ask agent",
+    componentInstances: {
+      selectLayer: "Select layer",
+      goToMain: "Go to main component",
+      swap: "Swap instance",
+      detach: "Detach instance",
+      searchComponents: "Search components…",
+      loading: "Loading…",
+      noOtherComponents: "No other components found",
+      goToMainUnavailable: "Go to main component isn't available yet.",
+      onlyKnownInstance: "This is the only known instance of this component.",
+      resolveMainFailed: "Couldn't resolve the main component.",
+      detachFailed: "Couldn't detach this instance.",
+      detached: "Instance detached.",
+      swapFailed: "Couldn't swap this instance.",
+      swappedFor: 'Swapped for "{{name}}".',
+      openPanelNudge: "Use the Swap instance picker in the Component panel.",
+      openPanelFailed: "Could not open the component panel.",
+    },
+    makeItRealCard: {
+      open: "Open",
+      choose: "Choose",
+      connect: "Connect",
+      generating: "Generating",
+      generate: "Generate",
+      migrationFailed: "Migration failed. Please try again.",
+    },
+    componentProps: {
+      alpineTooComplexToEdit:
+        "Can’t safely edit this prop inline — this component’s Alpine state is too complex. Edit the source instead.",
+      label: "Props",
+    },
+    componentSource: {
+      editSource: "Edit component source",
+      needsConnectedApp: "Source jump needs a connected app",
+    },
     leftRail: {
       file: "File",
       agent: "Agent",
@@ -437,6 +493,12 @@ const enUS = {
       figmaPasteDescription:
         "Copy a frame or layer in Figma, then paste into the Design canvas. Design imports the visible clipboard HTML.",
       figmaPasteTarget: "Paste into the canvas",
+      figmaPasteApiKeyHint:
+        "Connect your Figma access token for exact node imports.",
+      figmaPasteMatchGuidance:
+        "Couldn't match this to specific Figma nodes. Paste a frame link instead for an exact import.",
+      figmaPasteRestLabel: "Imported via Figma API",
+      figmaPasteHtmlLabel: "Imported from clipboard preview",
       figUploadTitle: "Upload .fig",
       figUploadDescription:
         "Export only the frames you need. Large files with many embedded images may exceed the import limit.",
@@ -511,6 +573,122 @@ const enUS = {
       hand: "Hand",
       scale: "Scale",
     },
+    keyboardShortcuts: {
+      title: "Keyboard shortcuts",
+      close: "Close keyboard shortcuts",
+      codeContext: "Code",
+      screenContext: "Screen",
+      keys: {
+        or: "or",
+        command: "Command",
+        control: "Control",
+        option: "Option",
+        alt: "Alt",
+        shift: "Shift",
+        arrowDown: "Down Arrow",
+        arrowLeft: "Left Arrow",
+        arrowRight: "Right Arrow",
+        arrowUp: "Up Arrow",
+        backspace: "Backspace",
+        delete: "Delete",
+        enter: "Enter",
+        tab: "Tab",
+        questionMark: "Question Mark",
+        backslash: "Backslash",
+        equals: "Equals",
+        minus: "Minus",
+        leftBracket: "Left Bracket",
+        rightBracket: "Right Bracket",
+      },
+      descriptions: {
+        toggleUi:
+          "Press it now to quickly hide the panes and focus on your work",
+        undo: "Step back through your most recent design change",
+        redo: "Restore the design change you just undid",
+      },
+      categories: {
+        essential: "Essential",
+        tools: "Tools",
+        view: "View",
+        zoom: "Zoom",
+        text: "Text",
+        shape: "Shape",
+        selection: "Selection",
+        cursor: "Cursor",
+        edit: "Edit",
+        transform: "Transform",
+        arrange: "Arrange",
+        components: "Components",
+        layout: "Layout",
+      },
+      commands: {
+        showShortcuts: "Show keyboard shortcuts",
+        undo: "Undo",
+        redo: "Redo",
+        moveTool: "Move tool",
+        frameTool: "Frame tool",
+        textTool: "Text tool",
+        penTool: "Pen tool",
+        handTool: "Hand tool",
+        scaleTool: "Scale tool",
+        commentTool: "Comment tool",
+        drawTool: "Draw tool",
+        showLayers: "Show layers",
+        showAssets: "Show assets",
+        toggleUi: "Show/Hide UI",
+        toggleComments: "Show or hide comments",
+        zoomIn: "Zoom in",
+        zoomOut: "Zoom out",
+        zoomReset: "Zoom to 100%",
+        zoomFit: "Zoom to fit",
+        zoomSelection: "Zoom to selection",
+        underline: "Underline",
+        strikethrough: "Strikethrough",
+        rectangle: "Rectangle",
+        ellipse: "Ellipse",
+        line: "Line",
+        arrow: "Arrow",
+        selectAll: "Select all",
+        selectParent: "Select parent",
+        enterSelection: "Enter selection",
+        nextSibling: "Next sibling",
+        previousSibling: "Previous sibling",
+        nextScreen: "Next screen",
+        previousScreen: "Previous screen",
+        nudge: "Nudge",
+        nudgeLarge: "Nudge by 10",
+        copy: "Copy",
+        copyPng: "Copy as PNG",
+        cut: "Cut",
+        paste: "Paste",
+        pasteOver: "Paste over selection",
+        copyProperties: "Copy properties",
+        pasteProperties: "Paste properties",
+        pasteReplace: "Paste to replace",
+        duplicate: "Duplicate",
+        delete: "Delete",
+        rename: "Rename",
+        find: "Find layers",
+        flipHorizontal: "Flip horizontal",
+        flipVertical: "Flip vertical",
+        swapFillStroke: "Swap fill and stroke",
+        bringForward: "Bring forward",
+        sendBackward: "Send backward",
+        bringFront: "Bring to front",
+        sendBack: "Send to back",
+        alignLeft: "Align left",
+        alignRight: "Align right",
+        alignTop: "Align top",
+        alignBottom: "Align bottom",
+        tidy: "Tidy up",
+        createComponent: "Create component",
+        detachInstance: "Detach instance",
+        group: "Group selection",
+        ungroup: "Ungroup selection",
+        frameSelection: "Frame selection",
+        autoLayout: "Add auto layout",
+      },
+    },
     undo: "Undo",
     undoShortcut: "Undo (⌘Z)",
     redo: "Redo",
@@ -667,6 +845,13 @@ const enUS = {
       openScreenSvg: "Open a screen before exporting SVG",
       svgDownloaded: "SVG downloaded",
       svgExportError: "Could not export SVG",
+      figmaSvgCopied: "Copied as Figma SVG",
+      figmaSvgUnsupported:
+        "This browser can't copy SVG images to the clipboard",
+      figmaSvgBlocked: "Allow clipboard access to copy this SVG",
+      figmaSvgWriteError: "Could not copy SVG to the clipboard",
+      figmaSvgRenderError: "Could not create the Figma SVG",
+      figmaSvgExportError: "Could not export Figma SVG",
       screenDuplicated: "Screen duplicated",
       screenDuplicateError: "Could not duplicate screen",
       copied: "Copied",
@@ -691,6 +876,8 @@ const enUS = {
       undoSkippedConcurrentEdit: "Skipped an undo — someone else moved that",
       redoSkippedConcurrentEdit: "Skipped a redo — someone else moved that",
       autoLayoutScreensUnsupported: "Add auto layout doesn't apply to screens",
+      reactSourceAnchorsLoading:
+        "React source anchors are still loading. Try again once the local app finishes rendering.",
     },
   },
   layersPanel: {
@@ -727,6 +914,15 @@ const enUS = {
     frameSelection: "Frame selection",
     flipHorizontal: "Flip horizontal",
     flipVertical: "Flip vertical",
+    dragGhostCount: "{{count}} layers",
+  },
+  designCanvas: {
+    localBridge: {
+      confirmationRetryExhausted:
+        "Live editor bridge did not confirm after several attempts.",
+      connectionNotConfirmed:
+        "The live editor bridge did not confirm the connection. Is the local dev server still running?",
+    },
   },
   multiScreenCanvas: {
     duplicate: "Duplicate",
@@ -806,6 +1002,8 @@ const enUS = {
     assetAdded: "Asset added",
     assetsNoImageUrl: "Assets did not return an image URL.",
     failedToUploadFile: "Failed to upload file",
+    failedToSubmitPrompt: "Failed to submit prompt",
+    skipPrompt: "Skip prompt",
     designSystem: "Design system",
     noDesignSystem: "No design system",
     newDesignSystem: "New",
@@ -834,8 +1032,11 @@ const enUS = {
     offline: "Offline",
     saving: "Saving...",
     clearedAllAnnotations: "Cleared all annotations",
+    annotationsDiscardedOnViewChange:
+      "{{count}} unsent annotation(s) were discarded when you left this view.",
     undo: "Undo",
     send: "Send",
+    sendingDrawing: "Sending…",
     commentSent: "Comment sent",
     comment: "Comment",
     annotationQueue: "Annotation queue",
@@ -878,6 +1079,9 @@ const enUS = {
       conflict: "Conflict {{count}}",
       blocked: "Blocked {{count}}",
     },
+    queuedCommentsDiscarded:
+      "{{count}} unsent comment draft(s) were discarded when you left this view.",
+    staleAnchorDetail: "Original element no longer found on the canvas.",
   },
   home: {
     pageTitle: "Designs",
@@ -1180,6 +1384,17 @@ function mergeMessages(overrides: PartialMessages): Messages {
   return deepMerge(enUS, overrides);
 }
 
+function mergeLocalizedMessages(
+  locale: Exclude<LocaleCode, "en-US">,
+  overrides: PartialMessages,
+): Messages {
+  return attachLocalizedKeyboardShortcuts(
+    mergeMessages(overrides),
+    keyboardShortcutLabels[locale],
+    keyboardKeyLabels[locale],
+  );
+}
+
 function mergePartialMessages(
   ...overrides: PartialMessages[]
 ): PartialMessages {
@@ -1266,6 +1481,22 @@ const designLocaleOverrides = {
         right: "正确的",
         justify: "证明合法",
       },
+      textDecorations: {
+        underline: "下划线",
+        strikethrough: "删除线",
+      },
+      textCases: {
+        none: "无",
+        uppercase: "大写",
+        lowercase: "小写",
+        capitalize: "首字母大写",
+      },
+      typographyDetails: {
+        basicsTab: "基础",
+        detailsTab: "详细信息",
+        decorationLabel: "装饰",
+        caseLabel: "大小写",
+      },
       flexDirections: {
         row: "排",
         column: "柱子",
@@ -1627,6 +1858,22 @@ const designLocaleOverrides = {
         right: "Bien",
         justify: "Justificar",
       },
+      textDecorations: {
+        underline: "Subrayado",
+        strikethrough: "Tachado",
+      },
+      textCases: {
+        none: "Ninguno",
+        uppercase: "Mayúsculas",
+        lowercase: "Minúsculas",
+        capitalize: "Capitalizar",
+      },
+      typographyDetails: {
+        basicsTab: "Básicos",
+        detailsTab: "Detalles",
+        decorationLabel: "Decoración",
+        caseLabel: "Mayúsculas y minúsculas",
+      },
       flexDirections: {
         row: "Fila",
         column: "Columna",
@@ -2010,6 +2257,22 @@ const designLocaleOverrides = {
         right: "Droite",
         justify: "Justifier",
       },
+      textDecorations: {
+        underline: "Souligné",
+        strikethrough: "Barré",
+      },
+      textCases: {
+        none: "Aucun",
+        uppercase: "Majuscules",
+        lowercase: "Minuscules",
+        capitalize: "Première lettre en majuscule",
+      },
+      typographyDetails: {
+        basicsTab: "Bases",
+        detailsTab: "Détails",
+        decorationLabel: "Décoration",
+        caseLabel: "Casse",
+      },
       flexDirections: {
         row: "Rangée",
         column: "Colonne",
@@ -2397,6 +2660,22 @@ const designLocaleOverrides = {
         right: "Rechts",
         justify: "Rechtfertigen",
       },
+      textDecorations: {
+        underline: "Unterstrichen",
+        strikethrough: "Durchgestrichen",
+      },
+      textCases: {
+        none: "Keine",
+        uppercase: "Großbuchstaben",
+        lowercase: "Kleinbuchstaben",
+        capitalize: "Großschreibung",
+      },
+      typographyDetails: {
+        basicsTab: "Grundlagen",
+        detailsTab: "Details",
+        decorationLabel: "Dekoration",
+        caseLabel: "Groß-/Kleinschreibung",
+      },
       flexDirections: {
         row: "Reihe",
         column: "Spalte",
@@ -2785,6 +3064,22 @@ const designLocaleOverrides = {
         right: "右",
         justify: "正当化する",
       },
+      textDecorations: {
+        underline: "下線",
+        strikethrough: "取り消し線",
+      },
+      textCases: {
+        none: "なし",
+        uppercase: "大文字",
+        lowercase: "小文字",
+        capitalize: "先頭を大文字にする",
+      },
+      typographyDetails: {
+        basicsTab: "基本",
+        detailsTab: "詳細",
+        decorationLabel: "装飾",
+        caseLabel: "大文字/小文字",
+      },
       flexDirections: {
         row: "行",
         column: "カラム",
@@ -3168,6 +3463,22 @@ const designLocaleOverrides = {
         right: "오른쪽",
         justify: "신이 옳다고 하다",
       },
+      textDecorations: {
+        underline: "밑줄",
+        strikethrough: "취소선",
+      },
+      textCases: {
+        none: "없음",
+        uppercase: "대문자",
+        lowercase: "소문자",
+        capitalize: "첫 글자만 대문자",
+      },
+      typographyDetails: {
+        basicsTab: "기본",
+        detailsTab: "세부 정보",
+        decorationLabel: "장식",
+        caseLabel: "대소문자",
+      },
       flexDirections: {
         row: "열",
         column: "열",
@@ -3544,6 +3855,22 @@ const designLocaleOverrides = {
         right: "Certo",
         justify: "Justificar",
       },
+      textDecorations: {
+        underline: "Sublinhado",
+        strikethrough: "Tachado",
+      },
+      textCases: {
+        none: "Nenhum",
+        uppercase: "Maiúsculas",
+        lowercase: "Minúsculas",
+        capitalize: "Capitalizar",
+      },
+      typographyDetails: {
+        basicsTab: "Básico",
+        detailsTab: "Detalhes",
+        decorationLabel: "Decoração",
+        caseLabel: "Maiúsculas e minúsculas",
+      },
       flexDirections: {
         row: "Linha",
         column: "Coluna",
@@ -3927,6 +4254,22 @@ const designLocaleOverrides = {
         right: "सही",
         justify: "औचित्य",
       },
+      textDecorations: {
+        underline: "रेखांकित",
+        strikethrough: "स्ट्राइकथ्रू",
+      },
+      textCases: {
+        none: "कोई नहीं",
+        uppercase: "बड़े अक्षर",
+        lowercase: "छोटे अक्षर",
+        capitalize: "पहला अक्षर बड़ा",
+      },
+      typographyDetails: {
+        basicsTab: "बुनियादी बातें",
+        detailsTab: "विवरण",
+        decorationLabel: "सजावट",
+        caseLabel: "बड़े/छोटे अक्षर",
+      },
       flexDirections: {
         row: "पंक्ति",
         column: "स्तंभ",
@@ -4301,6 +4644,22 @@ const designLocaleOverrides = {
         right: "يمين",
         justify: "يبرر",
       },
+      textDecorations: {
+        underline: "تسطير",
+        strikethrough: "يتوسطه خط",
+      },
+      textCases: {
+        none: "بلا",
+        uppercase: "أحرف كبيرة",
+        lowercase: "أحرف صغيرة",
+        capitalize: "بدء الكلمات بحرف كبير",
+      },
+      typographyDetails: {
+        basicsTab: "أساسيات",
+        detailsTab: "التفاصيل",
+        decorationLabel: "زخرفة",
+        caseLabel: "حالة الأحرف",
+      },
       flexDirections: {
         row: "صف",
         column: "عمود",
@@ -4682,8 +5041,11 @@ const designRawLiteralOverrides = {
       offline: "离线",
       saving: "正在保存...",
       clearedAllAnnotations: "已清除所有批注",
+      annotationsDiscardedOnViewChange:
+        "离开此视图时，{{count}} 条未发送的批注已被丢弃。",
       undo: "撤消",
       send: "发送",
+      sendingDrawing: "正在发送…",
       commentSent: "评论已发送",
       comment: "评论",
     },
@@ -4836,8 +5198,11 @@ const designRawLiteralOverrides = {
       offline: "Sin conexión",
       saving: "Guardando...",
       clearedAllAnnotations: "Se borraron todas las anotaciones",
+      annotationsDiscardedOnViewChange:
+        "Se descartaron {{count}} anotación(es) sin enviar al salir de esta vista.",
       undo: "Deshacer",
       send: "Enviar",
+      sendingDrawing: "Enviando…",
       commentSent: "Comentario enviado",
       comment: "Comentario",
     },
@@ -4991,8 +5356,11 @@ const designRawLiteralOverrides = {
       offline: "Hors ligne",
       saving: "Enregistrement...",
       clearedAllAnnotations: "Toutes les annotations ont été effacées",
+      annotationsDiscardedOnViewChange:
+        "{{count}} annotation(s) non envoyée(s) ont été abandonnées lorsque vous avez quitté cette vue.",
       undo: "Annuler",
       send: "Envoyer",
+      sendingDrawing: "Envoi…",
       commentSent: "Commentaire envoyé",
       comment: "Commentaire",
     },
@@ -5147,8 +5515,11 @@ const designRawLiteralOverrides = {
       offline: "Offline",
       saving: "Speichern...",
       clearedAllAnnotations: "Alle Anmerkungen gelöscht",
+      annotationsDiscardedOnViewChange:
+        "{{count}} nicht gesendete Anmerkung(en) wurden beim Verlassen dieser Ansicht verworfen.",
       undo: "Rückgängig",
       send: "Senden",
+      sendingDrawing: "Wird gesendet …",
       commentSent: "Kommentar gesendet",
       comment: "Kommentar",
     },
@@ -5299,8 +5670,11 @@ const designRawLiteralOverrides = {
       offline: "オフライン",
       saving: "保存中...",
       clearedAllAnnotations: "すべての注釈を消去しました",
+      annotationsDiscardedOnViewChange:
+        "この画面を離れたため、未送信の注釈{{count}}件が破棄されました。",
       undo: "元に戻す",
       send: "送信",
+      sendingDrawing: "送信中…",
       commentSent: "コメントを送信しました",
       comment: "コメント",
     },
@@ -5449,8 +5823,11 @@ const designRawLiteralOverrides = {
       offline: "오프라인",
       saving: "저장 중...",
       clearedAllAnnotations: "모든 주석이 지워졌습니다",
+      annotationsDiscardedOnViewChange:
+        "이 화면을 벗어나면서 전송되지 않은 주석 {{count}}개가 삭제되었습니다.",
       undo: "실행 취소",
       send: "보내기",
+      sendingDrawing: "전송 중…",
       commentSent: "댓글을 보냈습니다",
       comment: "댓글",
     },
@@ -5603,8 +5980,11 @@ const designRawLiteralOverrides = {
       offline: "Off-line",
       saving: "Salvando...",
       clearedAllAnnotations: "Todas as anotações foram limpas",
+      annotationsDiscardedOnViewChange:
+        "{{count}} anotação(ões) não enviada(s) foram descartadas ao sair desta visualização.",
       undo: "Desfazer",
       send: "Enviar",
+      sendingDrawing: "Enviando…",
       commentSent: "Comentário enviado",
       comment: "Comentário",
     },
@@ -5754,8 +6134,11 @@ const designRawLiteralOverrides = {
       offline: "ऑफ़लाइन",
       saving: "सहेजा जा रहा है...",
       clearedAllAnnotations: "सभी एनोटेशन साफ़ किए गए",
+      annotationsDiscardedOnViewChange:
+        "यह दृश्य छोड़ने पर {{count}} न भेजे गए एनोटेशन हटा दिए गए।",
       undo: "पूर्ववत करें",
       send: "भेजें",
+      sendingDrawing: "भेजा जा रहा है…",
       commentSent: "टिप्पणी भेजी गई",
       comment: "टिप्पणी",
     },
@@ -5904,8 +6287,11 @@ const designRawLiteralOverrides = {
       offline: "غير متصل",
       saving: "جارٍ الحفظ...",
       clearedAllAnnotations: "تم مسح جميع التعليقات التوضيحية",
+      annotationsDiscardedOnViewChange:
+        "تم تجاهل {{count}} من التعليقات التوضيحية غير المُرسَلة عند مغادرة هذا العرض.",
       undo: "تراجع",
       send: "إرسال",
+      sendingDrawing: "جارٍ الإرسال…",
       commentSent: "تم إرسال التعليق",
       comment: "تعليق",
     },
@@ -6048,6 +6434,12 @@ const designExactEnglishOverrides = {
         pngSaveError: "无法保存 PNG",
         svgDownloaded: "SVG 已下载",
         svgExportError: "无法导出 SVG",
+        figmaSvgCopied: "已复制为 Figma SVG",
+        figmaSvgUnsupported: "此浏览器无法将 SVG 图像复制到剪贴板",
+        figmaSvgBlocked: "请允许访问剪贴板以复制此 SVG",
+        figmaSvgWriteError: "无法将 SVG 复制到剪贴板",
+        figmaSvgRenderError: "无法创建 Figma SVG",
+        figmaSvgExportError: "无法导出 Figma SVG",
         zipCreateError: "无法创建 ZIP 下载",
         zipDownloaded: "ZIP 已下载",
         zipExportError: "无法导出 ZIP",
@@ -6134,6 +6526,14 @@ const designExactEnglishOverrides = {
         pngSaveError: "No se pudo guardar PNG",
         svgDownloaded: "SVG descargado",
         svgExportError: "No se pudo exportar SVG",
+        figmaSvgCopied: "Copiado como Figma SVG",
+        figmaSvgUnsupported:
+          "Este navegador no puede copiar imágenes SVG al portapapeles",
+        figmaSvgBlocked:
+          "Permite el acceso al portapapeles para copiar este SVG",
+        figmaSvgWriteError: "No se pudo copiar el SVG al portapapeles",
+        figmaSvgRenderError: "No se pudo crear el SVG de Figma",
+        figmaSvgExportError: "No se pudo exportar el SVG de Figma",
         zipCreateError: "No se pudo crear la descarga ZIP",
         zipDownloaded: "ZIP descargado",
         zipExportError: "No se pudo exportar ZIP",
@@ -6222,6 +6622,15 @@ const designExactEnglishOverrides = {
         pngSaveError: "Impossible d’enregistrer PNG",
         svgDownloaded: "SVG téléchargé",
         svgExportError: "Impossible d’exporter SVG",
+        figmaSvgCopied: "Copié en tant que SVG Figma",
+        figmaSvgUnsupported:
+          "Ce navigateur ne peut pas copier d’images SVG dans le presse-papiers",
+        figmaSvgBlocked:
+          "Autorisez l’accès au presse-papiers pour copier ce SVG",
+        figmaSvgWriteError:
+          "Impossible de copier le SVG dans le presse-papiers",
+        figmaSvgRenderError: "Impossible de créer le SVG Figma",
+        figmaSvgExportError: "Impossible d’exporter le SVG Figma",
         zipCreateError: "Impossible de créer le téléchargement ZIP",
         zipDownloaded: "ZIP téléchargé",
         zipExportError: "Impossible d’exporter ZIP",
@@ -6310,6 +6719,15 @@ const designExactEnglishOverrides = {
         pngSaveError: "PNG konnte nicht gespeichert werden",
         svgDownloaded: "SVG heruntergeladen",
         svgExportError: "SVG konnte nicht exportiert werden",
+        figmaSvgCopied: "Als Figma-SVG kopiert",
+        figmaSvgUnsupported:
+          "Dieser Browser kann SVG-Bilder nicht in die Zwischenablage kopieren",
+        figmaSvgBlocked:
+          "Erlauben Sie den Zugriff auf die Zwischenablage, um dieses SVG zu kopieren",
+        figmaSvgWriteError:
+          "SVG konnte nicht in die Zwischenablage kopiert werden",
+        figmaSvgRenderError: "Figma-SVG konnte nicht erstellt werden",
+        figmaSvgExportError: "Figma-SVG konnte nicht exportiert werden",
         zipCreateError: "ZIP-Download konnte nicht erstellt werden",
         zipDownloaded: "ZIP heruntergeladen",
         zipExportError: "ZIP konnte nicht exportiert werden",
@@ -6397,6 +6815,14 @@ const designExactEnglishOverrides = {
         pngSaveError: "PNG を保存できませんでした",
         svgDownloaded: "SVG をダウンロードしました",
         svgExportError: "SVG をエクスポートできませんでした",
+        figmaSvgCopied: "Figma SVG としてコピーしました",
+        figmaSvgUnsupported:
+          "このブラウザでは SVG 画像をクリップボードにコピーできません",
+        figmaSvgBlocked:
+          "この SVG をコピーするにはクリップボードへのアクセスを許可してください",
+        figmaSvgWriteError: "SVG をクリップボードにコピーできませんでした",
+        figmaSvgRenderError: "Figma SVG を作成できませんでした",
+        figmaSvgExportError: "Figma SVG をエクスポートできませんでした",
         zipCreateError: "ZIP ダウンロードを作成できませんでした",
         zipDownloaded: "ZIP をダウンロードしました",
         zipExportError: "ZIP をエクスポートできませんでした",
@@ -6482,6 +6908,13 @@ const designExactEnglishOverrides = {
         pngSaveError: "PNG를 저장할 수 없음",
         svgDownloaded: "SVG 다운로드됨",
         svgExportError: "SVG를 내보낼 수 없음",
+        figmaSvgCopied: "Figma SVG로 복사됨",
+        figmaSvgUnsupported:
+          "이 브라우저에서는 SVG 이미지를 클립보드에 복사할 수 없음",
+        figmaSvgBlocked: "이 SVG를 복사하려면 클립보드 접근을 허용하세요",
+        figmaSvgWriteError: "SVG를 클립보드에 복사할 수 없음",
+        figmaSvgRenderError: "Figma SVG를 만들 수 없음",
+        figmaSvgExportError: "Figma SVG를 내보낼 수 없음",
         zipCreateError: "ZIP 다운로드를 만들 수 없음",
         zipDownloaded: "ZIP 다운로드됨",
         zipExportError: "ZIP을 내보낼 수 없음",
@@ -6569,6 +7002,15 @@ const designExactEnglishOverrides = {
         pngSaveError: "Não foi possível salvar PNG",
         svgDownloaded: "SVG baixado",
         svgExportError: "Não foi possível exportar SVG",
+        figmaSvgCopied: "Copiado como Figma SVG",
+        figmaSvgUnsupported:
+          "Este navegador não pode copiar imagens SVG para a área de transferência",
+        figmaSvgBlocked:
+          "Permita o acesso à área de transferência para copiar este SVG",
+        figmaSvgWriteError:
+          "Não foi possível copiar o SVG para a área de transferência",
+        figmaSvgRenderError: "Não foi possível criar o Figma SVG",
+        figmaSvgExportError: "Não foi possível exportar o Figma SVG",
         zipCreateError: "Não foi possível criar o download ZIP",
         zipDownloaded: "ZIP baixado",
         zipExportError: "Não foi possível exportar ZIP",
@@ -6653,6 +7095,13 @@ const designExactEnglishOverrides = {
         pngSaveError: "PNG सहेजा नहीं जा सका",
         svgDownloaded: "SVG डाउनलोड हुआ",
         svgExportError: "SVG निर्यात नहीं किया जा सका",
+        figmaSvgCopied: "Figma SVG के रूप में कॉपी हुआ",
+        figmaSvgUnsupported:
+          "यह ब्राउज़र SVG छवियों को क्लिपबोर्ड पर कॉपी नहीं कर सकता",
+        figmaSvgBlocked: "इस SVG को कॉपी करने के लिए क्लिपबोर्ड एक्सेस की अनुमति दें",
+        figmaSvgWriteError: "SVG को क्लिपबोर्ड पर कॉपी नहीं किया जा सका",
+        figmaSvgRenderError: "Figma SVG नहीं बनाया जा सका",
+        figmaSvgExportError: "Figma SVG निर्यात नहीं किया जा सका",
         zipCreateError: "ZIP डाउनलोड नहीं बनाया जा सका",
         zipDownloaded: "ZIP डाउनलोड हुआ",
         zipExportError: "ZIP निर्यात नहीं किया जा सका",
@@ -6736,6 +7185,12 @@ const designExactEnglishOverrides = {
         pngSaveError: "تعذر حفظ PNG",
         svgDownloaded: "تم تنزيل SVG",
         svgExportError: "تعذر تصدير SVG",
+        figmaSvgCopied: "تم النسخ كملف Figma SVG",
+        figmaSvgUnsupported: "لا يمكن لهذا المتصفح نسخ صور SVG إلى الحافظة",
+        figmaSvgBlocked: "اسمح بالوصول إلى الحافظة لنسخ ملف SVG هذا",
+        figmaSvgWriteError: "تعذر نسخ SVG إلى الحافظة",
+        figmaSvgRenderError: "تعذر إنشاء Figma SVG",
+        figmaSvgExportError: "تعذر تصدير Figma SVG",
         zipCreateError: "تعذر إنشاء تنزيل ZIP",
         zipDownloaded: "تم تنزيل ZIP",
         zipExportError: "تعذر تصدير ZIP",
@@ -10593,6 +11048,11 @@ const designImportOverrides = {
         figmaPasteDescription:
           "在 Figma 複製畫框或圖層，然後貼到 Design 畫布。Design 會匯入可見的剪貼簿 HTML。",
         figmaPasteTarget: "貼到畫布",
+        figmaPasteApiKeyHint: "連結您的 Figma 存取權杖以取得精確的節點匯入。",
+        figmaPasteMatchGuidance:
+          "無法比對到特定的 Figma 節點。請改貼上畫框連結以進行精確匯入。",
+        figmaPasteRestLabel: "透過 Figma API 匯入",
+        figmaPasteHtmlLabel: "從剪貼簿預覽匯入",
         figUploadTitle: "上傳 .fig",
         figUploadDescription:
           "只匯出需要的畫框。含有許多嵌入圖片的大型檔案可能超過匯入限制。",
@@ -10633,6 +11093,11 @@ const designImportOverrides = {
         figmaPasteDescription:
           "在 Figma 中复制画框或图层，然后粘贴到 Design 画布。Design 会导入可见的剪贴板 HTML。",
         figmaPasteTarget: "粘贴到画布",
+        figmaPasteApiKeyHint: "连接您的 Figma 访问令牌以获得精确的节点导入。",
+        figmaPasteMatchGuidance:
+          "无法匹配到特定的 Figma 节点。请改为粘贴画框链接以进行精确导入。",
+        figmaPasteRestLabel: "通过 Figma API 导入",
+        figmaPasteHtmlLabel: "从剪贴板预览导入",
         figUploadTitle: "上传 .fig",
         figUploadDescription:
           "只导出需要的画框。包含大量嵌入图片的大文件可能超过导入限制。",
@@ -10674,6 +11139,12 @@ const designImportOverrides = {
         figmaPasteDescription:
           "Copia un marco o capa en Figma y pégalo en el lienzo de Design. Design importa el HTML visible del portapapeles.",
         figmaPasteTarget: "Pega en el lienzo",
+        figmaPasteApiKeyHint:
+          "Conecta tu token de acceso de Figma para importaciones exactas de nodos.",
+        figmaPasteMatchGuidance:
+          "No se pudo hacer coincidir con nodos específicos de Figma. Pega un enlace de marco para una importación exacta.",
+        figmaPasteRestLabel: "Importado mediante la API de Figma",
+        figmaPasteHtmlLabel: "Importado desde la vista previa del portapapeles",
         figUploadTitle: "Subir .fig",
         figUploadDescription:
           "Exporta solo los marcos necesarios. Los archivos grandes con muchas imágenes incrustadas pueden superar el límite.",
@@ -10717,6 +11188,12 @@ const designImportOverrides = {
         figmaPasteDescription:
           "Copiez un frame ou un calque dans Figma, puis collez-le dans le canevas Design. Design importe le HTML visible du presse-papiers.",
         figmaPasteTarget: "Collez dans le canevas",
+        figmaPasteApiKeyHint:
+          "Connectez votre jeton d'accès Figma pour des imports de nœuds exacts.",
+        figmaPasteMatchGuidance:
+          "Impossible de faire correspondre à des nœuds Figma précis. Collez un lien de cadre pour un import exact.",
+        figmaPasteRestLabel: "Importé via l'API Figma",
+        figmaPasteHtmlLabel: "Importé depuis l'aperçu du presse-papiers",
         figUploadTitle: "Téléverser .fig",
         figUploadDescription:
           "Exportez seulement les frames nécessaires. Les gros fichiers avec beaucoup d’images intégrées peuvent dépasser la limite.",
@@ -10760,6 +11237,12 @@ const designImportOverrides = {
         figmaPasteDescription:
           "Kopiere einen Frame oder Layer in Figma und füge ihn in die Design-Leinwand ein. Design importiert das sichtbare Zwischenablage-HTML.",
         figmaPasteTarget: "In die Leinwand einfügen",
+        figmaPasteApiKeyHint:
+          "Verbinde deinen Figma-Zugriffstoken für exakte Node-Importe.",
+        figmaPasteMatchGuidance:
+          "Konnte nicht mit bestimmten Figma-Nodes abgeglichen werden. Füge stattdessen einen Frame-Link für einen exakten Import ein.",
+        figmaPasteRestLabel: "Über die Figma-API importiert",
+        figmaPasteHtmlLabel: "Aus der Zwischenablage-Vorschau importiert",
         figUploadTitle: ".fig hochladen",
         figUploadDescription:
           "Exportiere nur die benötigten Frames. Große Dateien mit vielen eingebetteten Bildern können das Importlimit überschreiten.",
@@ -10802,6 +11285,12 @@ const designImportOverrides = {
         figmaPasteDescription:
           "Figma でフレームまたはレイヤーをコピーし、Design キャンバスに貼り付けます。Design は表示されているクリップボード HTML をインポートします。",
         figmaPasteTarget: "キャンバスに貼り付け",
+        figmaPasteApiKeyHint:
+          "正確なノードインポートのために Figma アクセストークンを接続してください。",
+        figmaPasteMatchGuidance:
+          "特定の Figma ノードと一致しませんでした。正確にインポートするにはフレームのリンクを貼り付けてください。",
+        figmaPasteRestLabel: "Figma API 経由でインポート",
+        figmaPasteHtmlLabel: "クリップボードプレビューからインポート",
         figUploadTitle: ".fig をアップロード",
         figUploadDescription:
           "必要なフレームだけを書き出してください。埋め込み画像が多い大きなファイルは制限を超える場合があります。",
@@ -10845,6 +11334,12 @@ const designImportOverrides = {
         figmaPasteDescription:
           "Figma에서 프레임이나 레이어를 복사한 뒤 Design 캔버스에 붙여넣으세요. Design은 보이는 클립보드 HTML을 가져옵니다.",
         figmaPasteTarget: "캔버스에 붙여넣기",
+        figmaPasteApiKeyHint:
+          "정확한 노드 가져오기를 위해 Figma 액세스 토큰을 연결하세요.",
+        figmaPasteMatchGuidance:
+          "특정 Figma 노드와 일치시킬 수 없습니다. 정확한 가져오기를 위해 프레임 링크를 붙여넣으세요.",
+        figmaPasteRestLabel: "Figma API로 가져옴",
+        figmaPasteHtmlLabel: "클립보드 미리보기에서 가져옴",
         figUploadTitle: ".fig 업로드",
         figUploadDescription:
           "필요한 프레임만 내보내세요. 포함된 이미지가 많은 큰 파일은 가져오기 제한을 초과할 수 있습니다.",
@@ -10888,6 +11383,13 @@ const designImportOverrides = {
         figmaPasteDescription:
           "Copie um frame ou camada no Figma e cole na tela do Design. O Design importa o HTML visível da área de transferência.",
         figmaPasteTarget: "Cole na tela",
+        figmaPasteApiKeyHint:
+          "Conecte seu token de acesso do Figma para importações exatas de nós.",
+        figmaPasteMatchGuidance:
+          "Não foi possível corresponder a nós específicos do Figma. Cole um link do frame para uma importação exata.",
+        figmaPasteRestLabel: "Importado via API do Figma",
+        figmaPasteHtmlLabel:
+          "Importado da pré-visualização da área de transferência",
         figUploadTitle: "Enviar .fig",
         figUploadDescription:
           "Exporte apenas os frames necessários. Arquivos grandes com muitas imagens incorporadas podem exceder o limite.",
@@ -10931,6 +11433,12 @@ const designImportOverrides = {
         figmaPasteDescription:
           "Figma में frame या layer कॉपी करें, फिर Design canvas में paste करें। Design visible clipboard HTML import करता है।",
         figmaPasteTarget: "canvas में paste करें",
+        figmaPasteApiKeyHint:
+          "सटीक नोड आयात के लिए अपना Figma access token कनेक्ट करें।",
+        figmaPasteMatchGuidance:
+          "विशिष्ट Figma नोड्स से मेल नहीं खाया। सटीक आयात के लिए इसके बजाय एक frame लिंक paste करें।",
+        figmaPasteRestLabel: "Figma API के ज़रिए आयात किया गया",
+        figmaPasteHtmlLabel: "क्लिपबोर्ड पूर्वावलोकन से आयात किया गया",
         figUploadTitle: ".fig अपलोड करें",
         figUploadDescription:
           "सिर्फ ज़रूरी frames export करें। कई embedded images वाली बड़ी files import limit से ऊपर जा सकती हैं।",
@@ -10973,6 +11481,12 @@ const designImportOverrides = {
         figmaPasteDescription:
           "انسخ إطارا أو طبقة في Figma، ثم الصقها في لوحة Design. يستورد Design HTML المرئي من الحافظة.",
         figmaPasteTarget: "الصق في اللوحة",
+        figmaPasteApiKeyHint:
+          "قم بربط رمز الوصول الخاص بك في Figma للحصول على استيراد دقيق للعقد.",
+        figmaPasteMatchGuidance:
+          "تعذّرت المطابقة مع عُقد Figma محددة. الصق رابط الإطار بدلاً من ذلك للحصول على استيراد دقيق.",
+        figmaPasteRestLabel: "تم الاستيراد عبر واجهة Figma البرمجية",
+        figmaPasteHtmlLabel: "تم الاستيراد من معاينة الحافظة",
         figUploadTitle: "رفع .fig",
         figUploadDescription:
           "صدّر الإطارات التي تحتاجها فقط. قد تتجاوز الملفات الكبيرة ذات الصور المضمنة الكثيرة حد الاستيراد.",
@@ -12220,9 +12734,666 @@ const designMotionAndBreakpointOverrides = {
   },
 } satisfies Record<Exclude<LocaleCode, "en-US" | "zh-TW">, PartialMessages>;
 
+// Runtime-layer identity, prompt/comment feedback, and localhost bridge copy.
+// zh-TW lives in app/i18n/zh-TW.ts with the rest of that locale's catalog.
+const designRuntimeIdentityAndBridgeOverrides = {
+  "zh-CN": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "React 源码锚点仍在加载中。请等本地应用完成渲染后再试一次。",
+      },
+    },
+    layersPanel: { dragGhostCount: "{{count}} 个图层" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "多次尝试后，实时编辑器桥接器仍未确认连接。",
+        connectionNotConfirmed:
+          "实时编辑器桥接器未确认连接。本地开发服务器是否仍在运行？",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "无法提交提示",
+      skipPrompt: "跳过提示",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "离开此视图时，{{count}} 个未发送的评论草稿已被丢弃。",
+      staleAnchorDetail: "在画布上已找不到原始元素。",
+    },
+  },
+  "es-ES": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "Los anclajes al código fuente de React aún se están cargando. Vuelve a intentarlo cuando la aplicación local termine de renderizarse.",
+      },
+    },
+    layersPanel: { dragGhostCount: "{{count}} capas" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "El puente del editor en vivo no confirmó la conexión tras varios intentos.",
+        connectionNotConfirmed:
+          "El puente del editor en vivo no confirmó la conexión. ¿Sigue ejecutándose el servidor de desarrollo local?",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "No se pudo enviar el prompt",
+      skipPrompt: "Omitir prompt",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "Se descartaron {{count}} borradores de comentarios sin enviar al salir de esta vista.",
+      staleAnchorDetail:
+        "Ya no se encuentra el elemento original en el lienzo.",
+    },
+  },
+  "fr-FR": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "Les ancres vers le code source React sont encore en cours de chargement. Réessayez une fois le rendu de l’application locale terminé.",
+      },
+    },
+    layersPanel: { dragGhostCount: "{{count}} calques" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "Le pont de l’éditeur en direct n’a pas confirmé la connexion après plusieurs tentatives.",
+        connectionNotConfirmed:
+          "Le pont de l’éditeur en direct n’a pas confirmé la connexion. Le serveur de développement local est-il toujours en cours d’exécution ?",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "Impossible d’envoyer le prompt",
+      skipPrompt: "Ignorer le prompt",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "Vous avez quitté cette vue : {{count}} brouillons de commentaires non envoyés ont été supprimés.",
+      staleAnchorDetail: "L’élément d’origine est introuvable sur le canevas.",
+    },
+  },
+  "de-DE": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "Die React-Quellcodeanker werden noch geladen. Versuche es erneut, sobald die lokale App vollständig gerendert wurde.",
+      },
+    },
+    layersPanel: { dragGhostCount: "{{count}} Ebenen" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "Die Live-Editor-Bridge hat die Verbindung auch nach mehreren Versuchen nicht bestätigt.",
+        connectionNotConfirmed:
+          "Die Live-Editor-Bridge hat die Verbindung nicht bestätigt. Läuft der lokale Entwicklungsserver noch?",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "Prompt konnte nicht gesendet werden",
+      skipPrompt: "Prompt überspringen",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "Beim Verlassen dieser Ansicht wurden {{count}} nicht gesendete Kommentarentwürfe verworfen.",
+      staleAnchorDetail:
+        "Das ursprüngliche Element wurde auf der Arbeitsfläche nicht mehr gefunden.",
+    },
+  },
+  "ja-JP": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "React ソースのアンカーを読み込み中です。ローカルアプリのレンダリングが完了してからもう一度お試しください。",
+      },
+    },
+    layersPanel: { dragGhostCount: "{{count}} 個のレイヤー" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "数回試行しましたが、ライブエディターブリッジから確認応答がありませんでした。",
+        connectionNotConfirmed:
+          "ライブエディターブリッジが接続を確認できませんでした。ローカル開発サーバーはまだ実行中ですか？",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "プロンプトを送信できませんでした",
+      skipPrompt: "プロンプトをスキップ",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "このビューを離れたため、未送信のコメント下書き {{count}} 件が破棄されました。",
+      staleAnchorDetail: "元の要素がキャンバス上に見つかりません。",
+    },
+  },
+  "ko-KR": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "React 소스 앵커를 아직 불러오는 중입니다. 로컬 앱의 렌더링이 끝난 후 다시 시도하세요.",
+      },
+    },
+    layersPanel: { dragGhostCount: "레이어 {{count}}개" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "여러 번 시도했지만 라이브 편집기 브리지가 연결을 확인하지 못했습니다.",
+        connectionNotConfirmed:
+          "라이브 편집기 브리지가 연결을 확인하지 못했습니다. 로컬 개발 서버가 아직 실행 중인가요?",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "프롬프트를 제출하지 못했습니다",
+      skipPrompt: "프롬프트 건너뛰기",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "이 보기를 벗어나면서 보내지 않은 댓글 초안 {{count}}개가 삭제되었습니다.",
+      staleAnchorDetail: "원래 요소를 캔버스에서 더 이상 찾을 수 없습니다.",
+    },
+  },
+  "pt-BR": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "Os vínculos ao código-fonte do React ainda estão sendo carregados. Tente novamente quando o app local terminar de renderizar.",
+      },
+    },
+    layersPanel: { dragGhostCount: "{{count}} camadas" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "Mesmo após várias tentativas, a ponte do editor em tempo real não confirmou a conexão.",
+        connectionNotConfirmed:
+          "A ponte do editor em tempo real não confirmou a conexão. O servidor de desenvolvimento local ainda está em execução?",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "Não foi possível enviar o prompt",
+      skipPrompt: "Pular prompt",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "{{count}} rascunhos de comentários não enviados foram descartados quando você saiu desta visualização.",
+      staleAnchorDetail:
+        "O elemento original não foi mais encontrado na tela de design.",
+    },
+  },
+  "hi-IN": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "React सोर्स एंकर अभी लोड हो रहे हैं। लोकल ऐप की रेंडरिंग पूरी होने के बाद फिर से कोशिश करें।",
+      },
+    },
+    layersPanel: { dragGhostCount: "{{count}} लेयर" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "कई कोशिशों के बाद भी लाइव एडिटर ब्रिज ने कनेक्शन की पुष्टि नहीं की।",
+        connectionNotConfirmed:
+          "लाइव एडिटर ब्रिज ने कनेक्शन की पुष्टि नहीं की। क्या लोकल डेवलपमेंट सर्वर अभी भी चल रहा है?",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "प्रॉम्प्ट सबमिट नहीं हो सका",
+      skipPrompt: "प्रॉम्प्ट छोड़ें",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "इस व्यू से बाहर निकलने पर {{count}} नहीं भेजे गए कमेंट ड्राफ़्ट हटा दिए गए।",
+      staleAnchorDetail: "मूल एलिमेंट अब कैनवास पर नहीं मिला।",
+    },
+  },
+  "ar-SA": {
+    designEditor: {
+      toasts: {
+        reactSourceAnchorsLoading:
+          "لا تزال نقاط ارتساء مصدر React قيد التحميل. أعد المحاولة بعد اكتمال عرض التطبيق المحلي.",
+      },
+    },
+    layersPanel: { dragGhostCount: "{{count}} طبقات" },
+    designCanvas: {
+      localBridge: {
+        confirmationRetryExhausted:
+          "لم يؤكد جسر المحرر المباشر الاتصال بعد عدة محاولات.",
+        connectionNotConfirmed:
+          "لم يؤكد جسر المحرر المباشر الاتصال. هل لا يزال خادم التطوير المحلي قيد التشغيل؟",
+      },
+    },
+    promptDialog: {
+      failedToSubmitPrompt: "تعذر إرسال المطالبة",
+      skipPrompt: "تخطي المطالبة",
+    },
+    visualEditor: {
+      queuedCommentsDiscarded:
+        "تم تجاهل {{count}} مسودة تعليق غير مرسلة عند مغادرة هذا العرض.",
+      staleAnchorDetail: "لم يعد العنصر الأصلي موجودًا على لوحة الرسم.",
+    },
+  },
+} satisfies Record<Exclude<LocaleCode, "en-US" | "zh-TW">, PartialMessages>;
+
+// zh-TW strings for designEditor.componentInstances live in app/i18n/zh-TW.ts
+// (the full zh-TW locale file), not here.
+const designComponentInstanceOverrides = {
+  "zh-CN": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "选择图层",
+        goToMain: "转到主组件",
+        swap: "交换实例",
+        detach: "分离实例",
+        searchComponents: "搜索组件…",
+        loading: "正在加载…",
+        noOtherComponents: "未找到其他组件",
+        goToMainUnavailable: "目前无法转到主组件。",
+        onlyKnownInstance: "这是此组件唯一已知的实例。",
+        resolveMainFailed: "无法解析主组件。",
+        detachFailed: "无法分离此实例。",
+        detached: "实例已分离。",
+        swapFailed: "无法交换此实例。",
+        swappedFor: "已交换为“{{name}}”。",
+        openPanelNudge: "请使用“组件”面板中的“交换实例”选择器。",
+        openPanelFailed: "无法打开组件面板。",
+      },
+    },
+  },
+  "es-ES": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "Seleccionar capa",
+        goToMain: "Ir al componente principal",
+        swap: "Intercambiar instancia",
+        detach: "Desvincular instancia",
+        searchComponents: "Buscar componentes…",
+        loading: "Cargando…",
+        noOtherComponents: "No se encontraron otros componentes",
+        goToMainUnavailable:
+          "Ir al componente principal todavía no está disponible.",
+        onlyKnownInstance:
+          "Esta es la única instancia conocida de este componente.",
+        resolveMainFailed: "No se pudo resolver el componente principal.",
+        detachFailed: "No se pudo desvincular esta instancia.",
+        detached: "Instancia desvinculada.",
+        swapFailed: "No se pudo intercambiar esta instancia.",
+        swappedFor: 'Se intercambió por "{{name}}".',
+        openPanelNudge:
+          "Usa el selector Intercambiar instancia del panel Componente.",
+        openPanelFailed: "No se pudo abrir el panel Componente.",
+      },
+    },
+  },
+  "fr-FR": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "Sélectionner un calque",
+        goToMain: "Accéder au composant principal",
+        swap: "Permuter l’instance",
+        detach: "Détacher l’instance",
+        searchComponents: "Rechercher des composants…",
+        loading: "Chargement…",
+        noOtherComponents: "Aucun autre composant trouvé",
+        goToMainUnavailable:
+          "L’accès au composant principal n’est pas encore disponible.",
+        onlyKnownInstance:
+          "Il s’agit de la seule instance connue de ce composant.",
+        resolveMainFailed: "Impossible de résoudre le composant principal.",
+        detachFailed: "Impossible de détacher cette instance.",
+        detached: "Instance détachée.",
+        swapFailed: "Impossible de permuter cette instance.",
+        swappedFor: "Instance remplacée par « {{name}} ».",
+        openPanelNudge:
+          "Utilisez le sélecteur Permuter l’instance dans le panneau Composant.",
+        openPanelFailed: "Impossible d’ouvrir le panneau Composant.",
+      },
+    },
+  },
+  "de-DE": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "Ebene auswählen",
+        goToMain: "Zur Hauptkomponente",
+        swap: "Instanz austauschen",
+        detach: "Instanz lösen",
+        searchComponents: "Komponenten suchen…",
+        loading: "Wird geladen…",
+        noOtherComponents: "Keine weiteren Komponenten gefunden",
+        goToMainUnavailable: "Die Hauptkomponente ist noch nicht verfügbar.",
+        onlyKnownInstance:
+          "Dies ist die einzige bekannte Instanz dieser Komponente.",
+        resolveMainFailed: "Die Hauptkomponente konnte nicht ermittelt werden.",
+        detachFailed: "Diese Instanz konnte nicht gelöst werden.",
+        detached: "Instanz gelöst.",
+        swapFailed: "Diese Instanz konnte nicht ausgetauscht werden.",
+        swappedFor: "Durch „{{name}}“ ersetzt.",
+        openPanelNudge:
+          "Verwende die Auswahl „Instanz austauschen“ im Komponentenbereich.",
+        openPanelFailed: "Der Komponentenbereich konnte nicht geöffnet werden.",
+      },
+    },
+  },
+  "ja-JP": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "レイヤーを選択",
+        goToMain: "メインコンポーネントに移動",
+        swap: "インスタンスを入れ替え",
+        detach: "インスタンスを切り離す",
+        searchComponents: "コンポーネントを検索…",
+        loading: "読み込み中…",
+        noOtherComponents: "他のコンポーネントが見つかりません",
+        goToMainUnavailable:
+          "メインコンポーネントへの移動はまだ利用できません。",
+        onlyKnownInstance:
+          "これはこのコンポーネントで確認できる唯一のインスタンスです。",
+        resolveMainFailed: "メインコンポーネントを特定できませんでした。",
+        detachFailed: "このインスタンスを切り離せませんでした。",
+        detached: "インスタンスを切り離しました。",
+        swapFailed: "このインスタンスを入れ替えられませんでした。",
+        swappedFor: "「{{name}}」に入れ替えました。",
+        openPanelNudge:
+          "コンポーネントパネルの「インスタンスを入れ替え」を使用してください。",
+        openPanelFailed: "コンポーネントパネルを開けませんでした。",
+      },
+    },
+  },
+  "ko-KR": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "레이어 선택",
+        goToMain: "메인 컴포넌트로 이동",
+        swap: "인스턴스 교체",
+        detach: "인스턴스 분리",
+        searchComponents: "컴포넌트 검색…",
+        loading: "불러오는 중…",
+        noOtherComponents: "다른 컴포넌트를 찾을 수 없습니다",
+        goToMainUnavailable: "메인 컴포넌트로 이동은 아직 사용할 수 없습니다.",
+        onlyKnownInstance: "이 컴포넌트에서 확인된 유일한 인스턴스입니다.",
+        resolveMainFailed: "메인 컴포넌트를 확인할 수 없습니다.",
+        detachFailed: "이 인스턴스를 분리할 수 없습니다.",
+        detached: "인스턴스를 분리했습니다.",
+        swapFailed: "이 인스턴스를 교체할 수 없습니다.",
+        swappedFor: '"{{name}}"(으)로 교체했습니다.',
+        openPanelNudge: "컴포넌트 패널의 인스턴스 교체 선택기를 사용하세요.",
+        openPanelFailed: "컴포넌트 패널을 열 수 없습니다.",
+      },
+    },
+  },
+  "pt-BR": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "Selecionar camada",
+        goToMain: "Ir para o componente principal",
+        swap: "Trocar instância",
+        detach: "Desvincular instância",
+        searchComponents: "Buscar componentes…",
+        loading: "Carregando…",
+        noOtherComponents: "Nenhum outro componente encontrado",
+        goToMainUnavailable:
+          "Ir para o componente principal ainda não está disponível.",
+        onlyKnownInstance:
+          "Esta é a única instância conhecida deste componente.",
+        resolveMainFailed: "Não foi possível encontrar o componente principal.",
+        detachFailed: "Não foi possível desvincular esta instância.",
+        detached: "Instância desvinculada.",
+        swapFailed: "Não foi possível trocar esta instância.",
+        swappedFor: 'Trocada por "{{name}}".',
+        openPanelNudge: "Use o seletor Trocar instância no painel Componente.",
+        openPanelFailed: "Não foi possível abrir o painel Componente.",
+      },
+    },
+  },
+  "hi-IN": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "लेयर चुनें",
+        goToMain: "मुख्य कॉम्पोनेंट पर जाएं",
+        swap: "इंस्टेंस बदलें",
+        detach: "इंस्टेंस अलग करें",
+        searchComponents: "कॉम्पोनेंट खोजें…",
+        loading: "लोड हो रहा है…",
+        noOtherComponents: "कोई अन्य कॉम्पोनेंट नहीं मिला",
+        goToMainUnavailable: "मुख्य कॉम्पोनेंट पर जाना अभी उपलब्ध नहीं है।",
+        onlyKnownInstance: "यह इस कॉम्पोनेंट का एकमात्र ज्ञात इंस्टेंस है।",
+        resolveMainFailed: "मुख्य कॉम्पोनेंट का पता नहीं लगाया जा सका।",
+        detachFailed: "इस इंस्टेंस को अलग नहीं किया जा सका।",
+        detached: "इंस्टेंस अलग कर दिया गया।",
+        swapFailed: "इस इंस्टेंस को बदला नहीं जा सका।",
+        swappedFor: '"{{name}}" से बदल दिया गया।',
+        openPanelNudge: "कॉम्पोनेंट पैनल में इंस्टेंस बदलें चयनकर्ता का उपयोग करें।",
+        openPanelFailed: "कॉम्पोनेंट पैनल नहीं खोला जा सका।",
+      },
+    },
+  },
+  "ar-SA": {
+    designEditor: {
+      componentInstances: {
+        selectLayer: "تحديد طبقة",
+        goToMain: "الانتقال إلى المكوّن الرئيسي",
+        swap: "تبديل النسخة",
+        detach: "فصل النسخة",
+        searchComponents: "البحث عن مكوّنات…",
+        loading: "جارٍ التحميل…",
+        noOtherComponents: "لم يتم العثور على مكوّنات أخرى",
+        goToMainUnavailable: "الانتقال إلى المكوّن الرئيسي غير متاح بعد.",
+        onlyKnownInstance: "هذه هي النسخة الوحيدة المعروفة من هذا المكوّن.",
+        resolveMainFailed: "تعذر تحديد المكوّن الرئيسي.",
+        detachFailed: "تعذر فصل هذه النسخة.",
+        detached: "تم فصل النسخة.",
+        swapFailed: "تعذر تبديل هذه النسخة.",
+        swappedFor: 'تم التبديل إلى "{{name}}".',
+        openPanelNudge: "استخدم منتقي تبديل النسخة في لوحة المكوّن.",
+        openPanelFailed: "تعذر فتح لوحة المكوّن.",
+      },
+    },
+  },
+} satisfies Record<Exclude<LocaleCode, "en-US" | "zh-TW">, PartialMessages>;
+
+// zh-TW strings for designEditor.makeItRealCard / componentProps /
+// componentSource live in app/i18n/zh-TW.ts (the full zh-TW locale file),
+// not here.
+const designComponentSourceOverrides = {
+  "zh-CN": {
+    designEditor: {
+      makeItRealCard: {
+        open: "打开",
+        choose: "选择",
+        connect: "连接",
+        generating: "生成中",
+        generate: "生成",
+        migrationFailed: "迁移失败，请重试。",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "无法就地安全编辑此属性——此组件的 Alpine 状态过于复杂。请改为编辑源代码。",
+        label: "属性",
+      },
+      componentSource: {
+        editSource: "编辑组件源代码",
+        needsConnectedApp: "源代码跳转需要连接应用",
+      },
+    },
+  },
+  "es-ES": {
+    designEditor: {
+      makeItRealCard: {
+        open: "Abrir",
+        choose: "Elegir",
+        connect: "Conectar",
+        generating: "Generando",
+        generate: "Generar",
+        migrationFailed: "Error en la migración. Inténtalo de nuevo.",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "No se puede editar esta propiedad de forma segura en línea: el estado de Alpine de este componente es demasiado complejo. Edita el código fuente en su lugar.",
+        label: "Propiedades",
+      },
+      componentSource: {
+        editSource: "Editar código fuente del componente",
+        needsConnectedApp: "Saltar al código fuente requiere una app conectada",
+      },
+    },
+  },
+  "fr-FR": {
+    designEditor: {
+      makeItRealCard: {
+        open: "Ouvrir",
+        choose: "Choisir",
+        connect: "Connecter",
+        generating: "Génération en cours",
+        generate: "Générer",
+        migrationFailed: "Échec de la migration. Veuillez réessayer.",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "Impossible de modifier cette propriété en toute sécurité en ligne — l’état Alpine de ce composant est trop complexe. Modifiez plutôt le code source.",
+        label: "Propriétés",
+      },
+      componentSource: {
+        editSource: "Modifier le code source du composant",
+        needsConnectedApp:
+          "L’accès au code source nécessite une application connectée",
+      },
+    },
+  },
+  "de-DE": {
+    designEditor: {
+      makeItRealCard: {
+        open: "Öffnen",
+        choose: "Auswählen",
+        connect: "Verbinden",
+        generating: "Wird generiert",
+        generate: "Generieren",
+        migrationFailed: "Migration fehlgeschlagen. Bitte versuche es erneut.",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "Diese Eigenschaft kann nicht sicher inline bearbeitet werden – der Alpine-Zustand dieser Komponente ist zu komplex. Bearbeite stattdessen den Quellcode.",
+        label: "Eigenschaften",
+      },
+      componentSource: {
+        editSource: "Komponentenquelle bearbeiten",
+        needsConnectedApp:
+          "Für den Sprung zur Quelle ist eine verbundene App erforderlich",
+      },
+    },
+  },
+  "ja-JP": {
+    designEditor: {
+      makeItRealCard: {
+        open: "開く",
+        choose: "選択",
+        connect: "接続",
+        generating: "生成中",
+        generate: "生成",
+        migrationFailed: "移行に失敗しました。もう一度お試しください。",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "このプロパティはインラインで安全に編集できません — このコンポーネントの Alpine の状態が複雑すぎます。代わりにソースを編集してください。",
+        label: "プロパティ",
+      },
+      componentSource: {
+        editSource: "コンポーネントのソースを編集",
+        needsConnectedApp: "ソースへのジャンプには接続済みアプリが必要です",
+      },
+    },
+  },
+  "ko-KR": {
+    designEditor: {
+      makeItRealCard: {
+        open: "열기",
+        choose: "선택",
+        connect: "연결",
+        generating: "생성 중",
+        generate: "생성",
+        migrationFailed: "마이그레이션에 실패했습니다. 다시 시도해 주세요.",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "이 속성은 인라인으로 안전하게 편집할 수 없습니다 — 이 컴포넌트의 Alpine 상태가 너무 복잡합니다. 대신 소스를 편집하세요.",
+        label: "속성",
+      },
+      componentSource: {
+        editSource: "컴포넌트 소스 편집",
+        needsConnectedApp: "소스로 이동하려면 연결된 앱이 필요합니다",
+      },
+    },
+  },
+  "pt-BR": {
+    designEditor: {
+      makeItRealCard: {
+        open: "Abrir",
+        choose: "Escolher",
+        connect: "Conectar",
+        generating: "Gerando",
+        generate: "Gerar",
+        migrationFailed: "Falha na migração. Tente novamente.",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "Não é possível editar esta propriedade com segurança embutida — o estado Alpine deste componente é complexo demais. Edite o código-fonte em vez disso.",
+        label: "Propriedades",
+      },
+      componentSource: {
+        editSource: "Editar código-fonte do componente",
+        needsConnectedApp:
+          "Ir para o código-fonte exige um aplicativo conectado",
+      },
+    },
+  },
+  "hi-IN": {
+    designEditor: {
+      makeItRealCard: {
+        open: "खोलें",
+        choose: "चुनें",
+        connect: "कनेक्ट करें",
+        generating: "जनरेट हो रहा है",
+        generate: "जनरेट करें",
+        migrationFailed: "माइग्रेशन विफल रहा। कृपया फिर से कोशिश करें।",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "इस प्रॉप को इनलाइन सुरक्षित रूप से संपादित नहीं किया जा सकता — इस कॉम्पोनेंट की Alpine स्थिति बहुत जटिल है। इसके बजाय सोर्स संपादित करें।",
+        label: "प्रॉप्स",
+      },
+      componentSource: {
+        editSource: "कॉम्पोनेंट सोर्स संपादित करें",
+        needsConnectedApp: "सोर्स पर जाने के लिए कनेक्टेड ऐप आवश्यक है",
+      },
+    },
+  },
+  "ar-SA": {
+    designEditor: {
+      makeItRealCard: {
+        open: "فتح",
+        choose: "اختيار",
+        connect: "ربط",
+        generating: "جارٍ الإنشاء",
+        generate: "إنشاء",
+        migrationFailed: "فشل الترحيل. يُرجى المحاولة مرة أخرى.",
+      },
+      componentProps: {
+        alpineTooComplexToEdit:
+          "تعذّر تعديل هذه الخاصية مضمّنًا بأمان — حالة Alpine لهذا المكوّن معقّدة جدًا. عدّل الشيفرة المصدرية بدلاً من ذلك.",
+        label: "الخصائص",
+      },
+      componentSource: {
+        editSource: "تعديل الشيفرة المصدرية للمكوّن",
+        needsConnectedApp: "الانتقال إلى المصدر يتطلب تطبيقًا متصلًا",
+      },
+    },
+  },
+} satisfies Record<Exclude<LocaleCode, "en-US" | "zh-TW">, PartialMessages>;
+
 export const messagesByLocale = {
   "en-US": enUS,
-  "zh-TW": mergeMessages(
+  "zh-TW": mergeLocalizedMessages(
+    "zh-TW",
     mergePartialMessages(
       zhTW,
       designLeftRailOverrides["zh-TW"],
@@ -12239,7 +13410,8 @@ export const messagesByLocale = {
       motionDockOverrides["zh-TW"],
     ),
   ),
-  "zh-CN": mergeMessages(
+  "zh-CN": mergeLocalizedMessages(
+    "zh-CN",
     mergePartialMessages(
       designLocaleOverrides["zh-CN"],
       designRawLiteralOverrides["zh-CN"],
@@ -12261,6 +13433,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["zh-CN"],
       breakpointBarOverrides["zh-CN"],
       motionDockOverrides["zh-CN"],
+      designRuntimeIdentityAndBridgeOverrides["zh-CN"],
+      designComponentInstanceOverrides["zh-CN"],
+      designComponentSourceOverrides["zh-CN"],
       {
         root: {
           commandActions: "操作",
@@ -12308,7 +13483,8 @@ export const messagesByLocale = {
       },
     ),
   ),
-  "es-ES": mergeMessages(
+  "es-ES": mergeLocalizedMessages(
+    "es-ES",
     mergePartialMessages(
       designLocaleOverrides["es-ES"],
       designRawLiteralOverrides["es-ES"],
@@ -12330,6 +13506,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["es-ES"],
       breakpointBarOverrides["es-ES"],
       motionDockOverrides["es-ES"],
+      designRuntimeIdentityAndBridgeOverrides["es-ES"],
+      designComponentInstanceOverrides["es-ES"],
+      designComponentSourceOverrides["es-ES"],
       {
         root: {
           commandActions: "Acciones",
@@ -12379,7 +13558,8 @@ export const messagesByLocale = {
       },
     ),
   ),
-  "fr-FR": mergeMessages(
+  "fr-FR": mergeLocalizedMessages(
+    "fr-FR",
     mergePartialMessages(
       designLocaleOverrides["fr-FR"],
       designRawLiteralOverrides["fr-FR"],
@@ -12401,6 +13581,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["fr-FR"],
       breakpointBarOverrides["fr-FR"],
       motionDockOverrides["fr-FR"],
+      designRuntimeIdentityAndBridgeOverrides["fr-FR"],
+      designComponentInstanceOverrides["fr-FR"],
+      designComponentSourceOverrides["fr-FR"],
       {
         root: {
           commandActions: "Actions",
@@ -12450,7 +13633,8 @@ export const messagesByLocale = {
       },
     ),
   ),
-  "de-DE": mergeMessages(
+  "de-DE": mergeLocalizedMessages(
+    "de-DE",
     mergePartialMessages(
       designLocaleOverrides["de-DE"],
       designRawLiteralOverrides["de-DE"],
@@ -12472,6 +13656,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["de-DE"],
       breakpointBarOverrides["de-DE"],
       motionDockOverrides["de-DE"],
+      designRuntimeIdentityAndBridgeOverrides["de-DE"],
+      designComponentInstanceOverrides["de-DE"],
+      designComponentSourceOverrides["de-DE"],
       {
         root: {
           commandActions: "Aktionen",
@@ -12521,7 +13708,8 @@ export const messagesByLocale = {
       },
     ),
   ),
-  "ja-JP": mergeMessages(
+  "ja-JP": mergeLocalizedMessages(
+    "ja-JP",
     mergePartialMessages(
       designLocaleOverrides["ja-JP"],
       designRawLiteralOverrides["ja-JP"],
@@ -12543,6 +13731,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["ja-JP"],
       breakpointBarOverrides["ja-JP"],
       motionDockOverrides["ja-JP"],
+      designRuntimeIdentityAndBridgeOverrides["ja-JP"],
+      designComponentInstanceOverrides["ja-JP"],
+      designComponentSourceOverrides["ja-JP"],
       {
         root: {
           commandActions: "操作",
@@ -12593,7 +13784,8 @@ export const messagesByLocale = {
       },
     ),
   ),
-  "ko-KR": mergeMessages(
+  "ko-KR": mergeLocalizedMessages(
+    "ko-KR",
     mergePartialMessages(
       designLocaleOverrides["ko-KR"],
       designRawLiteralOverrides["ko-KR"],
@@ -12615,6 +13807,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["ko-KR"],
       breakpointBarOverrides["ko-KR"],
       motionDockOverrides["ko-KR"],
+      designRuntimeIdentityAndBridgeOverrides["ko-KR"],
+      designComponentInstanceOverrides["ko-KR"],
+      designComponentSourceOverrides["ko-KR"],
       {
         root: {
           commandActions: "작업",
@@ -12663,7 +13858,8 @@ export const messagesByLocale = {
       },
     ),
   ),
-  "pt-BR": mergeMessages(
+  "pt-BR": mergeLocalizedMessages(
+    "pt-BR",
     mergePartialMessages(
       designLocaleOverrides["pt-BR"],
       designRawLiteralOverrides["pt-BR"],
@@ -12685,6 +13881,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["pt-BR"],
       breakpointBarOverrides["pt-BR"],
       motionDockOverrides["pt-BR"],
+      designRuntimeIdentityAndBridgeOverrides["pt-BR"],
+      designComponentInstanceOverrides["pt-BR"],
+      designComponentSourceOverrides["pt-BR"],
       {
         root: {
           commandActions: "Ações",
@@ -12734,7 +13933,8 @@ export const messagesByLocale = {
       },
     ),
   ),
-  "hi-IN": mergeMessages(
+  "hi-IN": mergeLocalizedMessages(
+    "hi-IN",
     mergePartialMessages(
       designLocaleOverrides["hi-IN"],
       designRawLiteralOverrides["hi-IN"],
@@ -12756,6 +13956,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["hi-IN"],
       breakpointBarOverrides["hi-IN"],
       motionDockOverrides["hi-IN"],
+      designRuntimeIdentityAndBridgeOverrides["hi-IN"],
+      designComponentInstanceOverrides["hi-IN"],
+      designComponentSourceOverrides["hi-IN"],
       {
         root: {
           commandActions: "क्रियाएं",
@@ -12805,7 +14008,8 @@ export const messagesByLocale = {
       },
     ),
   ),
-  "ar-SA": mergeMessages(
+  "ar-SA": mergeLocalizedMessages(
+    "ar-SA",
     mergePartialMessages(
       designLocaleOverrides["ar-SA"],
       designRawLiteralOverrides["ar-SA"],
@@ -12827,6 +14031,9 @@ export const messagesByLocale = {
       designMotionAndBreakpointOverrides["ar-SA"],
       breakpointBarOverrides["ar-SA"],
       motionDockOverrides["ar-SA"],
+      designRuntimeIdentityAndBridgeOverrides["ar-SA"],
+      designComponentInstanceOverrides["ar-SA"],
+      designComponentSourceOverrides["ar-SA"],
       {
         root: {
           commandActions: "الإجراءات",
diff --git a/templates/design/app/i18n-keyboard-shortcuts.ts b/templates/design/app/i18n-keyboard-shortcuts.ts
new file mode 100644
index 0000000000..86337625b4
--- /dev/null
+++ b/templates/design/app/i18n-keyboard-shortcuts.ts
@@ -0,0 +1,577 @@
+import type { LocaleCode } from "@agent-native/core/client";
+
+interface KeyboardShortcutLabels {
+  title: string;
+  essential: string;
+  shape: string;
+  selection: string;
+  cursor: string;
+  transform: string;
+  arrange: string;
+  components: string;
+  hideUiDescription: string;
+  undoDescription: string;
+  redoDescription: string;
+}
+
+interface KeyboardKeyLabels {
+  or: string;
+  command: string;
+  control: string;
+  option: string;
+  alt: string;
+  shift: string;
+  arrowDown: string;
+  arrowLeft: string;
+  arrowRight: string;
+  arrowUp: string;
+  backspace: string;
+  delete: string;
+  enter: string;
+  tab: string;
+  questionMark: string;
+  backslash: string;
+  equals: string;
+  minus: string;
+  leftBracket: string;
+  rightBracket: string;
+}
+
+export const keyboardShortcutLabels = {
+  "zh-TW": {
+    title: "鍵盤快速鍵",
+    essential: "基本",
+    shape: "形狀",
+    selection: "選取",
+    cursor: "游標",
+    transform: "變形",
+    arrange: "排列",
+    components: "元件",
+    hideUiDescription: "立即按下以快速隱藏面板並專注於工作",
+    undoDescription: "逐步回復最近的設計變更",
+    redoDescription: "還原剛才復原的設計變更",
+  },
+  "zh-CN": {
+    title: "键盘快捷键",
+    essential: "基本",
+    shape: "形状",
+    selection: "选择",
+    cursor: "光标",
+    transform: "变换",
+    arrange: "排列",
+    components: "组件",
+    hideUiDescription: "立即按下以快速隐藏面板并专注于工作",
+    undoDescription: "逐步撤销最近的设计更改",
+    redoDescription: "恢复刚刚撤销的设计更改",
+  },
+  "es-ES": {
+    title: "Atajos de teclado",
+    essential: "Esenciales",
+    shape: "Formas",
+    selection: "Selección",
+    cursor: "Cursor",
+    transform: "Transformar",
+    arrange: "Organizar",
+    components: "Componentes",
+    hideUiDescription:
+      "Púlsalo ahora para ocultar los paneles y concentrarte en tu trabajo",
+    undoDescription: "Retrocede por el cambio de diseño más reciente",
+    redoDescription: "Restaura el cambio de diseño que acabas de deshacer",
+  },
+  "fr-FR": {
+    title: "Raccourcis clavier",
+    essential: "Essentiels",
+    shape: "Formes",
+    selection: "Sélection",
+    cursor: "Curseur",
+    transform: "Transformer",
+    arrange: "Organiser",
+    components: "Composants",
+    hideUiDescription:
+      "Appuyez maintenant pour masquer les panneaux et vous concentrer sur votre travail",
+    undoDescription: "Revenez sur votre dernière modification de design",
+    redoDescription:
+      "Restaurez la modification de design que vous venez d’annuler",
+  },
+  "de-DE": {
+    title: "Tastenkürzel",
+    essential: "Grundlagen",
+    shape: "Formen",
+    selection: "Auswahl",
+    cursor: "Zeiger",
+    transform: "Transformieren",
+    arrange: "Anordnen",
+    components: "Komponenten",
+    hideUiDescription:
+      "Drücke jetzt, um die Bereiche auszublenden und dich auf deine Arbeit zu konzentrieren",
+    undoDescription: "Mache die letzte Designänderung rückgängig",
+    redoDescription:
+      "Stelle die soeben rückgängig gemachte Designänderung wieder her",
+  },
+  "ja-JP": {
+    title: "キーボードショートカット",
+    essential: "基本",
+    shape: "シェイプ",
+    selection: "選択",
+    cursor: "カーソル",
+    transform: "変形",
+    arrange: "配置",
+    components: "コンポーネント",
+    hideUiDescription: "今すぐ押してパネルを隠し、作業に集中できます",
+    undoDescription: "直前のデザイン変更を元に戻します",
+    redoDescription: "元に戻したデザイン変更を復元します",
+  },
+  "ko-KR": {
+    title: "키보드 단축키",
+    essential: "필수",
+    shape: "도형",
+    selection: "선택",
+    cursor: "커서",
+    transform: "변형",
+    arrange: "정렬",
+    components: "컴포넌트",
+    hideUiDescription: "지금 눌러 패널을 빠르게 숨기고 작업에 집중하세요",
+    undoDescription: "가장 최근 디자인 변경을 되돌립니다",
+    redoDescription: "방금 실행 취소한 디자인 변경을 복원합니다",
+  },
+  "pt-BR": {
+    title: "Atalhos de teclado",
+    essential: "Essenciais",
+    shape: "Formas",
+    selection: "Seleção",
+    cursor: "Cursor",
+    transform: "Transformar",
+    arrange: "Organizar",
+    components: "Componentes",
+    hideUiDescription:
+      "Pressione agora para ocultar os painéis e focar no seu trabalho",
+    undoDescription: "Desfaça a alteração de design mais recente",
+    redoDescription:
+      "Restaure a alteração de design que você acabou de desfazer",
+  },
+  "hi-IN": {
+    title: "कीबोर्ड शॉर्टकट",
+    essential: "आवश्यक",
+    shape: "आकृति",
+    selection: "चयन",
+    cursor: "कर्सर",
+    transform: "रूपांतरण",
+    arrange: "व्यवस्थित करें",
+    components: "कॉम्पोनेंट",
+    hideUiDescription: "पैनल तुरंत छिपाकर अपने काम पर ध्यान देने के लिए इसे अभी दबाएँ",
+    undoDescription: "सबसे हाल के डिज़ाइन बदलाव को वापस करें",
+    redoDescription: "अभी वापस किए गए डिज़ाइन बदलाव को फिर से लागू करें",
+  },
+  "ar-SA": {
+    title: "اختصارات لوحة المفاتيح",
+    essential: "أساسي",
+    shape: "الأشكال",
+    selection: "التحديد",
+    cursor: "المؤشر",
+    transform: "التحويل",
+    arrange: "الترتيب",
+    components: "المكونات",
+    hideUiDescription: "اضغطه الآن لإخفاء اللوحات بسرعة والتركيز على عملك",
+    undoDescription: "تراجع عن أحدث تغيير في التصميم",
+    redoDescription: "استعد تغيير التصميم الذي تراجعت عنه للتو",
+  },
+} satisfies Record<Exclude<LocaleCode, "en-US">, KeyboardShortcutLabels>;
+
+export const keyboardKeyLabels = {
+  "zh-TW": {
+    or: "或",
+    command: "Command 鍵",
+    control: "Control 鍵",
+    option: "Option 鍵",
+    alt: "Alt 鍵",
+    shift: "Shift 鍵",
+    arrowDown: "下方向鍵",
+    arrowLeft: "左方向鍵",
+    arrowRight: "右方向鍵",
+    arrowUp: "上方向鍵",
+    backspace: "退格鍵",
+    delete: "刪除鍵",
+    enter: "Enter 鍵",
+    tab: "Tab 鍵",
+    questionMark: "問號",
+    backslash: "反斜線",
+    equals: "等號",
+    minus: "減號",
+    leftBracket: "左方括號",
+    rightBracket: "右方括號",
+  },
+  "zh-CN": {
+    or: "或",
+    command: "Command 键",
+    control: "Control 键",
+    option: "Option 键",
+    alt: "Alt 键",
+    shift: "Shift 键",
+    arrowDown: "向下箭头键",
+    arrowLeft: "向左箭头键",
+    arrowRight: "向右箭头键",
+    arrowUp: "向上箭头键",
+    backspace: "退格键",
+    delete: "删除键",
+    enter: "Enter 键",
+    tab: "Tab 键",
+    questionMark: "问号",
+    backslash: "反斜杠",
+    equals: "等号",
+    minus: "减号",
+    leftBracket: "左方括号",
+    rightBracket: "右方括号",
+  },
+  "es-ES": {
+    or: "o",
+    command: "Comando",
+    control: "Control",
+    option: "Opción",
+    alt: "Alt",
+    shift: "Mayús",
+    arrowDown: "Flecha abajo",
+    arrowLeft: "Flecha izquierda",
+    arrowRight: "Flecha derecha",
+    arrowUp: "Flecha arriba",
+    backspace: "Retroceso",
+    delete: "Suprimir",
+    enter: "Intro",
+    tab: "Tabulador",
+    questionMark: "Signo de interrogación",
+    backslash: "Barra invertida",
+    equals: "Igual",
+    minus: "Menos",
+    leftBracket: "Corchete izquierdo",
+    rightBracket: "Corchete derecho",
+  },
+  "fr-FR": {
+    or: "ou",
+    command: "Commande",
+    control: "Contrôle",
+    option: "Option",
+    alt: "Alt",
+    shift: "Majuscule",
+    arrowDown: "Flèche vers le bas",
+    arrowLeft: "Flèche vers la gauche",
+    arrowRight: "Flèche vers la droite",
+    arrowUp: "Flèche vers le haut",
+    backspace: "Retour arrière",
+    delete: "Supprimer",
+    enter: "Entrée",
+    tab: "Tabulation",
+    questionMark: "Point d’interrogation",
+    backslash: "Barre oblique inverse",
+    equals: "Égal",
+    minus: "Moins",
+    leftBracket: "Crochet gauche",
+    rightBracket: "Crochet droit",
+  },
+  "de-DE": {
+    or: "oder",
+    command: "Befehl",
+    control: "Steuerung",
+    option: "Wahltaste",
+    alt: "Alt",
+    shift: "Umschalt",
+    arrowDown: "Pfeil nach unten",
+    arrowLeft: "Pfeil nach links",
+    arrowRight: "Pfeil nach rechts",
+    arrowUp: "Pfeil nach oben",
+    backspace: "Rücktaste",
+    delete: "Entfernen",
+    enter: "Eingabetaste",
+    tab: "Tabulatortaste",
+    questionMark: "Fragezeichen",
+    backslash: "Umgekehrter Schrägstrich",
+    equals: "Gleichheitszeichen",
+    minus: "Minuszeichen",
+    leftBracket: "Linke eckige Klammer",
+    rightBracket: "Rechte eckige Klammer",
+  },
+  "ja-JP": {
+    or: "または",
+    command: "Commandキー",
+    control: "Controlキー",
+    option: "Optionキー",
+    alt: "Altキー",
+    shift: "Shiftキー",
+    arrowDown: "下矢印キー",
+    arrowLeft: "左矢印キー",
+    arrowRight: "右矢印キー",
+    arrowUp: "上矢印キー",
+    backspace: "Backspaceキー",
+    delete: "Deleteキー",
+    enter: "Enterキー",
+    tab: "Tabキー",
+    questionMark: "疑問符",
+    backslash: "バックスラッシュ",
+    equals: "等号",
+    minus: "マイナス",
+    leftBracket: "左角括弧",
+    rightBracket: "右角括弧",
+  },
+  "ko-KR": {
+    or: "또는",
+    command: "Command 키",
+    control: "Control 키",
+    option: "Option 키",
+    alt: "Alt 키",
+    shift: "Shift 키",
+    arrowDown: "아래쪽 화살표 키",
+    arrowLeft: "왼쪽 화살표 키",
+    arrowRight: "오른쪽 화살표 키",
+    arrowUp: "위쪽 화살표 키",
+    backspace: "백스페이스 키",
+    delete: "Delete 키",
+    enter: "Enter 키",
+    tab: "Tab 키",
+    questionMark: "물음표",
+    backslash: "백슬래시",
+    equals: "등호",
+    minus: "빼기 기호",
+    leftBracket: "왼쪽 대괄호",
+    rightBracket: "오른쪽 대괄호",
+  },
+  "pt-BR": {
+    or: "ou",
+    command: "Comando",
+    control: "Control",
+    option: "Opção",
+    alt: "Alt",
+    shift: "Shift",
+    arrowDown: "Seta para baixo",
+    arrowLeft: "Seta para a esquerda",
+    arrowRight: "Seta para a direita",
+    arrowUp: "Seta para cima",
+    backspace: "Backspace",
+    delete: "Excluir",
+    enter: "Enter",
+    tab: "Tab",
+    questionMark: "Ponto de interrogação",
+    backslash: "Barra invertida",
+    equals: "Igual",
+    minus: "Menos",
+    leftBracket: "Colchete esquerdo",
+    rightBracket: "Colchete direito",
+  },
+  "hi-IN": {
+    or: "या",
+    command: "Command कुंजी",
+    control: "Control कुंजी",
+    option: "Option कुंजी",
+    alt: "Alt कुंजी",
+    shift: "Shift कुंजी",
+    arrowDown: "नीचे तीर कुंजी",
+    arrowLeft: "बायाँ तीर कुंजी",
+    arrowRight: "दायाँ तीर कुंजी",
+    arrowUp: "ऊपर तीर कुंजी",
+    backspace: "Backspace कुंजी",
+    delete: "Delete कुंजी",
+    enter: "Enter कुंजी",
+    tab: "Tab कुंजी",
+    questionMark: "प्रश्न चिह्न",
+    backslash: "बैकस्लैश",
+    equals: "बराबर चिह्न",
+    minus: "ऋण चिह्न",
+    leftBracket: "बायाँ कोष्ठक",
+    rightBracket: "दायाँ कोष्ठक",
+  },
+  "ar-SA": {
+    or: "أو",
+    command: "مفتاح Command",
+    control: "مفتاح Control",
+    option: "مفتاح Option",
+    alt: "مفتاح Alt",
+    shift: "مفتاح Shift",
+    arrowDown: "مفتاح السهم لأسفل",
+    arrowLeft: "مفتاح السهم لليسار",
+    arrowRight: "مفتاح السهم لليمين",
+    arrowUp: "مفتاح السهم لأعلى",
+    backspace: "مفتاح Backspace",
+    delete: "مفتاح Delete",
+    enter: "مفتاح Enter",
+    tab: "مفتاح Tab",
+    questionMark: "علامة الاستفهام",
+    backslash: "الشرطة المائلة العكسية",
+    equals: "علامة يساوي",
+    minus: "علامة الطرح",
+    leftBracket: "القوس المربع الأيسر",
+    rightBracket: "القوس المربع الأيمن",
+  },
+} satisfies Record<Exclude<LocaleCode, "en-US">, KeyboardKeyLabels>;
+
+interface KeyboardMessagesSource {
+  editPanel: {
+    properties: string;
+    sections: {
+      layout: string;
+      autoLayout: string;
+      fill: string;
+      stroke: string;
+      codeConfidence: string;
+    };
+    labels: { align: string };
+    alignOptions: { start: string; center: string; end: string };
+    textDecorations: { underline: string; strikethrough: string };
+  };
+  designEditor: {
+    leftRail: { tools: string; assets: string };
+    modes: { edit: string; draw: string };
+    tools: Record<
+      | "move"
+      | "frame"
+      | "text"
+      | "pen"
+      | "hand"
+      | "scale"
+      | "rect"
+      | "ellipse"
+      | "line"
+      | "arrow",
+      string
+    >;
+    undo: string;
+    redo: string;
+    view: string;
+    zoom: string;
+    zoomIn: string;
+    zoomOut: string;
+    fitToScreen: string;
+    pinComment: string;
+    downloadPng: string;
+    close: string;
+    componentInstances: { detach: string };
+  };
+  layersPanel: {
+    title: string;
+    screens: string;
+    searchPlaceholder: string;
+    copy: string;
+    pasteHere: string;
+    pasteToReplace: string;
+    duplicate: string;
+    delete: string;
+    rename: string;
+    flipHorizontal: string;
+    flipVertical: string;
+    bringForward: string;
+    bringToFront: string;
+    sendBackward: string;
+    sendToBack: string;
+    group: string;
+    ungroup: string;
+    frameSelection: string;
+  };
+}
+
+export function attachLocalizedKeyboardShortcuts<
+  T extends KeyboardMessagesSource,
+>(
+  messages: T,
+  labels: KeyboardShortcutLabels,
+  keyLabels: KeyboardKeyLabels,
+): T {
+  const d = messages.designEditor;
+  const layers = messages.layersPanel;
+  const edit = messages.editPanel;
+  return {
+    ...messages,
+    designEditor: {
+      ...d,
+      keyboardShortcuts: {
+        title: labels.title,
+        close: `${d.close}: ${labels.title}`,
+        codeContext: edit.sections.codeConfidence,
+        screenContext: layers.screens,
+        keys: keyLabels,
+        descriptions: {
+          toggleUi: labels.hideUiDescription,
+          undo: labels.undoDescription,
+          redo: labels.redoDescription,
+        },
+        categories: {
+          essential: labels.essential,
+          tools: d.leftRail.tools,
+          view: d.view,
+          zoom: d.zoom,
+          text: d.tools.text,
+          shape: labels.shape,
+          selection: labels.selection,
+          cursor: labels.cursor,
+          edit: d.modes.edit,
+          transform: labels.transform,
+          arrange: labels.arrange,
+          components: labels.components,
+          layout: edit.sections.layout,
+        },
+        commands: {
+          showShortcuts: labels.title,
+          undo: d.undo,
+          redo: d.redo,
+          moveTool: d.tools.move,
+          frameTool: d.tools.frame,
+          textTool: d.tools.text,
+          penTool: d.tools.pen,
+          handTool: d.tools.hand,
+          scaleTool: d.tools.scale,
+          commentTool: d.pinComment,
+          drawTool: d.modes.draw,
+          showLayers: layers.title,
+          showAssets: d.leftRail.assets,
+          toggleUi: d.view,
+          toggleComments: d.pinComment,
+          zoomIn: d.zoomIn,
+          zoomOut: d.zoomOut,
+          zoomReset: `${d.zoom} 100%`,
+          zoomFit: d.fitToScreen,
+          zoomSelection: `${d.zoom}: ${labels.selection}`,
+          underline: edit.textDecorations.underline,
+          strikethrough: edit.textDecorations.strikethrough,
+          rectangle: d.tools.rect,
+          ellipse: d.tools.ellipse,
+          line: d.tools.line,
+          arrow: d.tools.arrow,
+          selectAll: labels.selection,
+          selectParent: `${labels.selection}: ${layers.title}`,
+          enterSelection: labels.selection,
+          nextSibling: `${labels.selection} →`,
+          previousSibling: `← ${labels.selection}`,
+          nextScreen: `${layers.screens} →`,
+          previousScreen: `← ${layers.screens}`,
+          nudge: d.tools.move,
+          nudgeLarge: `${d.tools.move} 10`,
+          copy: layers.copy,
+          copyPng: `${layers.copy} PNG`,
+          cut: layers.delete,
+          paste: layers.pasteHere,
+          pasteOver: layers.pasteToReplace,
+          copyProperties: `${layers.copy}: ${edit.properties}`,
+          pasteProperties: `${layers.pasteHere}: ${edit.properties}`,
+          pasteReplace: layers.pasteToReplace,
+          duplicate: layers.duplicate,
+          delete: layers.delete,
+          rename: layers.rename,
+          find: layers.searchPlaceholder,
+          flipHorizontal: layers.flipHorizontal,
+          flipVertical: layers.flipVertical,
+          swapFillStroke: `${edit.sections.fill} / ${edit.sections.stroke}`,
+          bringForward: layers.bringForward,
+          sendBackward: layers.sendBackward,
+          bringFront: layers.bringToFront,
+          sendBack: layers.sendToBack,
+          alignLeft: `${edit.labels.align}: ${edit.alignOptions.start}`,
+          alignRight: `${edit.labels.align}: ${edit.alignOptions.end}`,
+          alignTop: `${edit.labels.align}: ${edit.alignOptions.start}`,
+          alignBottom: `${edit.labels.align}: ${edit.alignOptions.end}`,
+          tidy: edit.sections.autoLayout,
+          createComponent: labels.components,
+          detachInstance: d.componentInstances.detach,
+          group: layers.group,
+          ungroup: layers.ungroup,
+          frameSelection: layers.frameSelection,
+          autoLayout: edit.sections.autoLayout,
+        },
+      },
+    },
+  } as T;
+}
diff --git a/templates/design/app/i18n/zh-TW.ts b/templates/design/app/i18n/zh-TW.ts
index a09d53f960..f1ddecb2cc 100644
--- a/templates/design/app/i18n/zh-TW.ts
+++ b/templates/design/app/i18n/zh-TW.ts
@@ -1,3 +1,9 @@
+import {
+  attachLocalizedKeyboardShortcuts,
+  keyboardKeyLabels,
+  keyboardShortcutLabels,
+} from "../i18n-keyboard-shortcuts";
+
 const messages = {
   root: {
     commandActions: "操作",
@@ -256,6 +262,22 @@ const messages = {
       right: "正確的",
       justify: "證明合法",
     },
+    textDecorations: {
+      underline: "底線",
+      strikethrough: "刪除線",
+    },
+    textCases: {
+      none: "無",
+      uppercase: "大寫",
+      lowercase: "小寫",
+      capitalize: "單字首字母大寫",
+    },
+    typographyDetails: {
+      basicsTab: "基本",
+      detailsTab: "詳細資料",
+      decorationLabel: "文字裝飾",
+      caseLabel: "大小寫",
+    },
     flexDirections: {
       row: "排",
       column: "柱子",
@@ -322,6 +344,41 @@ const messages = {
   },
   designEditor: {
     askAgent: "詢問代理",
+    componentInstances: {
+      selectLayer: "選取圖層",
+      goToMain: "前往主要元件",
+      swap: "交換實例",
+      detach: "卸離實例",
+      searchComponents: "搜尋元件…",
+      loading: "載入中…",
+      noOtherComponents: "找不到其他元件",
+      goToMainUnavailable: "目前無法前往主要元件。",
+      onlyKnownInstance: "這是此元件唯一已知的實例。",
+      resolveMainFailed: "無法解析主要元件。",
+      detachFailed: "無法卸離此實例。",
+      detached: "實例已卸離。",
+      swapFailed: "無法交換此實例。",
+      swappedFor: "已交換為「{{name}}」。",
+      openPanelNudge: "請使用「元件」面板中的「交換實例」選擇器。",
+      openPanelFailed: "無法開啟元件面板。",
+    },
+    makeItRealCard: {
+      open: "開啟",
+      choose: "選擇",
+      connect: "連接",
+      generating: "生成中",
+      generate: "生成",
+      migrationFailed: "遷移失敗，請再試一次。",
+    },
+    componentProps: {
+      alpineTooComplexToEdit:
+        "無法安全地就地編輯此屬性——此元件的 Alpine 狀態過於複雜。請改為編輯原始碼。",
+      label: "屬性",
+    },
+    componentSource: {
+      editSource: "編輯元件原始碼",
+      needsConnectedApp: "跳轉原始碼需要連接應用程式",
+    },
     breakpointBar: {
       base: "基礎",
       editBaseWidth: "編輯基礎寬度",
@@ -427,6 +484,11 @@ const messages = {
       figmaPasteDescription:
         "在 Figma 複製畫框或圖層，然後貼到 Design 畫布。Design 會匯入可見的剪貼簿 HTML。",
       figmaPasteTarget: "貼到畫布",
+      figmaPasteApiKeyHint: "連結您的 Figma 存取權杖以取得精確的節點匯入。",
+      figmaPasteMatchGuidance:
+        "無法比對到特定的 Figma 節點。請改貼上畫框連結以進行精確匯入。",
+      figmaPasteRestLabel: "透過 Figma API 匯入",
+      figmaPasteHtmlLabel: "從剪貼簿預覽匯入",
       figUploadTitle: "上傳 .fig",
       figUploadDescription:
         "只匯出需要的畫框。含有許多嵌入圖片的大型檔案可能超過匯入限制。",
@@ -648,6 +710,12 @@ const messages = {
       openScreenSvg: "匯出 SVG 前請先開啟一個螢幕",
       svgDownloaded: "SVG 已下載",
       svgExportError: "無法匯出 SVG",
+      figmaSvgCopied: "已複製為 Figma SVG",
+      figmaSvgUnsupported: "此瀏覽器無法將 SVG 圖像複製到剪貼簿",
+      figmaSvgBlocked: "請允許存取剪貼簿以複製此 SVG",
+      figmaSvgWriteError: "無法將 SVG 複製到剪貼簿",
+      figmaSvgRenderError: "無法建立 Figma SVG",
+      figmaSvgExportError: "無法匯出 Figma SVG",
       screenDuplicated: "畫面已複製",
       screenDuplicateError: "無法複製畫面",
       copied: "已複製",
@@ -665,6 +733,8 @@ const messages = {
       undoSkippedConcurrentEdit: "已略過復原 — 其他人移動了該項目",
       redoSkippedConcurrentEdit: "已略過重做 — 其他人移動了該項目",
       autoLayoutScreensUnsupported: "新增自動布局不適用於畫面",
+      reactSourceAnchorsLoading:
+        "React 原始碼錨點仍在載入中。請等本機應用程式完成渲染後再試一次。",
     },
   },
   layersPanel: {
@@ -701,6 +771,14 @@ const messages = {
     frameSelection: "將選取範圍建立畫框",
     flipHorizontal: "水平翻轉",
     flipVertical: "垂直翻轉",
+    dragGhostCount: "{{count}} 個圖層",
+  },
+  designCanvas: {
+    localBridge: {
+      confirmationRetryExhausted: "多次嘗試後，即時編輯器橋接器仍未確認連線。",
+      connectionNotConfirmed:
+        "即時編輯器橋接器未確認連線。本機開發伺服器是否仍在執行？",
+    },
   },
   multiScreenCanvas: {
     duplicate: "複製",
@@ -756,6 +834,8 @@ const messages = {
     assetsNoImageUrl: "Assets 未回傳圖片 URL。",
     assetAdded: "新增資產",
     failedToUploadFile: "上傳檔案失敗",
+    failedToSubmitPrompt: "無法提交提示",
+    skipPrompt: "略過提示",
     designSystem: "Design系統",
     noDesignSystem: "沒有設計系統",
     newDesignSystem: "新",
@@ -784,8 +864,11 @@ const messages = {
     offline: "離線",
     saving: "儲存...",
     clearedAllAnnotations: "已清除所有批注",
+    annotationsDiscardedOnViewChange:
+      "離開此檢視畫面時，{{count}} 則未傳送的批注已被捨棄。",
     undo: "復原",
     send: "傳送",
+    sendingDrawing: "正在傳送…",
     commentSent: "評論已傳送",
     comment: "評論",
     annotationQueue: "註記佇列",
@@ -799,6 +882,9 @@ const messages = {
     nearText: "靠近「{{text}}」",
     submitShortcut: "{{mod}}+Enter 送出",
     queue: "排隊",
+    queuedCommentsDiscarded:
+      "{{count}} 個未傳送的評論草稿已在你離開此檢視時捨棄。",
+    staleAnchorDetail: "在畫布上已找不到原始元素。",
     pinStatus: {
       deterministic: {
         label: "確定性",
@@ -1085,4 +1171,8 @@ const messages = {
   },
 };
 
-export default messages;
+export default attachLocalizedKeyboardShortcuts(
+  messages,
+  keyboardShortcutLabels["zh-TW"],
+  keyboardKeyLabels["zh-TW"],
+);
diff --git a/templates/design/app/lib/agent-chat.test.ts b/templates/design/app/lib/agent-chat.test.ts
index a71a09d45d..c90261bf73 100644
--- a/templates/design/app/lib/agent-chat.test.ts
+++ b/templates/design/app/lib/agent-chat.test.ts
@@ -1,12 +1,20 @@
 import { describe, expect, it, vi } from "vitest";
 
 const sendToAgentChatMock = vi.hoisted(() => vi.fn(() => "tab-design"));
+const sendToAgentChatAndConfirmMock = vi.hoisted(() =>
+  vi.fn(() => Promise.resolve({ tabId: "tab-design", delivered: true })),
+);
 
 vi.mock("@agent-native/core/client", () => ({
   sendToAgentChat: sendToAgentChatMock,
+  sendToAgentChatAndConfirm: sendToAgentChatAndConfirmMock,
 }));
 
-import { DESIGN_CHAT_STORAGE_KEY, sendToDesignAgentChat } from "./agent-chat";
+import {
+  DESIGN_CHAT_STORAGE_KEY,
+  sendToDesignAgentChat,
+  sendToDesignAgentChatAndConfirm,
+} from "./agent-chat";
 
 describe("Design agent chat routing", () => {
   it("namespaces Design chat state", () => {
@@ -27,4 +35,25 @@ describe("Design agent chat routing", () => {
       chatTarget: "local",
     });
   });
+
+  it("forces the ack-confirmed handoff to the local app chat and returns delivery status", async () => {
+    const result = await sendToDesignAgentChatAndConfirm(
+      {
+        message: "Apply this annotation",
+        submit: true,
+        chatTarget: "auto",
+      },
+      { timeoutMs: 1234 },
+    );
+
+    expect(result).toEqual({ tabId: "tab-design", delivered: true });
+    expect(sendToAgentChatAndConfirmMock).toHaveBeenCalledWith(
+      {
+        message: "Apply this annotation",
+        submit: true,
+        chatTarget: "local",
+      },
+      { timeoutMs: 1234 },
+    );
+  });
 });
diff --git a/templates/design/app/lib/agent-chat.ts b/templates/design/app/lib/agent-chat.ts
index 258a615be0..6a12d3bec8 100644
--- a/templates/design/app/lib/agent-chat.ts
+++ b/templates/design/app/lib/agent-chat.ts
@@ -1,6 +1,8 @@
 import {
   sendToAgentChat,
+  sendToAgentChatAndConfirm,
   type AgentChatMessage,
+  type SendToAgentChatAndConfirmResult,
 } from "@agent-native/core/client";
 
 export const DESIGN_CHAT_STORAGE_KEY = "design";
@@ -11,3 +13,24 @@ export function sendToDesignAgentChat(opts: AgentChatMessage): string {
     chatTarget: "local",
   });
 }
+
+/**
+ * Ack-confirmed variant of `sendToDesignAgentChat`. Resolves once the
+ * message either became a visible chat turn (`delivered: true`) or was
+ * definitively rejected/timed out (`delivered: false`) — use this wherever
+ * the caller owns state (draw overlay strokes, queued comment pins) that
+ * must not be discarded on a silent drop. See the `design-canvas/
+ * annotation-submit.ts` docblock for the contract this backs.
+ */
+export function sendToDesignAgentChatAndConfirm(
+  opts: AgentChatMessage,
+  options?: { timeoutMs?: number },
+): Promise<SendToAgentChatAndConfirmResult> {
+  return sendToAgentChatAndConfirm(
+    {
+      ...opts,
+      chatTarget: "local",
+    },
+    options,
+  );
+}
diff --git a/templates/design/app/lib/design-import.ts b/templates/design/app/lib/design-import.ts
index 524e66b909..35d346d10c 100644
--- a/templates/design/app/lib/design-import.ts
+++ b/templates/design/app/lib/design-import.ts
@@ -1,10 +1,34 @@
 import type { PortableStyleSnapshot } from "@/components/design/types";
 
+export interface FigmaFidelityReport {
+  exactCount: number;
+  approximated: Array<{
+    nodeId: string;
+    nodeName?: string;
+    nodeType?: string;
+    notes: string[];
+  }>;
+  imageFallbacks: Array<{
+    nodeId: string;
+    nodeName?: string;
+    nodeType?: string;
+    notes: string[];
+  }>;
+}
+
 export interface ImportResult {
   designId?: string;
   files?: Array<{ id: string; filename: string }>;
   warnings?: string[];
   error?: string;
+  /** Set by import-figma-clipboard: which path actually produced the screen(s). */
+  strategy?: "restNodes" | "htmlFallback";
+  /** Set by import-figma-clipboard when it fell back because no Figma token is configured. */
+  figmaApiKeyMissing?: boolean;
+  /** Set by import-figma-clipboard when it fell back: why the REST match didn't happen. */
+  matchStatus?: "matched" | "ambiguous" | "none" | "error";
+  fidelityReport?: FigmaFidelityReport;
+  guidance?: string;
 }
 
 export const VISUAL_EDIT_CONNECT_COMMAND =
diff --git a/templates/design/app/lib/figma-clipboard.test.ts b/templates/design/app/lib/figma-clipboard.test.ts
new file mode 100644
index 0000000000..8c10b304cb
--- /dev/null
+++ b/templates/design/app/lib/figma-clipboard.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  decideFigmaPasteStrategy,
+  extractFigmeta,
+  resolveFigmaPasteImportCall,
+} from "./figma-clipboard";
+
+function base64Json(value: unknown): string {
+  return btoa(JSON.stringify(value));
+}
+
+describe("extractFigmeta", () => {
+  it("decodes a figmeta marker wrapping base64 JSON", () => {
+    const payload = { fileKey: "abcDEF12345", pasteID: 42, dataType: "scene" };
+    const html = `<span data-metadata="(figmeta)${base64Json(payload)}(/figmeta)"></span>`;
+    expect(extractFigmeta(html)).toEqual(payload);
+  });
+
+  it("decodes a figmeta marker present as a bare HTML comment (not inside an attribute)", () => {
+    const payload = { fileKey: "xyzKey999" };
+    const html = `<!--(figmeta)${base64Json(payload)}(/figmeta)--><div>Layer</div>`;
+    expect(extractFigmeta(html)).toEqual({ fileKey: "xyzKey999" });
+  });
+
+  it("falls back to treating a bare data-metadata value as base64 JSON with no wrapper markers", () => {
+    const payload = { fileKey: "bareKey123" };
+    const html = `<span data-metadata="${base64Json(payload)}"></span>`;
+    expect(extractFigmeta(html)).toEqual({ fileKey: "bareKey123" });
+  });
+
+  it("only keeps the known figmeta fields and trims the file key", () => {
+    const html = `<span data-metadata="(figmeta)${base64Json({
+      fileKey: "  spacedKey1 ",
+      pasteID: 7,
+      dataType: "scene",
+      extraField: "ignored",
+    })}(/figmeta)"></span>`;
+    expect(extractFigmeta(html)).toEqual({
+      fileKey: "spacedKey1",
+      pasteID: 7,
+      dataType: "scene",
+    });
+  });
+
+  it("returns null for corrupted base64 inside the marker", () => {
+    const html =
+      '<span data-metadata="(figmeta)not-valid-base64!!!(/figmeta)"></span>';
+    expect(extractFigmeta(html)).toBeNull();
+  });
+
+  it("returns null for valid base64 that isn't JSON", () => {
+    const html = `<span data-metadata="(figmeta)${btoa("just some text")}(/figmeta)"></span>`;
+    expect(extractFigmeta(html)).toBeNull();
+  });
+
+  it("returns null for JSON missing a fileKey", () => {
+    const html = `<span data-metadata="(figmeta)${base64Json({ pasteID: 1 })}(/figmeta)"></span>`;
+    expect(extractFigmeta(html)).toBeNull();
+  });
+
+  it("returns null when there is no figmeta marker or data-metadata attribute at all", () => {
+    expect(extractFigmeta("<div>Just a normal paste</div>")).toBeNull();
+  });
+
+  it("returns null for empty/undefined/null input", () => {
+    expect(extractFigmeta("")).toBeNull();
+    expect(extractFigmeta(undefined)).toBeNull();
+    expect(extractFigmeta(null)).toBeNull();
+  });
+});
+
+describe("decideFigmaPasteStrategy", () => {
+  const figmeta = { fileKey: "abcDEF12345" };
+
+  it("is not-figma when there is no figmeta, regardless of key status", () => {
+    expect(decideFigmaPasteStrategy(null, "configured")).toBe("not-figma");
+    expect(decideFigmaPasteStrategy(null, "missing")).toBe("not-figma");
+    expect(decideFigmaPasteStrategy(null, "unknown")).toBe("not-figma");
+    expect(decideFigmaPasteStrategy(null)).toBe("not-figma");
+  });
+
+  it("attempts REST when figmeta is present and the key is configured", () => {
+    expect(decideFigmaPasteStrategy(figmeta, "configured")).toBe("rest");
+  });
+
+  it("skips straight to the HTML fallback when the key is known-missing", () => {
+    expect(decideFigmaPasteStrategy(figmeta, "missing")).toBe("html-fallback");
+  });
+
+  it("optimistically attempts REST when the key status isn't known client-side", () => {
+    expect(decideFigmaPasteStrategy(figmeta, "unknown")).toBe("rest");
+    expect(decideFigmaPasteStrategy(figmeta)).toBe("rest");
+  });
+});
+
+describe("resolveFigmaPasteImportCall", () => {
+  it("routes a figmeta-bearing paste to import-figma-clipboard", () => {
+    const payload = { fileKey: "abcDEF12345", pasteID: 1 };
+    const html = `<span data-metadata="(figmeta)${base64Json(payload)}(/figmeta)"></span><div>Hero</div>`;
+    const call = resolveFigmaPasteImportCall(html);
+    expect(call).toEqual({
+      action: "import-figma-clipboard",
+      payload: {
+        figmetaFileKey: "abcDEF12345",
+        clipboardHtml: html,
+        originalName: "figma-paste.html",
+      },
+    });
+  });
+
+  it("routes a paste with no figmeta to the legacy import-design-source action", () => {
+    const html = '<div data-buffer="(figma)">frame</div>';
+    const call = resolveFigmaPasteImportCall(html, "custom-name.html");
+    expect(call).toEqual({
+      action: "import-design-source",
+      payload: {
+        sourceType: "figma-paste-html",
+        content: html,
+        originalName: "custom-name.html",
+      },
+    });
+  });
+});
diff --git a/templates/design/app/lib/figma-clipboard.ts b/templates/design/app/lib/figma-clipboard.ts
new file mode 100644
index 0000000000..b036942d11
--- /dev/null
+++ b/templates/design/app/lib/figma-clipboard.ts
@@ -0,0 +1,157 @@
+/**
+ * Client-side Figma clipboard helpers: decode the `figmeta` marker Figma
+ * writes into a copy's clipboard HTML, and decide which action a paste
+ * should route through.
+ *
+ * Figma wraps a small base64 JSON payload (`{"fileKey","pasteID","dataType"}`)
+ * between literal `(figmeta)`/`(/figmeta)` markers — the same markers
+ * `hasFigmaClipboardPayload` in `design-import.ts` already scans for to detect
+ * a Figma paste at all. Some Figma clients may instead put that same base64
+ * blob directly in the `data-metadata` attribute with no wrapper markers, so
+ * `extractFigmeta` tries both, defensively, and never throws — any malformed
+ * input just means "not a decodable Figma paste".
+ *
+ * Important caveat carried through to the server: `figmeta` has no node ids
+ * (only a `fileKey`), and `pasteID` is an ephemeral, server-side identifier
+ * that isn't resolvable to a node through the public REST API. So a plain
+ * clipboard paste can only ever get an exact node import on a best-effort,
+ * heuristic match (see `server/lib/figma-clipboard-match.ts`) — a copied
+ * frame LINK (which carries a real `node-id`) is the only guaranteed-exact
+ * path (`import-figma-frame`).
+ */
+
+export interface FigmetaPayload {
+  fileKey: string;
+  pasteID?: number;
+  dataType?: string;
+}
+
+const FIGMETA_MARKER_RE = /\(figmeta\)([^(]*?)\(\/figmeta\)/i;
+const DATA_METADATA_ATTR_RE = /\bdata-metadata\s*=\s*(["'])([\s\S]*?)\1/i;
+
+function decodeBase64Json(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  try {
+    const decoded =
+      typeof atob === "function"
+        ? atob(trimmed)
+        : Buffer.from(trimmed, "base64").toString("utf8");
+    return JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+}
+
+function isFigmetaPayload(value: unknown): value is FigmetaPayload {
+  if (!value || typeof value !== "object") return false;
+  const fileKey = (value as { fileKey?: unknown }).fileKey;
+  return typeof fileKey === "string" && fileKey.trim().length > 0;
+}
+
+function normalizeFigmetaPayload(value: FigmetaPayload): FigmetaPayload {
+  const payload: FigmetaPayload = { fileKey: value.fileKey.trim() };
+  if (typeof value.pasteID === "number") payload.pasteID = value.pasteID;
+  if (typeof value.dataType === "string") payload.dataType = value.dataType;
+  return payload;
+}
+
+/**
+ * Extracts and decodes the `figmeta` payload from a clipboard's raw HTML (or
+ * plain text), if present. Returns `null` for anything that isn't a
+ * decodable Figma `figmeta` marker — this never throws, so callers can run it
+ * unconditionally on every paste.
+ */
+export function extractFigmeta(
+  html: string | null | undefined,
+): FigmetaPayload | null {
+  if (!html) return null;
+
+  const markerMatch = html.match(FIGMETA_MARKER_RE);
+  if (markerMatch?.[1]) {
+    const parsed = decodeBase64Json(markerMatch[1]);
+    if (isFigmetaPayload(parsed)) return normalizeFigmetaPayload(parsed);
+  }
+
+  // Defensive fallback: some clients may emit data-metadata as a bare base64
+  // blob with no (figmeta)...(/figmeta) wrapper markers.
+  const attrMatch = html.match(DATA_METADATA_ATTR_RE);
+  if (attrMatch?.[2]) {
+    const parsed = decodeBase64Json(attrMatch[2]);
+    if (isFigmetaPayload(parsed)) return normalizeFigmetaPayload(parsed);
+  }
+
+  return null;
+}
+
+export type FigmaApiKeyStatus = "configured" | "missing" | "unknown";
+export type FigmaPasteStrategy = "rest" | "html-fallback" | "not-figma";
+
+/**
+ * Pure decision matrix for what a paste should attempt, given whether it
+ * decoded a `figmeta` payload and (if known) whether the Figma access token
+ * is configured:
+ *
+ * - No `figmeta` -> not a Figma paste at all (`"not-figma"`).
+ * - `figmeta` present but the key is known-missing -> skip the REST attempt
+ *   entirely and go straight to the legacy HTML path (`"html-fallback"`).
+ * - `figmeta` present and the key is configured, or its status isn't known
+ *   client-side -> attempt the REST import (`"rest"`). The server is the
+ *   authority on whether the key actually works; passing `"unknown"` here
+ *   just means "try REST, let the server fall back for real if it can't."
+ */
+export function decideFigmaPasteStrategy(
+  figmeta: FigmetaPayload | null,
+  apiKeyStatus: FigmaApiKeyStatus = "unknown",
+): FigmaPasteStrategy {
+  if (!figmeta) return "not-figma";
+  if (apiKeyStatus === "missing") return "html-fallback";
+  return "rest";
+}
+
+export type FigmaPasteImportCall =
+  | {
+      action: "import-figma-clipboard";
+      payload: {
+        figmetaFileKey: string;
+        clipboardHtml: string;
+        originalName?: string;
+      };
+    }
+  | {
+      action: "import-design-source";
+      payload: {
+        sourceType: "figma-paste-html";
+        content: string;
+        originalName?: string;
+      };
+    };
+
+/**
+ * Resolves the actual action name + payload a paste should call, given the
+ * raw clipboard HTML. Used by both the canvas-level paste listener and the
+ * Import panel's Figma-paste target so the two call sites stay in lockstep.
+ */
+export function resolveFigmaPasteImportCall(
+  content: string,
+  originalName = "figma-paste.html",
+): FigmaPasteImportCall {
+  const figmeta = extractFigmeta(content);
+  const strategy = decideFigmaPasteStrategy(figmeta, "unknown");
+
+  if (strategy === "not-figma") {
+    return {
+      action: "import-design-source",
+      payload: { sourceType: "figma-paste-html", content, originalName },
+    };
+  }
+
+  return {
+    action: "import-figma-clipboard",
+    payload: {
+      figmetaFileKey: figmeta!.fileKey,
+      clipboardHtml: content,
+      originalName,
+    },
+  };
+}
diff --git a/templates/design/app/lib/figma-svg-copy.test.ts b/templates/design/app/lib/figma-svg-copy.test.ts
new file mode 100644
index 0000000000..889193ade0
--- /dev/null
+++ b/templates/design/app/lib/figma-svg-copy.test.ts
@@ -0,0 +1,193 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  canCopyFigmaSvgToClipboard,
+  copyDesignAsFigmaSvg,
+  FigmaSvgCopyError,
+  type FigmaSvgCopyEnvironment,
+  type FigmaSvgExportActionResult,
+} from "./figma-svg-copy";
+
+function clipboardEnvironment(options?: {
+  write?: (items: ClipboardItem[]) => Promise<void>;
+  writeText?: (text: string) => Promise<void>;
+  withClipboardItem?: boolean;
+  callExportAction?: (params: unknown) => Promise<FigmaSvgExportActionResult>;
+}) {
+  const constructed: Array<Record<string, Blob | Promise<Blob>>> = [];
+  class FakeClipboardItem {
+    static supports() {
+      return true;
+    }
+
+    constructor(items: Record<string, Blob | Promise<Blob>>) {
+      constructed.push(items);
+    }
+  }
+  const write = vi.fn(options?.write ?? (async () => undefined));
+  const writeText = options?.writeText ? vi.fn(options.writeText) : undefined;
+  const environment = {
+    clipboard: { write, writeText },
+    ClipboardItem:
+      options?.withClipboardItem === false ? null : FakeClipboardItem,
+    callExportAction:
+      options?.callExportAction ??
+      (async () => ({
+        ok: true,
+        svg: "<svg><rect/></svg>",
+        filename: "screen-figma-123.svg",
+        report: { vectorized: ["root"] },
+      })),
+  } as unknown as FigmaSvgCopyEnvironment;
+  return { constructed, write, writeText, environment };
+}
+
+describe("canCopyFigmaSvgToClipboard", () => {
+  it("is true when clipboard.write is available", () => {
+    const { environment } = clipboardEnvironment();
+    expect(canCopyFigmaSvgToClipboard(environment)).toBe(true);
+  });
+
+  it("is true when only writeText is available (no ClipboardItem support)", () => {
+    expect(
+      canCopyFigmaSvgToClipboard({
+        clipboard: { writeText: vi.fn() },
+      } as never),
+    ).toBe(true);
+  });
+
+  it("is false when neither write nor writeText is available", () => {
+    expect(canCopyFigmaSvgToClipboard({ clipboard: {} } as never)).toBe(false);
+    expect(canCopyFigmaSvgToClipboard({ clipboard: null } as never)).toBe(
+      false,
+    );
+  });
+});
+
+describe("copyDesignAsFigmaSvg", () => {
+  it("writes BOTH text/plain (the proven Figma-paste MIME) and image/svg+xml representations", async () => {
+    const { constructed, environment, write } = clipboardEnvironment();
+
+    const result = await copyDesignAsFigmaSvg(
+      { designId: "design_1" },
+      environment,
+    );
+
+    expect(write).toHaveBeenCalledTimes(1);
+    expect(constructed).toHaveLength(1);
+    const item = constructed[0]!;
+    const textBlob = await item["text/plain"];
+    const svgBlob = await item["image/svg+xml"];
+    expect(textBlob).toBeInstanceOf(Blob);
+    expect(textBlob.type).toBe("text/plain");
+    expect(svgBlob).toBeInstanceOf(Blob);
+    expect(svgBlob.type).toBe("image/svg+xml");
+    expect(await textBlob.text()).toBe("<svg><rect/></svg>");
+    expect(result.filename).toBe("screen-figma-123.svg");
+    expect(result.report).toEqual({ vectorized: ["root"] });
+  });
+
+  it("falls back to writeText (still text/plain SVG markup) when ClipboardItem is unavailable", async () => {
+    const { environment, writeText, write } = clipboardEnvironment({
+      withClipboardItem: false,
+      writeText: async () => undefined,
+    });
+
+    await copyDesignAsFigmaSvg({ designId: "design_1" }, environment);
+
+    expect(write).not.toHaveBeenCalled();
+    expect(writeText).toHaveBeenCalledWith("<svg><rect/></svg>");
+  });
+
+  it("starts clipboard.write before a slow server export resolves", async () => {
+    let resolveExport!: (result: FigmaSvgExportActionResult) => void;
+    const callExportAction = vi.fn(
+      () =>
+        new Promise<FigmaSvgExportActionResult>((resolve) => {
+          resolveExport = resolve;
+        }),
+    );
+    const { environment, write } = clipboardEnvironment({ callExportAction });
+
+    const operation = copyDesignAsFigmaSvg(
+      { designId: "design_1" },
+      environment,
+    );
+    expect(write).toHaveBeenCalledTimes(1);
+
+    resolveExport({
+      ok: true,
+      svg: "<svg><rect/></svg>",
+      filename: "slow.svg",
+      report: {},
+    });
+    await expect(operation).resolves.toMatchObject({ filename: "slow.svg" });
+  });
+
+  it("does not advertise write-only clipboard support without ClipboardItem", () => {
+    expect(
+      canCopyFigmaSvgToClipboard({
+        clipboard: { write: vi.fn() },
+        ClipboardItem: null,
+      } as never),
+    ).toBe(false);
+  });
+
+  it("throws 'unsupported' before calling the export action when the clipboard API is missing", async () => {
+    const callExportAction = vi.fn();
+    await expect(
+      copyDesignAsFigmaSvg({ designId: "design_1" }, {
+        clipboard: null,
+        callExportAction,
+      } as never),
+    ).rejects.toMatchObject({ code: "unsupported" });
+    expect(callExportAction).not.toHaveBeenCalled();
+  });
+
+  it("wraps a chromium-unavailable export action response as 'render-failed'", async () => {
+    const { environment } = clipboardEnvironment({
+      callExportAction: async () => ({
+        ok: false,
+        reason: "A headless Chromium browser is not available...",
+      }),
+    });
+
+    const promise = copyDesignAsFigmaSvg({ designId: "design_1" }, environment);
+    await expect(promise).rejects.toBeInstanceOf(FigmaSvgCopyError);
+    await expect(promise).rejects.toMatchObject({ code: "render-failed" });
+  });
+
+  it("classifies a clipboard permission failure without hiding the cause", async () => {
+    const permissionError = new DOMException("denied", "NotAllowedError");
+    const { environment } = clipboardEnvironment({
+      write: async () => {
+        throw permissionError;
+      },
+    });
+
+    const promise = copyDesignAsFigmaSvg({ designId: "design_1" }, environment);
+    await expect(promise).rejects.toBeInstanceOf(FigmaSvgCopyError);
+    await expect(promise).rejects.toMatchObject({ code: "blocked" });
+  });
+
+  it("passes designId/fileId/nodeId/embedImages through to the export action", async () => {
+    const callExportAction = vi.fn(async () => ({
+      ok: true,
+      svg: "<svg/>",
+      filename: "x.svg",
+      report: {},
+    }));
+    const { environment } = clipboardEnvironment({ callExportAction });
+
+    await copyDesignAsFigmaSvg(
+      { designId: "design_1", nodeId: "node_1", embedImages: false },
+      environment,
+    );
+
+    expect(callExportAction).toHaveBeenCalledWith({
+      designId: "design_1",
+      nodeId: "node_1",
+      embedImages: false,
+    });
+  });
+});
diff --git a/templates/design/app/lib/figma-svg-copy.ts b/templates/design/app/lib/figma-svg-copy.ts
new file mode 100644
index 0000000000..f494876da4
--- /dev/null
+++ b/templates/design/app/lib/figma-svg-copy.ts
@@ -0,0 +1,221 @@
+import { callAction } from "@agent-native/core/client";
+
+export type FigmaSvgCopyErrorCode =
+  | "unsupported"
+  | "blocked"
+  | "write-failed"
+  | "render-failed";
+
+export class FigmaSvgCopyError extends Error {
+  readonly code: FigmaSvgCopyErrorCode;
+
+  constructor(code: FigmaSvgCopyErrorCode, cause?: unknown) {
+    super(`Figma SVG copy ${code}`);
+    this.name = "FigmaSvgCopyError";
+    this.code = code;
+    if (cause !== undefined) {
+      Object.defineProperty(this, "cause", {
+        configurable: true,
+        value: cause,
+      });
+    }
+  }
+}
+
+type ClipboardWriter = Pick<Clipboard, "write"> & {
+  writeText?: Clipboard["writeText"];
+};
+
+type ClipboardItemConstructor = {
+  new (items: Record<string, Blob | Promise<Blob>>): ClipboardItem;
+  supports?: (type: string) => boolean;
+};
+
+export interface FigmaSvgExportActionResult {
+  ok: boolean;
+  reason?: string;
+  svg?: string;
+  filename?: string;
+  report?: unknown;
+}
+
+export interface FigmaSvgExportParams {
+  designId?: string;
+  fileId?: string;
+  filename?: string;
+  nodeId?: string;
+  embedImages?: boolean;
+}
+
+export interface FigmaSvgCopyEnvironment {
+  clipboard?: ClipboardWriter | null;
+  ClipboardItem?: ClipboardItemConstructor | null;
+  /** Injectable override for tests — defaults to the real `callAction`. */
+  callExportAction?: (
+    params: FigmaSvgExportParams,
+  ) => Promise<FigmaSvgExportActionResult>;
+}
+
+function defaultFigmaSvgCopyEnvironment(): FigmaSvgCopyEnvironment {
+  return {
+    clipboard:
+      typeof navigator === "undefined" ? null : (navigator.clipboard ?? null),
+    ClipboardItem:
+      typeof globalThis.ClipboardItem === "undefined"
+        ? null
+        : globalThis.ClipboardItem,
+  };
+}
+
+function defaultCallExportAction(
+  params: FigmaSvgExportParams,
+): Promise<FigmaSvgExportActionResult> {
+  // Same cast-to-loose-signature pattern as design-save-outbox.ts's
+  // `invokeAction` default: the action registry's generated `ActionName`
+  // union doesn't need to be threaded through this small client module.
+  return (
+    callAction as (
+      name: string,
+      params: Record<string, unknown>,
+    ) => Promise<FigmaSvgExportActionResult>
+  )("export-design-as-figma-svg", params as unknown as Record<string, unknown>);
+}
+
+export function canCopyFigmaSvgToClipboard(
+  environment: FigmaSvgCopyEnvironment = defaultFigmaSvgCopyEnvironment(),
+): boolean {
+  // `text/plain` (the proven Figma-paste MIME — see the export-handoff skill's
+  // "Export to Figma (SVG)" section) only needs a plain `clipboard.write` or
+  // `writeText`; ClipboardItem is optional (only gates the extra
+  // `image/svg+xml` representation).
+  return Boolean(
+    (environment.clipboard?.write && environment.ClipboardItem) ||
+    environment.clipboard?.writeText,
+  );
+}
+
+function supportsClipboardType(
+  ClipboardItemCtor: ClipboardItemConstructor,
+  type: string,
+): boolean {
+  try {
+    return (
+      typeof ClipboardItemCtor.supports !== "function" ||
+      ClipboardItemCtor.supports(type)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function classifyClipboardWriteError(error: unknown): FigmaSvgCopyErrorCode {
+  const name =
+    error && typeof error === "object" && "name" in error
+      ? String(error.name)
+      : "";
+  if (name === "NotAllowedError" || name === "SecurityError") return "blocked";
+  if (name === "NotSupportedError" || error instanceof TypeError)
+    return "unsupported";
+  return "write-failed";
+}
+
+export interface FigmaSvgCopyResult {
+  filename: string;
+  report: unknown;
+}
+
+/**
+ * Exports a design screen (or a selected element's subtree via `nodeId`) as
+ * a genuinely vector SVG through the `export-design-as-figma-svg` action,
+ * then writes it to the system clipboard as BOTH:
+ *
+ *   - `text/plain` — the raw SVG markup. This is the MIME Figma's own paste
+ *     handler reads for "paste as vector shapes"; a `image/svg+xml`-only
+ *     clipboard write is NOT enough on its own for a reliable Figma paste.
+ *   - `image/svg+xml` — the same markup as a typed image representation,
+ *     for any other paste target that specifically requests SVG images.
+ *
+ * Call this from a user-gesture handler (e.g. a context-menu "Copy as SVG"
+ * item) — `clipboard.write` requires transient activation in most browsers,
+ * the same reason `copyPngPromiseToClipboard` in `png-clipboard.ts` is
+ * gesture-scoped.
+ */
+export async function copyDesignAsFigmaSvg(
+  params: FigmaSvgExportParams,
+  environment: FigmaSvgCopyEnvironment = defaultFigmaSvgCopyEnvironment(),
+): Promise<FigmaSvgCopyResult> {
+  if (!canCopyFigmaSvgToClipboard(environment)) {
+    throw new FigmaSvgCopyError("unsupported");
+  }
+
+  const callExportAction =
+    environment.callExportAction ?? defaultCallExportAction;
+  const clipboard = environment.clipboard;
+  const ClipboardItemCtor = environment.ClipboardItem;
+
+  let renderError: unknown;
+  const exportPromise = callExportAction(params)
+    .then((result) => {
+      if (!result.ok || !result.svg) {
+        throw new FigmaSvgCopyError(
+          "render-failed",
+          new Error(result.reason ?? "Figma SVG export failed"),
+        );
+      }
+      return result as FigmaSvgExportActionResult & { svg: string };
+    })
+    .catch((error: unknown) => {
+      renderError =
+        error instanceof FigmaSvgCopyError
+          ? error
+          : new FigmaSvgCopyError("render-failed", error);
+      throw renderError;
+    });
+  // ClipboardItem owns the promises below in real browsers. Keep a separate
+  // observer so test doubles or an early clipboard rejection cannot surface an
+  // unhandled action/render rejection.
+  void exportPromise.catch(() => undefined);
+
+  try {
+    if (clipboard?.write && ClipboardItemCtor) {
+      // Call clipboard.write while the initiating click/key event still owns
+      // transient activation. ClipboardItem deliberately receives pending
+      // Blob promises, matching the proven PNG clipboard path; awaiting the
+      // server render first makes slow exports fail in Safari and hardened
+      // Chromium even though the user invoked the command correctly.
+      const textBlobPromise = exportPromise.then(
+        (result) => new Blob([result.svg], { type: "text/plain" }),
+      );
+      void textBlobPromise.catch(() => undefined);
+      const items: Record<string, Blob | Promise<Blob>> = {
+        "text/plain": textBlobPromise,
+      };
+      if (supportsClipboardType(ClipboardItemCtor, "image/svg+xml")) {
+        const svgBlobPromise = exportPromise.then(
+          (result) => new Blob([result.svg], { type: "image/svg+xml" }),
+        );
+        void svgBlobPromise.catch(() => undefined);
+        items["image/svg+xml"] = svgBlobPromise;
+      }
+      await clipboard.write([new ClipboardItemCtor(items)]);
+    } else if (clipboard?.writeText) {
+      // No ClipboardItem constructor available — still deliver the SVG
+      // markup as text/plain, which is the proven Figma-paste path anyway.
+      const result = await exportPromise;
+      await clipboard.writeText(result.svg);
+    } else {
+      throw new FigmaSvgCopyError("unsupported");
+    }
+  } catch (error) {
+    if (error instanceof FigmaSvgCopyError) throw error;
+    if (renderError !== undefined) throw renderError;
+    throw new FigmaSvgCopyError(classifyClipboardWriteError(error), error);
+  }
+
+  const result = await exportPromise;
+
+  return {
+    filename: result.filename ?? "design-figma.svg",
+    report: result.report,
+  };
+}
diff --git a/templates/design/app/pages/DesignEditor.collabRebase.test.ts b/templates/design/app/pages/DesignEditor.collabRebase.test.ts
index 5f021bbf83..1b9d6bee71 100644
--- a/templates/design/app/pages/DesignEditor.collabRebase.test.ts
+++ b/templates/design/app/pages/DesignEditor.collabRebase.test.ts
@@ -2,8 +2,10 @@ import { describe, expect, it } from "vitest";
 
 import {
   resolveScreenCollabSyncTarget,
+  shouldApplyRemotePreviewContent,
   shouldRebaseCollabDocFromStoredContent,
 } from "./design-editor/collab-sync";
+import { shouldAdoptExternalReconcileContent } from "./design-editor/editor-session";
 
 const OLD_HTML =
   '<!doctype html><html><body><div data-agent-native-node-id="an-1">old</div></body></html>';
@@ -141,3 +143,105 @@ describe("resolveScreenCollabSyncTarget (§gesture-persistence per-screen collab
     ).toEqual({ writeLiveDoc: false, syncCollab: true });
   });
 });
+
+describe("shouldApplyRemotePreviewContent (flash-free reconcile routing)", () => {
+  it("does not touch the preview for a local transaction", () => {
+    expect(
+      shouldApplyRemotePreviewContent({
+        isLocalEdit: true,
+        previousContent: OLD_HTML,
+        nextContent: NEW_HTML,
+      }),
+    ).toBe(false);
+  });
+
+  it("does not touch the preview for a same-content remote acknowledgement echo", () => {
+    expect(
+      shouldApplyRemotePreviewContent({
+        isLocalEdit: false,
+        previousContent: NEW_HTML,
+        nextContent: NEW_HTML,
+      }),
+    ).toBe(false);
+  });
+
+  it("applies a genuinely different remote snapshot through the live replacement path", () => {
+    expect(
+      shouldApplyRemotePreviewContent({
+        isLocalEdit: false,
+        previousContent: OLD_HTML,
+        nextContent: NEW_HTML,
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("shouldAdoptExternalReconcileContent (same-millisecond tie-break fix)", () => {
+  it("always adopts when there's no established watermark yet (fresh file load)", () => {
+    expect(
+      shouldAdoptExternalReconcileContent({
+        appliedUpdatedAt: null,
+        dbUpdatedAt: "2026-07-05T10:05:00.000Z",
+        agentActive: false,
+      }),
+    ).toBe(true);
+  });
+
+  it("adopts when the DB content is strictly newer than the applied watermark", () => {
+    expect(
+      shouldAdoptExternalReconcileContent({
+        appliedUpdatedAt: "2026-07-05T10:05:00.000Z",
+        dbUpdatedAt: "2026-07-05T10:05:00.100Z",
+        agentActive: false,
+      }),
+    ).toBe(true);
+  });
+
+  it("does not adopt strictly-older DB content", () => {
+    expect(
+      shouldAdoptExternalReconcileContent({
+        appliedUpdatedAt: "2026-07-05T10:05:00.100Z",
+        dbUpdatedAt: "2026-07-05T10:05:00.000Z",
+        agentActive: false,
+      }),
+    ).toBe(false);
+  });
+
+  it("adopts a same-millisecond tie when the agent is NOT active — the dropped-write fix", () => {
+    // Reached only once the caller's own "already reflecting this content"
+    // checks have ruled out dbContent matching what's rendered, so a tied
+    // timestamp here always represents a genuinely different write that
+    // landed in the same millisecond as the one already applied. A strict
+    // `>` used to silently drop this.
+    expect(
+      shouldAdoptExternalReconcileContent({
+        appliedUpdatedAt: "2026-07-05T10:05:00.000Z",
+        dbUpdatedAt: "2026-07-05T10:05:00.000Z",
+        agentActive: false,
+      }),
+    ).toBe(true);
+  });
+
+  it("does NOT adopt a same-millisecond tie while the agent is active — defers to the debounced self-echo recovery timer instead", () => {
+    // Forcing immediate adoption here too would skip
+    // staleAgentEchoPossible's 1200ms debounced recheck and reintroduce the
+    // live self-echo race that debounce exists to prevent.
+    expect(
+      shouldAdoptExternalReconcileContent({
+        appliedUpdatedAt: "2026-07-05T10:05:00.000Z",
+        dbUpdatedAt: "2026-07-05T10:05:00.000Z",
+        agentActive: true,
+      }),
+    ).toBe(false);
+  });
+
+  it("does not adopt when dbUpdatedAt is missing but a watermark is already established", () => {
+    expect(
+      shouldAdoptExternalReconcileContent({
+        appliedUpdatedAt: "2026-07-05T10:05:00.000Z",
+        dbUpdatedAt: null,
+        agentActive: false,
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/templates/design/app/pages/DesignEditor.reparentPosition.test.ts b/templates/design/app/pages/DesignEditor.reparentPosition.test.ts
new file mode 100644
index 0000000000..453cb99702
--- /dev/null
+++ b/templates/design/app/pages/DesignEditor.reparentPosition.test.ts
@@ -0,0 +1,130 @@
+// @vitest-environment happy-dom
+
+/**
+ * DesignEditor.reparentPosition.test.ts
+ *
+ * Regression coverage for the nested-container reparent bug: DesignEditor's
+ * (private, unexported) `getAbsolutePositioningForNodeInHtml` used to read
+ * only a node's own inline `style.left`/`style.top` — correct for a direct
+ * child of the screen root, but wrong for anything nested inside another
+ * positioned/flow container, since that value is relative to the node's OWN
+ * immediate parent rather than the screen root. `computeReparentedChildPosition`
+ * (shared/board-file.ts) then did a flat `source - target` subtraction,
+ * which is only valid when both inputs share the same coordinate space.
+ * Combining a parent-relative read with that flat subtraction produced a
+ * garbage delta whenever the source or target container was nested two or
+ * more levels deep — the dropped element visibly jumped away from the
+ * cursor.
+ *
+ * The fix reuses `authoredElementPosition` (MultiScreenCanvas's
+ * primitive-drop-target.ts — now exported for exactly this reuse) inside
+ * `getAbsolutePositioningForNodeInHtml`, which walks every ancestor up to
+ * `<body>` accumulating positioned-ancestor offsets and static-flow
+ * padding/sibling contributions. That produces a true screen-root-relative
+ * position for both source and target regardless of nesting depth, so
+ * `computeReparentedChildPosition`'s flat subtraction becomes valid again.
+ *
+ * `getAbsolutePositioningForNodeInHtml` itself stays private to
+ * DesignEditor.tsx (matching every other module-level helper in that file),
+ * so this spec exercises the exact same public seam DesignEditor.tsx now
+ * calls through: `authoredElementPosition` feeding
+ * `computeReparentedChildPosition`, using jsdom-style parsed documents built
+ * the same way `getAbsolutePositioningForNodeInHtml` builds them (DOMParser
+ * + a `data-agent-native-node-id` lookup).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { authoredElementPosition } from "@/components/design/multi-screen/primitive-drop-target";
+
+import { computeReparentedChildPosition } from "../../shared/board-file";
+
+function parse(html: string): Document {
+  return new DOMParser().parseFromString(html, "text/html");
+}
+
+function findByNodeId(doc: Document, nodeId: string): Element {
+  const element = doc.querySelector(`[data-agent-native-node-id="${nodeId}"]`);
+  if (!element) throw new Error(`missing node ${nodeId}`);
+  return element;
+}
+
+function resolvePosition(doc: Document, nodeId: string) {
+  return authoredElementPosition(findByNodeId(doc, nodeId));
+}
+
+describe("nested-container reparent position resolution", () => {
+  it("matches the old flat-read behavior for root-level (direct screen-root child) nodes", () => {
+    const html = `<!DOCTYPE html><html><body>
+      <div data-agent-native-node-id="source" style="position:absolute;left:398px;top:144px;width:80px;height:40px;"></div>
+      <div data-agent-native-node-id="target" style="position:absolute;left:250px;top:100px;width:400px;height:400px;"></div>
+    </body></html>`;
+    const doc = parse(html);
+    const sourcePosition = resolvePosition(doc, "source");
+    const targetPosition = resolvePosition(doc, "target");
+    // Both nodes are direct children of <body> — the ancestor walk should
+    // terminate after a single step and return their own inline left/top
+    // unchanged, exactly like the previous naive implementation.
+    expect(sourcePosition).toEqual({ x: 398, y: 144 });
+    expect(targetPosition).toEqual({ x: 250, y: 100 });
+    expect(
+      computeReparentedChildPosition(sourcePosition, targetPosition),
+    ).toEqual({ x: 148, y: 44 });
+  });
+
+  it("resolves a node two containers deep to its true screen-root-relative position (same-screen reparent)", () => {
+    // outer (absolute, root-level) > inner (absolute, nested) > source
+    //   (absolute, nested again). target is a root-level frame the user
+    // drags `source` into.
+    const html = `<!DOCTYPE html><html><body>
+      <div data-agent-native-node-id="outer" style="position:absolute;left:100px;top:80px;width:600px;height:600px;">
+        <div data-agent-native-node-id="inner" style="position:absolute;left:50px;top:40px;width:400px;height:400px;">
+          <div data-agent-native-node-id="source" style="position:absolute;left:20px;top:10px;width:80px;height:40px;"></div>
+        </div>
+      </div>
+      <div data-agent-native-node-id="target" style="position:absolute;left:300px;top:250px;width:200px;height:200px;"></div>
+    </body></html>`;
+    const doc = parse(html);
+    // Screen-root-relative source position = 100+50+20, 80+40+10.
+    const sourcePosition = resolvePosition(doc, "source");
+    expect(sourcePosition).toEqual({ x: 170, y: 130 });
+    const targetPosition = resolvePosition(doc, "target");
+    expect(targetPosition).toEqual({ x: 300, y: 250 });
+    // Old (buggy) behavior would have read source.style.left/top verbatim —
+    // {x: 20, y: 10}, relative to "inner" — and subtracted target's root
+    // position from THAT, teleporting the dropped node far from the cursor.
+    // The fixed pipeline instead produces the correct parent-relative delta
+    // once "source" is reparented under "target".
+    expect(
+      computeReparentedChildPosition(sourcePosition, targetPosition),
+    ).toEqual({ x: -130, y: -120 });
+  });
+
+  it("resolves a node nested inside a static-flow (non-absolute) frame with padding, for cross-screen reparent", () => {
+    // Source screen: a frame with padding contains "source" as its second
+    // flex child (so the walk must also account for the preceding sibling's
+    // width + gap, not just ancestor padding).
+    const sourceHtml = `<!DOCTYPE html><html><body>
+      <div data-agent-native-node-id="frame" style="position:absolute;left:40px;top:60px;width:500px;height:300px;padding-left:16px;padding-top:16px;display:flex;gap:8px;">
+        <div data-agent-native-node-id="sibling" style="width:100px;height:40px;"></div>
+        <div data-agent-native-node-id="source" style="width:80px;height:40px;"></div>
+      </div>
+    </body></html>`;
+    // Destination screen: target frame lives at a different root offset.
+    const destHtml = `<!DOCTYPE html><html><body>
+      <div data-agent-native-node-id="target" style="position:absolute;left:500px;top:500px;width:300px;height:300px;"></div>
+    </body></html>`;
+    const sourceDoc = parse(sourceHtml);
+    const destDoc = parse(destHtml);
+    // Screen-root-relative source: frame origin (40,60) + frame padding
+    // (16,16) + sibling's width+gap (100+8) contributed on the x axis only
+    // (row flex) = 40+16+100+8=164, 60+16=76.
+    const sourcePosition = resolvePosition(sourceDoc, "source");
+    expect(sourcePosition).toEqual({ x: 164, y: 76 });
+    const targetPosition = resolvePosition(destDoc, "target");
+    expect(targetPosition).toEqual({ x: 500, y: 500 });
+    expect(
+      computeReparentedChildPosition(sourcePosition, targetPosition),
+    ).toEqual({ x: -336, y: -424 });
+  });
+});
diff --git a/templates/design/app/pages/DesignEditor.resizeUndoFallback.spec.ts b/templates/design/app/pages/DesignEditor.resizeUndoFallback.spec.ts
new file mode 100644
index 0000000000..43096136de
--- /dev/null
+++ b/templates/design/app/pages/DesignEditor.resizeUndoFallback.spec.ts
@@ -0,0 +1,124 @@
+/**
+ * DesignEditor.resizeUndoFallback.spec.ts
+ *
+ * BUG-UNDO-RESIZE-STACK regression — Cmd+Z stopped undoing a canvas
+ * resize-drag at all.
+ *
+ * Every content-mutating commit path in DesignEditor.tsx that goes through
+ * the Yjs UndoManager (`applyLocalContentUpdate`, `applyFileContentUpdate`)
+ * ALSO mirrors its before/after pair into `localContentUndoStackRef` via
+ * `recordLocalContentHistoryChangeFallback` (which wraps
+ * `mergeLocalContentHistoryFallback`). This mirror exists specifically
+ * because the Yjs UndoManager (and its whole undo stack) is destroyed and
+ * recreated whenever `docId` changes — a view-mode switch, a zoom-triggered
+ * re-render, or a breakpoint switch — and handleUndo falls back to this local
+ * stack once `undoManagerRef.current?.canUndo()` is false.
+ *
+ * `commitVisualStyles` — the ONE commit path a gesture-driven resize/style
+ * drag goes through — wrote directly to the Y.Doc but never called this
+ * mirror. So the moment the UndoManager was torn down for any of the above
+ * reasons between the resize-drag and the user's Cmd+Z, there was NOTHING
+ * left to undo: not in Yjs (destroyed), not in the local fallback stack
+ * (never populated for this commit path). Cmd+Z silently did nothing, no
+ * matter how many times it was pressed.
+ *
+ * These tests pin the pure mechanism `commitVisualStyles` now drives the same
+ * way every other commit path already did: "before" (old, buggy) simulates a
+ * resize commit that never mirrors to the local stack; "after" (fixed)
+ * simulates the same commit calling `recordLocalContentHistoryChangeFallback`,
+ * matching the new `else if (yjsHistoryAvailable ...)` branch added to
+ * `commitVisualStyles`.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  findLastContentHistoryChangeIndex,
+  mergeLocalContentHistoryFallback,
+  type ContentHistoryChange,
+} from "./design-editor/history";
+
+const FILE_ID = "screen-1";
+const BEFORE_RESIZE_HTML =
+  '<div id="box" style="position:absolute;left:10px;top:10px;width:100px;height:100px;"></div>';
+const AFTER_RESIZE_HTML =
+  '<div id="box" style="position:absolute;left:10px;top:10px;width:260px;height:180px;"></div>';
+
+function simulateYjsUndoManagerTornDown() {
+  // Mirrors handleUndo's `um?.canUndo()` going false after a view-mode
+  // switch / zoom change destroys and recreates the UndoManager (see the
+  // useEffect on undoManagerRef in DesignEditor.tsx) — its whole stack is
+  // gone, so handleUndo must fall back to localContentUndoStackRef.
+  return { canUndo: () => false };
+}
+
+describe("resize-drag undo — local fallback mirror (BUG-UNDO-RESIZE-STACK)", () => {
+  it("BEFORE FIX: a resize commit that never mirrors leaves nothing to recover once the Yjs stack is gone", () => {
+    // Old commitVisualStyles: only recorded into the local fallback stack
+    // when yjsHistoryAvailable was FALSE. For a single-screen gesture commit
+    // (yjsHistoryAvailable === true), the local stack was never touched.
+    let localContentUndoStack: ContentHistoryChange[] = [];
+
+    const um = simulateYjsUndoManagerTornDown();
+    expect(um.canUndo()).toBe(false);
+
+    // handleUndo's fallback lookup finds nothing for this file — Cmd+Z is a
+    // total no-op, reproducing "DOM stays at new size after 2 presses".
+    const recoverableIndex = findLastContentHistoryChangeIndex(
+      localContentUndoStack,
+      FILE_ID,
+    );
+    expect(recoverableIndex).toBe(-1);
+  });
+
+  it("AFTER FIX: commitVisualStyles' local mirror lets handleUndo recover the pre-resize content", () => {
+    let localContentUndoStack: ContentHistoryChange[] = [];
+
+    // This is exactly the new `else if (yjsHistoryAvailable ...)` branch in
+    // commitVisualStyles: mirror the same before/after commitVisualStyles
+    // just wrote into the Y.Doc.
+    localContentUndoStack = mergeLocalContentHistoryFallback(
+      localContentUndoStack,
+      { fileId: FILE_ID, before: BEFORE_RESIZE_HTML, after: AFTER_RESIZE_HTML },
+    );
+
+    const um = simulateYjsUndoManagerTornDown();
+    expect(um.canUndo()).toBe(false);
+
+    const recoverableIndex = findLastContentHistoryChangeIndex(
+      localContentUndoStack,
+      FILE_ID,
+    );
+    expect(recoverableIndex).not.toBe(-1);
+
+    const [entry] = localContentUndoStack.splice(recoverableIndex, 1);
+    expect(entry?.before).toBe(BEFORE_RESIZE_HTML);
+    // The recovered content is the pre-resize box size, not the resized one.
+    expect(entry?.before).toContain("width:100px;height:100px");
+    expect(entry?.before).not.toContain("width:260px");
+  });
+
+  it("mirrors consecutive resize ticks (onMove-style coalescing) as a single undoable step, matching mergeLocalContentHistoryFallback's chaining contract", () => {
+    let localContentUndoStack: ContentHistoryChange[] = [];
+    const midDragHtml =
+      '<div id="box" style="position:absolute;left:10px;top:10px;width:200px;height:150px;"></div>';
+
+    // First tick of the same gesture.
+    localContentUndoStack = mergeLocalContentHistoryFallback(
+      localContentUndoStack,
+      { fileId: FILE_ID, before: BEFORE_RESIZE_HTML, after: midDragHtml },
+    );
+    // Second tick chains off the first tick's "after" (same fileId), so the
+    // whole gesture still undoes in ONE step back to the true pre-drag size.
+    localContentUndoStack = mergeLocalContentHistoryFallback(
+      localContentUndoStack,
+      { fileId: FILE_ID, before: midDragHtml, after: AFTER_RESIZE_HTML },
+    );
+
+    expect(localContentUndoStack).toHaveLength(1);
+    expect(localContentUndoStack[0]).toEqual({
+      fileId: FILE_ID,
+      before: BEFORE_RESIZE_HTML,
+      after: AFTER_RESIZE_HTML,
+    });
+  });
+});
diff --git a/templates/design/app/pages/DesignEditor.selection.test.ts b/templates/design/app/pages/DesignEditor.selection.test.ts
index bf49f7f32f..4ed92ab94a 100644
--- a/templates/design/app/pages/DesignEditor.selection.test.ts
+++ b/templates/design/app/pages/DesignEditor.selection.test.ts
@@ -59,6 +59,8 @@ import {
   getPendingVisualStylePropertyCount,
   shouldBlockPendingVisualStyleNavigation,
   resolveOverviewScreenSourceType,
+  shouldPreferRuntimeLayerProjection,
+  shouldUseRuntimeLayerProjection,
   shouldShowPendingVisualStyleApply,
   formatPendingVisualStylePrompt,
   buildPendingVisualStyleRevertPatches,
@@ -86,6 +88,7 @@ import {
   shouldUseOverviewRuntimeReplacement,
   shouldIncludeScreenRenameContentOverride,
   shouldMirrorSelectedElementToAgentChat,
+  computeOverviewScreenPickSelectionIds,
 } from "./design-editor/selection-state";
 import {
   getDesignToolActivationState,
@@ -665,6 +668,53 @@ describe("DesignEditor pending visual style edits", () => {
     ).toBe(true);
   });
 
+  it("uses runtime layers only for URL-backed localhost screens", () => {
+    expect(
+      shouldUseRuntimeLayerProjection({
+        screen: { sourceType: "localhost", bridgeUrl: "http://127.0.0.1:7336" },
+        content: "http://127.0.0.1:9210/",
+      }),
+    ).toBe(true);
+    expect(
+      shouldUseRuntimeLayerProjection({
+        screen: { sourceType: "inline" },
+        content:
+          '<div x-data="{}"><template x-for="item in items"></template></div>',
+      }),
+    ).toBe(false);
+    expect(
+      shouldUseRuntimeLayerProjection({
+        screen: { sourceType: "localhost" },
+        content:
+          '<div x-data="{}">Inline Alpine remains source projected</div>',
+      }),
+    ).toBe(false);
+  });
+
+  it("prefers a valid live runtime tree even when its node count is equal or smaller", () => {
+    expect(
+      shouldPreferRuntimeLayerProjection({
+        eligible: true,
+        runtimeNodeCount: 3,
+        sourceNodeCount: 3,
+      }),
+    ).toBe(true);
+    expect(
+      shouldPreferRuntimeLayerProjection({
+        eligible: true,
+        runtimeNodeCount: 2,
+        sourceNodeCount: 5,
+      }),
+    ).toBe(true);
+    expect(
+      shouldPreferRuntimeLayerProjection({
+        eligible: false,
+        runtimeNodeCount: 8,
+        sourceNodeCount: 2,
+      }),
+    ).toBe(false);
+  });
+
   it("hides the apply styles affordance for non-localhost visual edits", () => {
     const edits = [
       {
@@ -727,6 +777,46 @@ describe("DesignEditor overview layer selection", () => {
         event: "select",
       }),
     ).toBe(false);
+
+    expect(
+      shouldIgnoreOverviewLayerCreationEcho({
+        pendingLayerId: "selected-beta",
+        pendingScreenId: "screen-a",
+        screenId: "screen-a",
+        info: {
+          ...layerInfo,
+          sourceId: "selected-beta",
+        },
+        event: "select",
+      }),
+    ).toBe(true);
+
+    expect(
+      shouldIgnoreOverviewLayerCreationEcho({
+        pendingLayerId: "selected-beta",
+        pendingScreenId: "screen-a",
+        screenId: "screen-a",
+        info: {
+          ...layerInfo,
+          sourceId: "real-canvas-click",
+        },
+        event: "select",
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldIgnoreOverviewLayerCreationEcho({
+        pendingLayerId: "projected-beta-id",
+        pendingScreenId: "screen-a",
+        screenId: "screen-a",
+        info: {
+          ...layerInfo,
+          sourceId: "authored-beta-id",
+        },
+        resolvedLayerId: "projected-beta-id",
+        event: "select",
+      }),
+    ).toBe(true);
   });
 
   it("allows normal element selection after the creation echo has cleared", () => {
@@ -2449,3 +2539,52 @@ describe("shouldClearBridgeSelectionOnEmptyMarquee", () => {
     ).toBe(false);
   });
 });
+
+describe("computeOverviewScreenPickSelectionIds", () => {
+  // PICK-RACE: MultiScreenCanvas's onPick prop is `(id: string) => void` —
+  // no modifier info — even though a shift-click there already toggled a
+  // full multi-id array internally before calling onPick with just the
+  // resulting primary id. handleOverviewScreenPick used to always clobber
+  // selectedLayerIdsState down to [pickedId], which is wrong for both
+  // shift-click cases below; the fix defers entirely to the
+  // onScreenSelectionChange-reported overviewSelectedScreenIds while shift
+  // is held instead of guessing a (necessarily wrong) merged array.
+  it("replaces the selection with the singleton pick when shift is not held", () => {
+    expect(
+      computeOverviewScreenPickSelectionIds({
+        pickedId: "screen-b",
+        shiftKeyHeld: false,
+        currentSelectedLayerIds: ["screen-a"],
+      }),
+    ).toEqual(["screen-b"]);
+  });
+
+  it("does not clobber a multi-screen selection on a shift-click ADD", () => {
+    // handleFrameClick already added "screen-b" to ITS OWN selectedIds and
+    // reported "screen-b" as the new primary via onPick; DesignEditor's
+    // selectedLayerIdsState still shows only ["screen-a"] until the
+    // onScreenSelectionChange effect lands ["screen-a", "screen-b"] a render
+    // later. The fix must not overwrite it with a wrong singleton meanwhile.
+    expect(
+      computeOverviewScreenPickSelectionIds({
+        pickedId: "screen-b",
+        shiftKeyHeld: true,
+        currentSelectedLayerIds: ["screen-a"],
+      }),
+    ).toEqual(["screen-a"]);
+  });
+
+  it("does not clobber the remaining selection on a shift-click REMOVE", () => {
+    // Selection was [A, B, C]; shift-clicking B toggles it off, and
+    // handleFrameClick reports the new primary (the last remaining id, "C")
+    // through onPick — NOT the full remaining array. A naive
+    // [pickedId] === ["C"] clobber would incorrectly drop "A" too.
+    expect(
+      computeOverviewScreenPickSelectionIds({
+        pickedId: "screen-c",
+        shiftKeyHeld: true,
+        currentSelectedLayerIds: ["screen-a", "screen-b", "screen-c"],
+      }),
+    ).toEqual(["screen-a", "screen-b", "screen-c"]);
+  });
+});
diff --git a/templates/design/app/pages/DesignEditor.singleScreenCreation.spec.ts b/templates/design/app/pages/DesignEditor.singleScreenCreation.spec.ts
index cefc8606fa..d8234f568c 100644
--- a/templates/design/app/pages/DesignEditor.singleScreenCreation.spec.ts
+++ b/templates/design/app/pages/DesignEditor.singleScreenCreation.spec.ts
@@ -313,6 +313,38 @@ describe("parsePenPathFromSerializedD (inverse of serializePenPath)", () => {
     });
   });
 
+  it("round-trips an asymmetric cusp node (handleOut only, no handleIn) in the middle of an open path", () => {
+    // The cusp's incoming segment renders as a straight "L" (its handleIn is
+    // absent) while its outgoing segment renders as a curve "C" (it has a
+    // handleOut) — the reconstructed node must come back with exactly that
+    // one-sided handle shape, not gain a phantom handleIn nor lose the
+    // handleOut.
+    const cusp = createSmoothNode(
+      { x: 50, y: 50 },
+      { x: 90, y: 30 },
+      { breakSymmetry: true },
+    );
+    expect(cusp.handleIn).toBeUndefined();
+    expect(cusp.handleOut).toEqual({ x: 90, y: 30 });
+
+    const path: PenPath = {
+      nodes: [
+        createCornerNode({ x: 0, y: 0 }),
+        cusp,
+        createCornerNode({ x: 150, y: 20 }),
+      ],
+      closed: false,
+    };
+    const d = serializePenPath(path);
+    expect(d).toContain(" L 50 50 C ");
+
+    const parsed = parsePenPathFromSerializedD(d);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.nodes[1].handleIn).toBeUndefined();
+    expect(parsed!.nodes[1].handleOut).toEqual({ x: 90, y: 30 });
+    expect(serializePenPath(parsed!)).toBe(d);
+  });
+
   it("returns null for empty input", () => {
     expect(parsePenPathFromSerializedD("")).toBeNull();
     expect(parsePenPathFromSerializedD("   ")).toBeNull();
diff --git a/templates/design/app/pages/DesignEditor.tsx b/templates/design/app/pages/DesignEditor.tsx
index b8f594b260..084e32341a 100644
--- a/templates/design/app/pages/DesignEditor.tsx
+++ b/templates/design/app/pages/DesignEditor.tsx
@@ -152,6 +152,7 @@ import {
   IconLink,
   IconLock,
   IconPuzzle,
+  IconKeyboard,
 } from "@tabler/icons-react";
 import { useQueryClient } from "@tanstack/react-query";
 import {
@@ -209,6 +210,7 @@ import {
   type DesignExtensionSlotContext,
 } from "@/components/design/DesignExtensionsPanel";
 import { DesignImportPanel } from "@/components/design/DesignImportPanel";
+import { nextTextDecorationLineValue } from "@/components/design/edit-panel/typography-helpers";
 import {
   EditPanel,
   isTextElement,
@@ -228,6 +230,7 @@ import {
   isShaderWriteInFlight,
   waitForShaderWriteToSettle,
 } from "@/components/design/inspector/GlslShaderPanel";
+import { KeyboardShortcutsPanel } from "@/components/design/KeyboardShortcutsPanel";
 import {
   LayersPanel,
   type LayersPanelFile,
@@ -243,8 +246,17 @@ import {
   MotionDock,
   type MotionDockTrack,
 } from "@/components/design/MotionDock";
-import { getInitialFrameGeometry } from "@/components/design/multi-screen/frame-geometry";
-import { getPrimaryIframeId } from "@/components/design/multi-screen/iframe-targeting";
+import { getBoardSurfaceContentBounds } from "@/components/design/multi-screen/board-surface-html";
+import {
+  getCanonicalScreenStack,
+  getInitialFrameGeometry,
+  reorderCanonicalScreenStack,
+} from "@/components/design/multi-screen/frame-geometry";
+import {
+  findCanvasIframeForScreen,
+  getPrimaryIframeId,
+} from "@/components/design/multi-screen/iframe-targeting";
+import { authoredElementPosition } from "@/components/design/multi-screen/primitive-drop-target";
 import type {
   CanvasLayerMarqueeSelection,
   CanvasPrimitiveInsert,
@@ -261,10 +273,12 @@ import { ReadOnlyDesignBanner } from "@/components/design/ReadOnlyDesignBanner";
 import type { ReviewPanelProps } from "@/components/design/ReviewPanel";
 import { TokensPanel } from "@/components/design/TokensPanel";
 import type {
+  CanvasLayerHitCandidate,
   ElementInfo,
   ElementSelectionIntent,
   DeviceFrameType,
   PortableStyleSnapshot,
+  RuntimeStructureMoveRequest,
 } from "@/components/design/types";
 import { DEVICE_FRAME_VIEWPORTS } from "@/components/design/types";
 import PromptPopover from "@/components/editor/PromptDialog";
@@ -313,6 +327,10 @@ import {
   TooltipContent,
   TooltipTrigger,
 } from "@/components/ui/tooltip";
+import {
+  DrawOverlay as SharedDrawOverlay,
+  type DrawAnnotation,
+} from "@/components/visual-editor/DrawOverlay";
 import { useAgentGenerating } from "@/hooks/use-agent-generating";
 import { useDesignSystems } from "@/hooks/use-design-systems";
 import {
@@ -330,6 +348,7 @@ import {
 import {
   DESIGN_CHAT_STORAGE_KEY,
   sendToDesignAgentChat,
+  sendToDesignAgentChatAndConfirm,
 } from "@/lib/agent-chat";
 import {
   type DesignClipboardPayload,
@@ -349,6 +368,12 @@ import {
   updateFileResultPersistedContent,
   type DesignSaveOutboxEntry,
 } from "@/lib/design-save-outbox";
+import { resolveFigmaPasteImportCall } from "@/lib/figma-clipboard";
+import {
+  canCopyFigmaSvgToClipboard,
+  copyDesignAsFigmaSvg,
+  FigmaSvgCopyError,
+} from "@/lib/figma-svg-copy";
 import {
   clearPendingGeneration,
   hasFreshPendingGeneration,
@@ -401,6 +426,7 @@ import {
 } from "./design-editor/code-layer-state";
 import {
   resolveScreenCollabSyncTarget,
+  shouldApplyRemotePreviewContent,
   shouldRebaseCollabDocFromStoredContent,
 } from "./design-editor/collab-sync";
 import {
@@ -424,6 +450,7 @@ import { queryUniqueSelector } from "./design-editor/dom-utils";
 import {
   createEditorSaveOperationSource,
   LOCAL_EDIT_ORIGIN,
+  shouldAdoptExternalReconcileContent,
   TAB_ID,
 } from "./design-editor/editor-session";
 import {
@@ -440,10 +467,12 @@ import {
   getPersistedContentHostSyncOptions,
   removeUndoRedoOrderKind,
   resolveLocalhostSourceWriteContent,
+  resolveOptimisticTextDecorationLine,
   shouldClearLatestUnloadSave,
   shouldReplacePreviewAfterVisualStyleCommit,
   shouldSendKeepalive,
   shouldSkipVisualStyleCommitForPreview,
+  type OptimisticTextDecorationLineEntry,
   type UndoRedoOrderKind,
 } from "./design-editor/editor-state";
 import {
@@ -488,9 +517,14 @@ import {
   type MotionTimelineQueryResult,
   motionTimelineFingerprint,
 } from "./design-editor/motion-state";
+import {
+  collectOverviewAnnotationViewportMap,
+  formatOverviewAnnotationMessage,
+} from "./design-editor/overview-annotation-context";
 import {
   clampOverviewDisplayZoom,
   clampZoom,
+  computeIframeLocalCanvasPoint,
   findScreenFrameAtCanvasPoint,
   getAllScreenFrameEntries,
   getDefaultOverviewCanvasZoom,
@@ -503,6 +537,7 @@ import {
   resolveOverviewZoomBasisScreenId,
   resolveScreenEntryZoom,
   resolveZoomUpdate,
+  readOverviewZoomPercentFromTransform,
   shouldPopToOverviewOnZoomChange,
   shouldResetExplicitOverviewZoomOnBasisChange,
 } from "./design-editor/overview-camera";
@@ -516,6 +551,7 @@ import {
   mergePendingLiveNonStyleEdits,
   mergePendingVisualStyleEdits,
   originalStylesForPendingVisualEdit,
+  reactSourceAnchorForPendingEdit,
   type PendingLiveNonStyleEdit,
   type PendingLiveNonStyleUndoEntry,
   type PendingLiveStructureEdit,
@@ -526,6 +562,8 @@ import {
   type PendingVisualStyleUndoEntry,
   pendingVisualStyleUndoRevertStyles,
   resolveOverviewScreenSourceType,
+  shouldPreferRuntimeLayerProjection,
+  shouldUseRuntimeLayerProjection,
   resolveVisualStyleCommitContent,
   shouldBlockPendingVisualStyleNavigation,
   shouldShowPendingVisualStyleApply,
@@ -536,18 +574,32 @@ import {
   elementAtPortableStylePath,
   styleHost,
 } from "./design-editor/portable-style";
+import {
+  buildReactSemanticHandoff,
+  buildRuntimeReactLayerStateHandoff,
+  buildRuntimeReactStructureMoveHandoff,
+  resolveRuntimeStructureMoveExecutionMode,
+} from "./design-editor/react-semantic-handoff";
+import {
+  enableInlineScreenAutoLayout,
+  getRuntimeScreenAutoLayoutSubjectIds,
+} from "./design-editor/screen-auto-layout";
 import {
   buildActiveFileNodeIdSet,
+  computeOverviewScreenPickSelectionIds,
   dedupeStringIds,
-  getContentSignature,
   getOverviewEnterTarget,
   getOverviewScreenIdsFromLayerSelection,
+  getOverviewScreenContentKey,
   getOverviewScreenRuntimeReplacementKey,
   getSelectedScreenGeometryForInspector,
   getSelectedScreenIdsForEditorState,
   getSidebarCodeLayerSelectionState,
+  hasSelectableCodeLayerParent,
   isScreenRootElementInfo,
+  pendingEditTargetsSelectedElement,
   resolveAvailableActiveFileId,
+  resolveEscapePopSelectionAction,
   sameStringIds,
   shouldClearBridgeSelectionOnEmptyMarquee,
   shouldEscapeToOverview,
@@ -974,6 +1026,38 @@ interface LiveScreenSnapshot {
   contentType?: string;
 }
 
+interface RuntimeLayerSnapshot {
+  html: string;
+  nodeCount: number;
+}
+
+function runtimeMultiplicityForElementProvenance(
+  snapshots: Record<string, RuntimeLayerSnapshot>,
+  info: ElementInfo | null | undefined,
+): number {
+  const provenance = info?.provenance;
+  if (!provenance?.sourceFile || !provenance.line || !provenance.column) {
+    return 1;
+  }
+  let count = 0;
+  for (const snapshot of Object.values(snapshots)) {
+    const projection = buildCodeLayerProjection(snapshot.html);
+    for (const node of projection.nodes) {
+      const attrs = node.dataAttributes;
+      if (
+        attrs["data-source-file"] === provenance.sourceFile &&
+        Number(attrs["data-source-line"]) === provenance.line &&
+        Number(attrs["data-source-column"]) === provenance.column &&
+        (!provenance.component ||
+          attrs["data-component-name"] === provenance.component)
+      ) {
+        count += 1;
+      }
+    }
+  }
+  return Math.max(1, count);
+}
+
 interface DesignData {
   id: string;
   title: string;
@@ -1401,6 +1485,33 @@ function removeAbsolutePositioningFromNodeInHtml(
   }
 }
 
+/** Persist the bridge's narrow fallback for a flow insertion whose authored
+ * stylesheet still resolves the moved child to absolute/fixed after its
+ * editable inline/utility positioning has been stripped. `!important` is
+ * intentional: the stylesheet declaration that forced this path may itself
+ * be important. Left/top are removed because they are inert in static flow
+ * and should not become surprising offsets if positioning changes later. */
+function setFlowPositioningOverrideForNodeInHtml(
+  content: string,
+  nodeAttrId: string,
+): string {
+  if (typeof window === "undefined") return content;
+  try {
+    const doc = new DOMParser().parseFromString(content, "text/html");
+    const element = doc.querySelector(
+      `[data-agent-native-node-id="${CSS.escape(nodeAttrId)}"]`,
+    ) as HTMLElement | null;
+    if (!element) return content;
+    for (const prop of ABS_POSITION_PROPS) {
+      element.style.removeProperty(prop);
+    }
+    element.style.setProperty("position", "static", "important");
+    return `<!DOCTYPE html>\n${doc.documentElement.outerHTML}`;
+  } catch {
+    return content;
+  }
+}
+
 function setAbsolutePositioningForNodeInHtml(
   content: string,
   nodeAttrId: string,
@@ -1436,10 +1547,18 @@ function getAbsolutePositioningForNodeInHtml(
       `[data-agent-native-node-id="${CSS.escape(nodeAttrId)}"]`,
     ) as HTMLElement | null;
     if (!element) return null;
-    return {
-      x: Number.parseFloat(element.style.left || "0") || 0,
-      y: Number.parseFloat(element.style.top || "0") || 0,
-    };
+    // Walk every ancestor up to <body> (authoredElementPosition, shared with
+    // MultiScreenCanvas's drop-target math) instead of reading only this
+    // node's own inline left/top. A node nested two-plus containers deep has
+    // a style.left/top that's relative to its OWN immediate parent, not the
+    // screen root, so a flat read here previously fed
+    // computeReparentedChildPosition two positions from different coordinate
+    // spaces whenever the source/target containers weren't both direct
+    // children of the screen root — producing a garbage delta and making the
+    // dropped element jump away from the cursor. For a root-level node this
+    // walk terminates after one step and returns the exact same left/top as
+    // before, so root-level reparents are unaffected.
+    return authoredElementPosition(element);
   } catch {
     return null;
   }
@@ -2280,13 +2399,18 @@ function queryFirstSelector(
 ): Element | null {
   for (const selector of selectors) {
     if (!selector) continue;
-    try {
-      const match = root.querySelector(selector);
-      if (match) return match;
-    } catch {
-      // Ignore bridge selectors that are valid in the runtime but not in this
-      // DOMParser pass; later aliases may still resolve.
-    }
+    // Fail-closed on ambiguity, same pattern as queryUniqueSelector's other
+    // call sites in this file (and resolveCodeLayerNodeFromBridge in
+    // design-editor/code-layer-state.ts): a selector alias that matches
+    // MULTIPLE elements in this DOMParser pass (an imprecise class-based
+    // alias colliding with unrelated siblings, e.g.) must not silently
+    // resolve to whichever one querySelector happens to return first —
+    // callers pass several alias selectors for the SAME intended node
+    // (codeLayerSelectorAliases) specifically so a later, more specific
+    // alias (e.g. a stable data-attribute id) can still resolve correctly
+    // when an earlier one is ambiguous.
+    const match = queryUniqueSelector(root, selector);
+    if (match) return match;
   }
   return null;
 }
@@ -2708,7 +2832,7 @@ function DesignWorkspaceRail({
   return (
     <nav
       aria-label={t("designEditor.leftRail.label")}
-      className="flex w-[52px] shrink-0 flex-col items-center border-r border-[var(--design-editor-panel-divider-color)] bg-[var(--design-editor-panel-bg)] py-3"
+      className="flex w-[57px] shrink-0 flex-col items-center border-r border-[var(--design-editor-panel-divider-color)] bg-[var(--design-editor-panel-bg)] py-3"
     >
       <div className="mb-3 flex h-8 items-center justify-center">
         {projectMenu}
@@ -3186,6 +3310,7 @@ function DesignBottomToolbar({
   onScale,
   onCommentPin,
   onModeChange,
+  shortcutsPanelOpen,
 }: {
   mode: EditorMode;
   pinMode: boolean;
@@ -3203,6 +3328,7 @@ function DesignBottomToolbar({
   onScale: () => void;
   onCommentPin: () => void;
   onModeChange: (mode: EditorMode) => void;
+  shortcutsPanelOpen: boolean;
 }) {
   const t = useT();
   const shapeTools = new Set<DesignTool>([
@@ -3405,7 +3531,7 @@ function DesignBottomToolbar({
           icon: <IconBrush className="size-4" />,
           shortcut: "Y",
           active: activeTool === "draw" && mode === "annotate" && drawMode,
-          disabled: !hasActiveFile || isOverview,
+          disabled: !hasActiveFile,
           onSelect: onDraw,
         },
       ],
@@ -3449,7 +3575,7 @@ function DesignBottomToolbar({
           icon: <IconBrush className="size-4" />,
           shortcut: "Y",
           active: activeTool === "draw" && mode === "annotate" && drawMode,
-          disabled: !hasActiveFile || isOverview,
+          disabled: !hasActiveFile,
           onSelect: onDraw,
         },
       ],
@@ -3487,7 +3613,11 @@ function DesignBottomToolbar({
   ];
 
   return (
-    <div className="absolute bottom-4 left-1/2 z-[70] flex max-w-[calc(100%-2rem)] -translate-x-1/2 items-center gap-1.5 rounded-xl border border-white/10 bg-[#2c2c2c]/95 p-1.5 text-neutral-100 shadow-[0_22px_55px_-24px_rgba(0,0,0,0.9),0_0_0_1px_rgba(0,0,0,0.25)] backdrop-blur">
+    <div
+      data-design-bottom-toolbar
+      className="fixed left-1/2 z-[70] flex max-w-[calc(100%-2rem)] -translate-x-1/2 items-center gap-1.5 rounded-xl border border-white/10 bg-[#2c2c2c]/95 p-1.5 text-neutral-100 shadow-[0_22px_55px_-24px_rgba(0,0,0,0.9),0_0_0_1px_rgba(0,0,0,0.25)] backdrop-blur transition-[bottom] duration-150 motion-reduce:transition-none"
+      style={{ bottom: shortcutsPanelOpen ? 257 : 16 }}
+    >
       <div className="flex min-w-0 items-center gap-0.5">
         {tools.map((tool) => (
           <DesignToolbarTool
@@ -3772,12 +3902,18 @@ function DesignEditor() {
     requestId: number;
     acks: Array<{ screenId: string; requestId: string; applied: boolean }>;
   } | null>(null);
+  const [runtimeStructureMoveRequest, setRuntimeStructureMoveRequest] =
+    useState<(RuntimeStructureMoveRequest & { screenId: string }) | null>(null);
+  const runtimeStructureMoveRevisionRef = useRef(0);
   const [
     pendingVisualStyleBaselineResetRequest,
     setPendingVisualStyleBaselineResetRequest,
   ] = useState<number | null>(null);
   const pendingVisualStyleEditsRef = useRef<PendingVisualStyleEdit[]>([]);
   const pendingLiveNonStyleEditsRef = useRef<PendingLiveNonStyleEdit[]>([]);
+  const localhostConnectionRootPathByIdRef = useRef<Map<string, string>>(
+    new Map(),
+  );
   const pendingVisualStyleUndoStackRef = useRef<PendingVisualStyleUndoEntry[]>(
     [],
   );
@@ -3914,8 +4050,11 @@ function DesignEditor() {
     useState<CodeWorkbenchActiveFile | null>(null);
   const initialSearchCommandAppliedForIdRef = useRef<string | null>(null);
   const initialUrlSelectionHydratedForIdRef = useRef<string | null>(null);
-  const [leftSidebarWidth, setLeftSidebarWidth] = useState(256);
-  const [rightSidebarWidth, setRightSidebarWidth] = useState(256);
+  // Figma's 56px workspace rail (plus its 1px divider) and 280px Layers/Pages
+  // pane place the content divider at x=337. Keep that total while honoring
+  // resizable 220–420px content range.
+  const [leftSidebarWidth, setLeftSidebarWidth] = useState(280);
+  const [rightSidebarWidth, setRightSidebarWidth] = useState(240);
   // Figma's Cmd+\ "Show/Hide UI": hides the left rail, right inspector panel,
   // and bottom toolbar chrome so the canvas fills the viewport. No prior
   // panel-visibility state existed to hook into (grepped for
@@ -3923,6 +4062,10 @@ function DesignEditor() {
   // so this is a new single boolean gating those three chrome containers'
   // rendering.
   const [uiHidden, setUiHidden] = useState(false);
+  const [keyboardShortcutsOpen, setKeyboardShortcutsOpen] = useState(false);
+  const keyboardShortcutsReturnFocusRef = useRef<HTMLElement | null>(null);
+  const projectMenuTriggerRef = useRef<HTMLButtonElement | null>(null);
+  const suppressProjectMenuReturnFocusRef = useRef(false);
   // PF13: refs to the resizable sidebar containers so a splitter drag can
   // update width imperatively (no React re-render per pointermove) and only
   // commit the final width to state once, on pointerup.
@@ -3946,7 +4089,12 @@ function DesignEditor() {
   const codeLayerOwnerByNodeIdRef = useRef<
     Map<
       string,
-      { fileId: string; node: CodeLayerNode; tree: CodeLayerTreeNode[] }
+      {
+        fileId: string;
+        node: CodeLayerNode;
+        tree: CodeLayerTreeNode[];
+        runtimeOnly: boolean;
+      }
     >
   >(new Map());
   const [overviewSelectedScreenIds, setOverviewSelectedScreenIds] = useState<
@@ -4720,11 +4868,37 @@ function DesignEditor() {
   // into the same agent submission.
   const [drawMode, setDrawMode] = useState(false);
   const [pinMode, setPinMode] = useState(false);
+  // Overview and focused canvases retain separate annotation batches. Each
+  // counter is bumped only for a deliberate close or a confirmed send; they
+  // must not share a signal, or closing a focused-screen batch would also
+  // erase preserved overview-board work while that overlay is hidden.
+  const [overviewAnnotationResetSignal, setOverviewAnnotationResetSignal] =
+    useState(0);
+  const [focusedAnnotationResetSignal, setFocusedAnnotationResetSignal] =
+    useState(0);
+  const [overviewAnnotationSending, setOverviewAnnotationSending] =
+    useState(false);
+  const overviewAnnotationSendingRef = useRef(false);
+  const [focusedAnnotationSending, setFocusedAnnotationSending] =
+    useState(false);
+  const focusedAnnotationSendingCountRef = useRef(0);
+  const handleFocusedAnnotationSendingChange = useCallback(
+    (sending: boolean) => {
+      focusedAnnotationSendingCountRef.current = Math.max(
+        0,
+        focusedAnnotationSendingCountRef.current + (sending ? 1 : -1),
+      );
+      setFocusedAnnotationSending(focusedAnnotationSendingCountRef.current > 0);
+    },
+    [],
+  );
   const [showPrompt, setShowPrompt] = useState(false);
   const [showTweakPrompt, setShowTweakPrompt] = useState(false);
   const [pngExporting, setPngExporting] = useState(false);
   const [svgExporting, setSvgExporting] = useState(false);
+  const [figmaSvgExporting, setFigmaSvgExporting] = useState(false);
   const pngExportingRef = useRef(false);
+  const figmaSvgExportingRef = useRef(false);
   const generateBtnRef = useRef<HTMLButtonElement | null>(null);
   const promptAnchorRef = useRef<HTMLElement | null>(null);
   const tweakPromptAnchorRef = useRef<HTMLElement | null>(null);
@@ -5186,6 +5360,17 @@ function DesignEditor() {
   const openComponentSourceMutation = useActionMutation(
     "open-component-source",
   );
+  // Figma's "Go to main component" — resolves/navigates to the earliest known
+  // instance of the selected component (see go-to-main-component.ts's design
+  // note: this codebase has no separate component-definition markup).
+  const goToMainComponentMutation = useActionMutation("go-to-main-component");
+  // Figma's "Detach instance" (⌥⌘B) — strips the component-instance linkage
+  // from the selected node, leaving its current markup as plain elements.
+  const detachComponentInstanceMutation = useActionMutation(
+    "detach-component-instance",
+  );
+  const [componentSwapPickerRequest, setComponentSwapPickerRequest] =
+    useState(0);
 
   // Board file migration — lazy, idempotent, triggers on design open when
   // designs.data.boardFileId is absent.
@@ -5362,7 +5547,7 @@ function DesignEditor() {
     ) => {
       if (!id) return null;
       return createDesignSaveOutboxEntry({
-        designId: id,
+        designId: id ?? "",
         actorScope: designSaveActorScope,
         actionName: "update-file",
         resourceId: pending.id,
@@ -5691,7 +5876,7 @@ function DesignEditor() {
     (pending: PendingTweakSave) => {
       if (!id) return null;
       return createDesignSaveOutboxEntry({
-        designId: id,
+        designId: id ?? "",
         actorScope: designSaveActorScope,
         actionName: "apply-tweaks",
         resourceId: id,
@@ -6146,6 +6331,9 @@ function DesignEditor() {
   const [liveScreenSnapshotsById, setLiveScreenSnapshotsById] = useState<
     Record<string, LiveScreenSnapshot>
   >({});
+  const [runtimeLayerSnapshotsById, setRuntimeLayerSnapshotsById] = useState<
+    Record<string, RuntimeLayerSnapshot>
+  >({});
   useEffect(() => {
     const liveFileIds = new Set(serverFiles.map((file) => file.id));
     setLiveScreenSnapshotsById((current) => {
@@ -6160,6 +6348,18 @@ function DesignEditor() {
       });
       return changed ? next : current;
     });
+    setRuntimeLayerSnapshotsById((current) => {
+      let changed = false;
+      const next: Record<string, RuntimeLayerSnapshot> = {};
+      Object.entries(current).forEach(([fileId, snapshot]) => {
+        if (!liveFileIds.has(fileId)) {
+          changed = true;
+          return;
+        }
+        next[fileId] = snapshot;
+      });
+      return changed ? next : current;
+    });
   }, [serverFiles]);
   const designDataJson = useMemo(
     () => parseDesignDataJson(design?.data),
@@ -6321,6 +6521,14 @@ function DesignEditor() {
     return typeof boardFile?.content === "string" ? boardFile.content : "";
   }, [boardFileId, files]);
 
+  // Camera/layout operations need the bounds of what the user can actually
+  // see on the board, not the 131,072px logical iframe used for hit testing.
+  // An empty board intentionally contributes no bounds.
+  const boardContentBounds = useMemo(
+    () => getBoardSurfaceContentBounds(boardFileContent),
+    [boardFileContent],
+  );
+
   // Self-heal persisted board content whose NESTED children carry left/top
   // values poisoned by the board-surface offset (near-65536-multiple values
   // written by the historic nest-on-drop coordinate bugs — see
@@ -7934,7 +8142,7 @@ function DesignEditor() {
       const frames = getAllScreenFrameEntries({
         overviewScreens,
         canvasFrameGeometryById,
-        boardFrameGeometry,
+        boardContentBounds,
         boardFileId,
       });
       const bounds = getFrameGroupBounds(frames);
@@ -7954,7 +8162,7 @@ function DesignEditor() {
     },
     [
       boardFileId,
-      boardFrameGeometry,
+      boardContentBounds,
       canvasFrameGeometryById,
       handleCreateScreenFrame,
       overviewScreens,
@@ -8108,7 +8316,13 @@ function DesignEditor() {
       setCollabContentFileId(fileId);
       lastLocalContentRef.current = pendingLocalContent;
       latestActiveContentRef.current = pendingLocalContent;
-      setContentRenderRevision((revision) => revision + 1);
+      if (
+        !replacePreviewContent(pendingLocalContent, null, {
+          forceFullDocument: true,
+        })
+      ) {
+        setContentRenderRevision((revision) => revision + 1);
+      }
       // Full delete+insert with an untracked origin: the UndoManager only
       // tracks LOCAL_EDIT_ORIGIN, so this rewrite is invisible to it. Clear
       // the undo stack so a subsequent Cmd+Z can't replay a tracked delta
@@ -8146,7 +8360,13 @@ function DesignEditor() {
         if (activeFile?.updatedAt) {
           lastAppliedFileUpdatedAtRef.current = activeFile.updatedAt;
         }
-        setContentRenderRevision((revision) => revision + 1);
+        if (
+          !replacePreviewContent(storedContent, null, {
+            forceFullDocument: true,
+          })
+        ) {
+          setContentRenderRevision((revision) => revision + 1);
+        }
         // Untracked full rewrite — see clear() note above.
         undoManagerRef.current?.clear(true, false);
         ydoc.transact(() => {
@@ -8177,7 +8397,9 @@ function DesignEditor() {
         setCollabContent(text);
         setCollabContentFileId(fileId);
         latestActiveContentRef.current = text;
-        setContentRenderRevision((revision) => revision + 1);
+        if (!replacePreviewContent(text, null, { forceFullDocument: true })) {
+          setContentRenderRevision((revision) => revision + 1);
+        }
       }
     }
   }, [
@@ -8232,7 +8454,13 @@ function DesignEditor() {
         setCollabContentFileId(fileId);
         lastLocalContentRef.current = pendingLocalContent;
         latestActiveContentRef.current = pendingLocalContent;
-        setContentRenderRevision((revision) => revision + 1);
+        if (
+          !replacePreviewContent(pendingLocalContent, null, {
+            forceFullDocument: true,
+          })
+        ) {
+          setContentRenderRevision((revision) => revision + 1);
+        }
         // Untracked full rewrite — see clear() note in the seed effect above.
         undoManagerRef.current?.clear(true, false);
         ydoc.transact(() => {
@@ -8246,7 +8474,13 @@ function DesignEditor() {
       latestActiveContentRef.current = next;
       if (isLocalEdit) {
         lastLocalContentRef.current = next;
-      } else if (next !== previousActiveContent) {
+      } else if (
+        shouldApplyRemotePreviewContent({
+          isLocalEdit,
+          previousContent: previousActiveContent,
+          nextContent: next,
+        })
+      ) {
         // Holistic flash pipeline: a remote (peer/agent) edit arriving mid-
         // session is exactly the "remote adoption" case that should apply
         // in-place — this is not a file switch or initial mount. Try the
@@ -8384,7 +8618,11 @@ function DesignEditor() {
       lastAckedFileContentHashRef.current[activeFile.id] =
         sourceContentHash(dbContent);
       if (dbUpdatedAt) lastAppliedFileUpdatedAtRef.current = dbUpdatedAt;
-      setContentRenderRevision((revision) => revision + 1);
+      if (
+        !replacePreviewContent(dbContent, null, { forceFullDocument: true })
+      ) {
+        setContentRenderRevision((revision) => revision + 1);
+      }
 
       if (isLeadClient && ydoc) {
         const ytext = ydoc.getText("content");
@@ -8415,9 +8653,18 @@ function DesignEditor() {
     }
 
     // Only adopt genuinely newer content. No baseline yet (fresh file load)
-    // always adopts so a stale persisted Y.Doc can't shadow newer SQL.
+    // always adopts so a stale persisted Y.Doc can't shadow newer SQL. See
+    // shouldAdoptExternalReconcileContent's doc comment
+    // (design-editor/editor-session.ts) for the same-millisecond tie-break
+    // fix this closes: a strict `>` used to silently drop a real external
+    // write that landed in the same millisecond as the one already applied,
+    // whenever agentActive was false.
     const applied = lastAppliedFileUpdatedAtRef.current;
-    const externalNewer = !applied || (!!dbUpdatedAt && dbUpdatedAt > applied);
+    const externalNewer = shouldAdoptExternalReconcileContent({
+      appliedUpdatedAt: applied,
+      dbUpdatedAt,
+      agentActive,
+    });
     const staleAgentEchoPossible =
       agentActive &&
       !!applied &&
@@ -8446,7 +8693,13 @@ function DesignEditor() {
             lastAckedFileContentHashRef.current[expectedFileId] =
               sourceContentHash(expectedContent);
             lastAppliedFileUpdatedAtRef.current = expectedUpdatedAt;
-            setContentRenderRevision((revision) => revision + 1);
+            if (
+              !replacePreviewContent(expectedContent, null, {
+                forceFullDocument: true,
+              })
+            ) {
+              setContentRenderRevision((revision) => revision + 1);
+            }
 
             if (isLeadClient && ydoc) {
               const ytext = ydoc.getText("content");
@@ -8476,7 +8729,9 @@ function DesignEditor() {
     lastAckedFileContentHashRef.current[activeFile.id] =
       sourceContentHash(dbContent);
     if (dbUpdatedAt) lastAppliedFileUpdatedAtRef.current = dbUpdatedAt;
-    setContentRenderRevision((revision) => revision + 1);
+    if (!replacePreviewContent(dbContent, null, { forceFullDocument: true })) {
+      setContentRenderRevision((revision) => revision + 1);
+    }
 
     // Lead client mirrors it into the shared Y.Doc so other open clients
     // receive it through Yjs and the durable collab state stays in step. The
@@ -8520,6 +8775,9 @@ function DesignEditor() {
 
   // Canvas container ref for cursor overlay coordinate mapping.
   const canvasContextMenuRef = useRef<CanvasContextMenuHandle | null>(null);
+  const [canvasLayerHitCandidates, setCanvasLayerHitCandidates] = useState<
+    CanvasLayerHitCandidate[]
+  >([]);
   // L12: imperative handle so Cmd+R and the canvas context-menu Rename item
   // can start the layers panel's real inline rename editor on the selected
   // layer (see beginRename in LayersPanel.tsx).
@@ -9234,6 +9492,46 @@ function DesignEditor() {
     },
     [],
   );
+  const handleScreenRuntimeLayerSnapshot = useCallback(
+    (screenId: string, snapshot: RuntimeLayerSnapshot) => {
+      setRuntimeLayerSnapshotsById((current) => {
+        const existing = current[screenId];
+        if (
+          existing?.html === snapshot.html &&
+          existing.nodeCount === snapshot.nodeCount
+        ) {
+          return current;
+        }
+        return { ...current, [screenId]: snapshot };
+      });
+    },
+    [],
+  );
+  // Per-screen stable identity for DesignCanvas's onRuntimeLayerSnapshot prop
+  // (mirrors the embeddedFrameCacheRef pattern above). The overview map below
+  // previously passed a fresh `(snapshot) => handleScreenRuntimeLayerSnapshot(
+  // screen.id, snapshot)` arrow on every render for every rendered screen;
+  // since handleScreenRuntimeLayerSnapshot itself never changes identity
+  // (empty deps), a bound function per screenId can be created once and
+  // reused forever. DesignCanvas lists onRuntimeLayerSnapshot as a dependency
+  // of its window "message" listener effect, so an unstable per-render
+  // identity here was tearing down and re-adding that listener on every
+  // MultiScreenCanvas render.
+  const runtimeLayerSnapshotCallbacksRef = useRef<
+    Map<string, (snapshot: RuntimeLayerSnapshot) => void>
+  >(new Map());
+  const getRuntimeLayerSnapshotCallback = useCallback(
+    (screenId: string) => {
+      const cache = runtimeLayerSnapshotCallbacksRef.current;
+      const cached = cache.get(screenId);
+      if (cached) return cached;
+      const callback = (snapshot: RuntimeLayerSnapshot) =>
+        handleScreenRuntimeLayerSnapshot(screenId, snapshot);
+      cache.set(screenId, callback);
+      return callback;
+    },
+    [handleScreenRuntimeLayerSnapshot],
+  );
   const updateLiveScreenSnapshotContent = useCallback(
     (
       screenId: string,
@@ -9309,6 +9607,22 @@ function DesignEditor() {
         screenName: prettyScreenName(fallbackName),
         selector,
         sourceId,
+        sourceAnchor: reactSourceAnchorForPendingEdit({
+          info: elementInfo,
+          id: sourceId ?? undefined,
+          rootPath: (() => {
+            const connectionId = overviewScreens.find(
+              (candidate) => candidate.id === screenId,
+            )?.connectionId;
+            return connectionId
+              ? localhostConnectionRootPathByIdRef.current.get(connectionId)
+              : undefined;
+          })(),
+          runtimeMultiplicity: runtimeMultiplicityForElementProvenance(
+            runtimeLayerSnapshotsById,
+            elementInfo,
+          ),
+        }),
         tagName: elementInfo?.tagName ?? null,
         classes: elementInfo?.classes ?? [],
         styles: stylePatch,
@@ -9393,6 +9707,8 @@ function DesignEditor() {
       canEditDesign,
       files,
       getProjectionContentForScreen,
+      overviewScreens,
+      runtimeLayerSnapshotsById,
       selectedElement?.computedStyles,
       selectedElement?.inlineStyles,
       selectedElement?.sourceId,
@@ -9437,6 +9753,22 @@ function DesignEditor() {
         screenName: prettyScreenName(fallbackName),
         selector,
         sourceId,
+        sourceAnchor: reactSourceAnchorForPendingEdit({
+          info: elementInfo,
+          id: sourceId ?? undefined,
+          rootPath: (() => {
+            const connectionId = overviewScreens.find(
+              (candidate) => candidate.id === screenId,
+            )?.connectionId;
+            return connectionId
+              ? localhostConnectionRootPathByIdRef.current.get(connectionId)
+              : undefined;
+          })(),
+          runtimeMultiplicity: runtimeMultiplicityForElementProvenance(
+            runtimeLayerSnapshotsById,
+            elementInfo,
+          ),
+        }),
         tagName: elementInfo?.tagName ?? null,
         classes: elementInfo?.classes ?? [],
         value,
@@ -9470,6 +9802,8 @@ function DesignEditor() {
       activeFile?.id,
       canEditDesign,
       files,
+      overviewScreens,
+      runtimeLayerSnapshotsById,
       selectedElement?.htmlContent,
       selectedElement?.sourceId,
       selectedElement?.textContent,
@@ -9486,6 +9820,7 @@ function DesignEditor() {
       details?: {
         sourceId?: string;
         anchorSourceId?: string;
+        anchorElementInfo?: ElementInfo;
         requestId?: string;
       },
     ) => {
@@ -9501,8 +9836,40 @@ function DesignEditor() {
         screenName: prettyScreenName(fallbackName),
         selector,
         sourceId: details?.sourceId ?? elementInfo?.sourceId ?? null,
+        sourceAnchor: reactSourceAnchorForPendingEdit({
+          info: elementInfo,
+          id: details?.sourceId ?? elementInfo?.sourceId,
+          rootPath: (() => {
+            const connectionId = overviewScreens.find(
+              (candidate) => candidate.id === screenId,
+            )?.connectionId;
+            return connectionId
+              ? localhostConnectionRootPathByIdRef.current.get(connectionId)
+              : undefined;
+          })(),
+          runtimeMultiplicity: runtimeMultiplicityForElementProvenance(
+            runtimeLayerSnapshotsById,
+            elementInfo,
+          ),
+        }),
         anchorSelector,
         anchorSourceId: details?.anchorSourceId ?? null,
+        anchorSourceAnchor: reactSourceAnchorForPendingEdit({
+          info: details?.anchorElementInfo,
+          id: details?.anchorSourceId,
+          rootPath: (() => {
+            const connectionId = overviewScreens.find(
+              (candidate) => candidate.id === screenId,
+            )?.connectionId;
+            return connectionId
+              ? localhostConnectionRootPathByIdRef.current.get(connectionId)
+              : undefined;
+          })(),
+          runtimeMultiplicity: runtimeMultiplicityForElementProvenance(
+            runtimeLayerSnapshotsById,
+            details?.anchorElementInfo,
+          ),
+        }),
         placement,
         requestId: details?.requestId,
         updatedAt: Date.now(),
@@ -9519,7 +9886,7 @@ function DesignEditor() {
       pendingLiveNonStyleEditsRef.current = nextPending;
       setPendingLiveNonStyleEdits(nextPending);
     },
-    [canEditDesign, files],
+    [canEditDesign, files, overviewScreens, runtimeLayerSnapshotsById],
   );
   const activeProjectionContent =
     activeFile?.id !== undefined
@@ -9745,6 +10112,25 @@ function DesignEditor() {
     [id, activeFileId, openComponentSourceMutation],
   );
 
+  // Stable identity for the single-screen-mode DesignCanvas's
+  // onRuntimeLayerSnapshot prop, mirroring getRuntimeLayerSnapshotCallback
+  // above for the overview per-screen map. That inline call site previously
+  // built a fresh `(snapshot) => { if (!activeFile?.id) return;
+  // handleScreenRuntimeLayerSnapshot(activeFile.id, snapshot); }` arrow on
+  // every render; since DesignCanvas lists onRuntimeLayerSnapshot as a
+  // dependency of its window "message" listener effect, that unstable
+  // identity was tearing down and re-adding the listener on every render
+  // while in single-screen mode. Scoped to activeFile?.id (rather than a
+  // per-screenId cache) since single-screen mode only ever has one active
+  // screen at a time.
+  const handleActiveRuntimeLayerSnapshot = useCallback(
+    (snapshot: RuntimeLayerSnapshot) => {
+      if (!activeFile?.id) return;
+      handleScreenRuntimeLayerSnapshot(activeFile.id, snapshot);
+    },
+    [activeFile?.id, handleScreenRuntimeLayerSnapshot],
+  );
+
   // The selected node id, when it already is a recognised component instance —
   // unlocks the contextual Component section at the top of the Design tab.
   const selectedComponentNodeId = useMemo(() => {
@@ -10153,12 +10539,24 @@ function DesignEditor() {
   const nonActiveProjectionCacheRef = useRef<
     Map<string, { contentRef: string; projection: CodeLayerProjection }>
   >(new Map());
+  const runtimeProjectionCacheRef = useRef<
+    Map<string, { contentRef: string; projection: CodeLayerProjection }>
+  >(new Map());
   const getCodeLayerProjectionForScreen = useCallback(
     (screenId: string) => {
-      if (screenId === activeFile?.id) return activeCodeLayerProjection;
       if (!fileContentById.has(screenId)) return null;
       const content = getProjectionContentForScreen(screenId);
       const cache = nonActiveProjectionCacheRef.current;
+      if (screenId === activeFile?.id) {
+        // Seed the same cache while this file is active. When selection moves
+        // to another screen, the old active screen can then become non-active
+        // without paying for a fresh full HTML projection on that click.
+        cache.set(screenId, {
+          contentRef: content,
+          projection: activeCodeLayerProjection,
+        });
+        return activeCodeLayerProjection;
+      }
       const cached = cache.get(screenId);
       if (cached && cached.contentRef === content) return cached.projection;
       const projection = buildCodeLayerProjection(content);
@@ -10172,6 +10570,17 @@ function DesignEditor() {
       getProjectionContentForScreen,
     ],
   );
+  const getRuntimeCodeLayerProjection = useCallback(
+    (screenId: string, content: string): CodeLayerProjection => {
+      const cache = runtimeProjectionCacheRef.current;
+      const cached = cache.get(screenId);
+      if (cached && cached.contentRef === content) return cached.projection;
+      const projection = buildCodeLayerProjection(content);
+      cache.set(screenId, { contentRef: content, projection });
+      return projection;
+    },
+    [],
+  );
 
   const replacePreviewContent = useCallback(
     (
@@ -10599,6 +11008,7 @@ function DesignEditor() {
     lastScheduledMotionAutosaveRevisionRef.current = revisionAtSchedule;
     clearMotionAutosaveTimer();
     const fileIdAtSchedule = activeFile.id;
+    const fileRevisionAtSchedule = activeFile.updatedAt;
     const fire = () => {
       if (motionAutosaveRevisionRef.current !== revisionAtSchedule) return;
       // Drop empty tracks defensively (a 0-keyframe track fails the action
@@ -10651,6 +11061,7 @@ function DesignEditor() {
           durationMs: motionDurationMs,
           defaultEase: motionDefaultEase,
           currentContent,
+          revision: fileRevisionAtSchedule,
           includeContent: false,
         },
         {
@@ -10727,7 +11138,8 @@ function DesignEditor() {
                 localMotionCss,
               );
               applyFileContentUpdate(response.fileId, patchedContent, {
-                refreshPreview: true,
+                refreshPreview: false,
+                forcePreviewFullDocument: true,
                 recordHistory: false,
                 // Without concurrent edits, adopt the server's write as-is
                 // (no re-save). With concurrent edits the merged content must
@@ -10776,6 +11188,7 @@ function DesignEditor() {
     };
   }, [
     activeFile?.id,
+    activeFile?.updatedAt,
     activeContent,
     applyFileContentUpdate,
     applyMotionEdit,
@@ -10814,6 +11227,128 @@ function DesignEditor() {
     [activeFile?.id, applyFileContentUpdate],
   );
 
+  // Instance-only operations (Figma's Go to main component / Swap instance /
+  // Detach instance), reachable from the canvas context menu and — for
+  // detach — the Cmd+Alt+B hotkey. The searchable Swap instance picker itself
+  // lives in the Component inspector section (component-section.tsx, which
+  // already wires its own detach/swap/go-to-main mutations and calls
+  // onComponentPropApplied on success). Go-to-main and detach call their
+  // actions here; Swap opens that canonical picker directly so both entry
+  // points share one catalog and mutation path.
+  const handleGoToMainComponentMenuAction = useCallback(() => {
+    if (!id || !selectedComponentNodeId) return;
+    goToMainComponentMutation.mutate(
+      {
+        designId: id,
+        nodeId: selectedComponentNodeId,
+        fileId: activeFileId ?? undefined,
+      },
+      {
+        onSuccess: (result: {
+          isMain?: boolean;
+          ctaRequired?: boolean;
+          ctaMessage?: string;
+          note?: string;
+        }) => {
+          if (result.ctaRequired) {
+            toast.error(
+              result.ctaMessage ??
+                t("designEditor.componentInstances.goToMainUnavailable"),
+            );
+            return;
+          }
+          if (result.isMain) {
+            toast(
+              result.note ??
+                t("designEditor.componentInstances.onlyKnownInstance"),
+            );
+          }
+        },
+        onError: () =>
+          toast.error(t("designEditor.componentInstances.resolveMainFailed")),
+      },
+    );
+  }, [activeFileId, goToMainComponentMutation, id, selectedComponentNodeId, t]);
+
+  const handleDetachInstanceMenuAction = useCallback(() => {
+    if (!id || !selectedComponentNodeId) return;
+    detachComponentInstanceMutation.mutate(
+      {
+        designId: id,
+        nodeId: selectedComponentNodeId,
+        fileId: activeFileId ?? undefined,
+        ...(activeContent
+          ? {
+              source: {
+                currentContent: activeContent,
+                ...(activeFile?.updatedAt
+                  ? { revision: activeFile.updatedAt }
+                  : {}),
+              },
+            }
+          : {}),
+      },
+      {
+        onSuccess: (result: {
+          detached?: boolean;
+          conflict?: boolean;
+          ctaRequired?: boolean;
+          error?: string;
+          ctaMessage?: string;
+          note?: string;
+          fileId?: string;
+          content?: string;
+          updatedAt?: string;
+        }) => {
+          if (result.conflict || result.ctaRequired) {
+            toast.error(
+              result.error ??
+                result.ctaMessage ??
+                t("designEditor.componentInstances.detachFailed"),
+            );
+            return;
+          }
+          if (result.detached) {
+            toast(result.note ?? t("designEditor.componentInstances.detached"));
+            if (
+              typeof result.fileId === "string" &&
+              typeof result.content === "string"
+            ) {
+              handleComponentPropApplied(
+                result.fileId,
+                result.content,
+                result.updatedAt,
+              );
+            }
+          }
+        },
+        onError: () =>
+          toast.error(t("designEditor.componentInstances.detachFailed")),
+      },
+    );
+  }, [
+    activeFileId,
+    activeContent,
+    activeFile?.updatedAt,
+    detachComponentInstanceMutation,
+    handleComponentPropApplied,
+    id,
+    selectedComponentNodeId,
+    t,
+  ]);
+
+  // Open the inspector's canonical searchable picker directly. Keeping one
+  // picker avoids two catalogs drifting while still matching Figma's
+  // immediate context-menu behavior (the click opens choices; it doesn't
+  // merely tell the user where to look).
+  const handleSwapInstanceMenuAction = useCallback(() => {
+    if (!id || !selectedComponentNodeId) return;
+    setUiHidden(false);
+    setMode("edit");
+    setActiveInspectorTab("design");
+    setComponentSwapPickerRequest((request) => request + 1);
+  }, [id, selectedComponentNodeId]);
+
   const handleReviewFixApplied = useCallback(
     (
       _finding: A11yFinding,
@@ -11368,10 +11903,20 @@ function DesignEditor() {
   const handleMoveTool = useCallback(() => {
     if (!canEditDesign) return;
     blurActiveDesignEditableTarget();
-    setActiveTool("move");
-    setMode("edit");
-    setDrawMode(false);
-    setPinMode(false);
+    // Toolbar dual-active fix: every other tool-switch handler
+    // (handleFrameTool/handleShapeTool/handleTextTool/handlePenTool) wraps
+    // its setActiveTool call in flushSync so the toolbar's active/pressed
+    // classes commit synchronously with the click. This one didn't, so a
+    // rapid V-after-Rectangle press could paint the new tool "pressed" while
+    // React hadn't yet flushed the re-render that clears the previous tool's
+    // "active" class, leaving both visually active until an unrelated
+    // re-render (e.g. the next click) caught it up.
+    flushSync(() => {
+      setActiveTool("move");
+      setMode("edit");
+      setDrawMode(false);
+      setPinMode(false);
+    });
   }, [canEditDesign]);
 
   const handleFrameTool = useCallback(() => {
@@ -11588,6 +12133,36 @@ function DesignEditor() {
     };
   }, [embedded, pendingQuestions]);
 
+  // PICK-RACE: a native (non-React-state) ref tracking whether Shift is
+  // currently physically held, same pattern as spacePanStashedToolRef above.
+  // handleOverviewScreenPick (below) reads this to tell a shift-click
+  // multi-select toggle apart from a plain single-screen pick — see its
+  // usage for the full race this closes.
+  const shiftKeyHeldRef = useRef(false);
+  useEffect(() => {
+    const handleShiftKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Shift") shiftKeyHeldRef.current = true;
+    };
+    const handleShiftKeyUp = (event: KeyboardEvent) => {
+      if (event.key === "Shift") shiftKeyHeldRef.current = false;
+    };
+    const handleShiftBlur = () => {
+      shiftKeyHeldRef.current = false;
+    };
+    window.addEventListener("keydown", handleShiftKeyDown, { capture: true });
+    window.addEventListener("keyup", handleShiftKeyUp, { capture: true });
+    window.addEventListener("blur", handleShiftBlur);
+    return () => {
+      window.removeEventListener("keydown", handleShiftKeyDown, {
+        capture: true,
+      });
+      window.removeEventListener("keyup", handleShiftKeyUp, {
+        capture: true,
+      });
+      window.removeEventListener("blur", handleShiftBlur);
+    };
+  }, []);
+
   const handleScaleTool = useCallback(() => {
     if (!activeFile || !canEditDesign) return;
     blurActiveDesignEditableTarget();
@@ -11599,22 +12174,9 @@ function DesignEditor() {
 
   const handleDrawTool = useCallback(() => {
     if (!activeFile || !canEditDesign) return;
-    // Y mirrors the comment tool's overview behavior: enter the active screen
-    // and arm annotation drawing in the same view transition. Returning early
-    // in overview made the shortcut look handled while doing nothing.
-    if (viewModeRef.current === "overview") {
-      viewModeRef.current = "single";
-      setActiveFileId(activeFile.id);
-      setScreenZoom(FOCUSED_SCREEN_ZOOM);
-      setViewMode("single");
-      setSelectedElement(null);
-      setHoveredElement(null);
-      setActiveTool("draw");
-      setMode("annotate");
-      setDrawMode(true);
-      setPinMode(false);
-      return;
-    }
+    // Annotation is a viewport-level overlay in overview, so it deliberately
+    // stays on the all-screens board. Switching to single view here used to
+    // unmount every overview iframe and produced a blank/flashy target.
     setActiveTool("draw");
     setMode("annotate");
     setSelectedElement(null);
@@ -11622,9 +12184,94 @@ function DesignEditor() {
     setPinMode(false);
   }, [activeFile, canEditDesign]);
 
-  useEffect(() => {
-    if (files.length > 0) resetAgentGenerating();
-  }, [files.length, resetAgentGenerating]);
+  const handleExitOverviewDrawMode = useCallback(() => {
+    setDrawMode(false);
+    setPinMode(false);
+    setActiveTool("move");
+    setMode("edit");
+    // Deliberate discard (X button or a confirmed Send) — see
+    // overviewAnnotationResetSignal's docblock. Entering a focused screen can
+    // hide this overlay, but must not clear its separate board-wide batch.
+    setOverviewAnnotationResetSignal((signal) => signal + 1);
+  }, []);
+
+  const handleExitFocusedDrawMode = useCallback(() => {
+    setDrawMode(false);
+    setPinMode(false);
+    setActiveTool("move");
+    setMode("edit");
+    setFocusedAnnotationResetSignal((signal) => signal + 1);
+  }, []);
+
+  const handleSendOverviewAnnotations = useCallback(
+    async (
+      annotations: DrawAnnotation[],
+      instruction: string,
+      canvasSize: { width: number; height: number },
+    ) => {
+      if (overviewAnnotationSendingRef.current) return;
+      const container = canvasContainerRef.current;
+      const viewportMap = container
+        ? collectOverviewAnnotationViewportMap({
+            container,
+            screens: overviewScreens.map((screen) => ({
+              id: screen.id,
+              name: prettyScreenName(screen.filename),
+            })),
+            zoom: overviewCanvasZoom,
+          })
+        : {
+            width: canvasSize.width,
+            height: canvasSize.height,
+            zoom: overviewCanvasZoom,
+            screens: [],
+          };
+      const message = formatOverviewAnnotationMessage({
+        designId: id ?? "",
+        designTitle: design?.title,
+        annotations,
+        instruction,
+        viewportMap,
+      });
+
+      overviewAnnotationSendingRef.current = true;
+      setOverviewAnnotationSending(true);
+      try {
+        const result = await sendToDesignAgentChatAndConfirm({
+          message,
+          submit: true,
+          openSidebar: true,
+        });
+        if (!result.delivered) {
+          throw new Error(
+            `Overview annotation message was not delivered to the agent chat (${result.reason ?? "unknown"})`,
+          );
+        }
+        handleExitOverviewDrawMode();
+      } catch (error) {
+        console.error(
+          "[DesignEditor] failed to submit overview drawing:",
+          error,
+        );
+        toast.error(t("designEditor.toasts.annotationSendError"));
+      } finally {
+        overviewAnnotationSendingRef.current = false;
+        setOverviewAnnotationSending(false);
+      }
+    },
+    [
+      design?.title,
+      handleExitOverviewDrawMode,
+      id,
+      overviewCanvasZoom,
+      overviewScreens,
+      t,
+    ],
+  );
+
+  useEffect(() => {
+    if (files.length > 0) resetAgentGenerating();
+  }, [files.length, resetAgentGenerating]);
 
   // Parse design.data for agent-supplied tweaks. The agent writes a JSON blob
   // to designs.data containing { tweaks: TweakDefinition[], ... }; we surface
@@ -12198,15 +12845,28 @@ function DesignEditor() {
   );
 
   const handleScreenElementSelect = useCallback(
-    (screenId: string, info: ElementInfo, intent?: ElementSelectionIntent) => {
+    (
+      screenId: string,
+      info: ElementInfo,
+      intent?: ElementSelectionIntent,
+      options: { persistPendingNodeId?: boolean } = {},
+    ) => {
       const pendingLayerId = pendingOverviewLayerSelectionRef.current;
       const pendingScreenId = pendingOverviewScreenSelectionRef.current;
+      const projection = getCodeLayerProjectionForScreen(screenId);
+      const canonical = projection
+        ? canonicalizeElementInfoFromProjection(projection, info)
+        : info;
+      const node = projection
+        ? resolveCodeLayerNodeFromElementInfo(projection, canonical)
+        : null;
       if (
         shouldIgnoreOverviewLayerCreationEcho({
           pendingLayerId,
           pendingScreenId,
           screenId,
-          info,
+          info: canonical,
+          resolvedLayerId: node?.id,
           event: "select",
         })
       ) {
@@ -12216,13 +12876,6 @@ function DesignEditor() {
       pendingOverviewLayerSelectionRef.current = null;
       clearPendingOverviewLayerSelectionTimer();
       setCreatedOverviewLayerSelection(null);
-      const projection = getCodeLayerProjectionForScreen(screenId);
-      const canonical = projection
-        ? canonicalizeElementInfoFromProjection(projection, info)
-        : info;
-      const node = projection
-        ? resolveCodeLayerNodeFromElementInfo(projection, canonical)
-        : null;
       if (
         shouldPreserveBlockedOverviewLayerSelectionRef.current(screenId) &&
         (isScreenRootElementInfo(canonical) ||
@@ -12252,6 +12905,7 @@ function DesignEditor() {
       const pendingNodeId = (canonical as { pendingNodeId?: string })
         .pendingNodeId;
       if (
+        options.persistPendingNodeId !== false &&
         !isScreenRootElementInfo(canonical) &&
         pendingNodeId &&
         !canonical.sourceId &&
@@ -12281,6 +12935,7 @@ function DesignEditor() {
           }
         }
       } else if (
+        options.persistPendingNodeId !== false &&
         // Fallback sweep: an element the bridge didn't mint a pendingNodeId
         // for (older bridge instance, or a node resolved only through the
         // host's own projection) but that still lacks a stable id per the
@@ -12609,16 +13264,16 @@ function DesignEditor() {
       const container = canvasContainerRef.current;
       const menu = canvasContextMenuRef.current;
       if (!container || !menu) return;
-      if (payload.info) {
+      const contextScreenId =
+        payload.screenId ?? activeFile?.id ?? activeFileId ?? null;
+      flushSync(() => {
+        setCanvasLayerHitCandidates(payload.layerCandidates ?? []);
+      });
+      if (payload.info && contextScreenId) {
         flushSync(() => {
-          setSelectedElement(
-            payload.info
-              ? canonicalizeElementInfoFromProjection(
-                  activeCodeLayerProjection,
-                  payload.info,
-                )
-              : null,
-          );
+          handleScreenElementSelect(contextScreenId, payload.info!, undefined, {
+            persistPendingNodeId: false,
+          });
         });
         focusDesignInspectorForSelection();
       }
@@ -12630,9 +13285,82 @@ function DesignEditor() {
         typeof payload.viewportClientY === "number"
           ? payload.viewportClientY
           : payload.clientY;
-      menu.openAt({ clientX, clientY });
+      // PASTE-HERE-IN-CONTENT: this imperative openAt() call bypasses
+      // CanvasContextMenu's own onContextMenuCapture handler entirely — the
+      // ONLY place that normally calls getCanvasPoint to attach canvasX/
+      // canvasY to the menu's point. Without computing it here too, a
+      // right-click that lands ON rendered screen content (an element, or
+      // empty in-screen space — as opposed to the shared canvas background,
+      // which still goes through onContextMenuCapture) never got a
+      // canvasX/canvasY at all, so "Paste here" from it silently degraded to
+      // the position-less cascade/offset paste instead of landing under the
+      // cursor. Overview screens each carry their own screenId through the
+      // context-menu bridge, including non-active screens, so target that
+      // exact iframe rather than the currently-active screen. Otherwise
+      // Paste here would translate the pointer through the wrong frame just
+      // before Select layer activates the right-clicked screen.
+      const iframeForPoint =
+        viewMode === "single"
+          ? container.querySelector<HTMLElement>("[data-design-preview-iframe]")
+          : findCanvasIframeForScreen(
+              container,
+              contextScreenId ?? "",
+              boardFileId ?? undefined,
+            );
+      const liveOverviewZoom =
+        viewMode === "overview"
+          ? readOverviewZoomPercentFromTransform(
+              container.querySelector<HTMLElement>(
+                "[data-multi-screen-canvas-world]",
+              )?.style.transform,
+              overviewCanvasZoom,
+            )
+          : overviewCanvasZoom;
+      const canvasPoint = computeIframeLocalCanvasPoint({
+        clientX,
+        clientY,
+        iframeRect: iframeForPoint?.getBoundingClientRect() ?? null,
+        zoomPercent: viewMode === "single" ? zoom : liveOverviewZoom,
+      });
+      menu.openAt({
+        clientX,
+        clientY,
+        ...(canvasPoint
+          ? { canvasX: canvasPoint.x, canvasY: canvasPoint.y }
+          : {}),
+      });
     },
-    [activeCodeLayerProjection, focusDesignInspectorForSelection],
+    [
+      activeFile?.id,
+      activeFileId,
+      boardFileId,
+      focusDesignInspectorForSelection,
+      handleScreenElementSelect,
+      overviewCanvasZoom,
+      viewMode,
+      zoom,
+    ],
+  );
+
+  const handleContextMenuSelectLayer = useCallback(
+    (candidate: CanvasLayerHitCandidate) => {
+      const screenId = candidate.screenId ?? activeFile?.id ?? activeFileId;
+      if (!screenId) return;
+      handleScreenElementSelect(screenId, candidate.info, undefined, {
+        // The Select layer submenu is selection-only. In particular, choosing
+        // a local React runtime host must never stamp wrapper source or make
+        // any structural/source mutation merely because it was behind another
+        // layer at the pointer location.
+        persistPendingNodeId: false,
+      });
+      focusDesignInspectorForSelection();
+    },
+    [
+      activeFile?.id,
+      activeFileId,
+      focusDesignInspectorForSelection,
+      handleScreenElementSelect,
+    ],
   );
 
   const commitVisualStyles = useCallback(
@@ -12981,6 +13709,29 @@ function DesignEditor() {
           } else {
             recordLocalContentHistoryEntry(change);
           }
+        } else if (
+          yjsHistoryAvailable &&
+          !suppressContentHistoryRef.current &&
+          baseContent !== resolvedNextContent
+        ) {
+          // BUG-UNDO-RESIZE-STACK: mirror the same before/after into the local
+          // fallback stack that applyLocalContentUpdate already maintains for
+          // every other commit path (text edits, moves, structure changes).
+          // The Yjs UndoManager is destroyed and recreated whenever `docId`
+          // changes — a view-mode switch, a zoom-triggered re-render, or a
+          // breakpoint switch — which silently drops its entire undo stack.
+          // Without this mirror, a gesture-driven style/resize commit (the
+          // ONLY commit path that skipped this call) became permanently
+          // unrecoverable the moment that happened: handleUndo's um.canUndo()
+          // goes false with nothing to fall back to, so Cmd+Z does nothing at
+          // all for a resize-drag even though every other edit kind still has
+          // a working fallback. Only consulted once Yjs itself has nothing
+          // left to undo (see handleUndo), so this never causes a double-undo.
+          recordLocalContentHistoryChangeFallback({
+            fileId: activeFile.id,
+            before: baseContent,
+            after: resolvedNextContent,
+          });
         }
 
         setCollabContent(resolvedNextContent);
@@ -13061,6 +13812,7 @@ function DesignEditor() {
       queueFileContentSave,
       recordContentHistoryEntry,
       recordLocalContentHistoryEntry,
+      recordLocalContentHistoryChangeFallback,
       replacePreviewContent,
       selectedElement,
       t,
@@ -13381,7 +14133,8 @@ function DesignEditor() {
             }).content;
       if (nextContent === baseContent) return false;
       applyFileContentUpdate(activeFile.id, nextContent, {
-        refreshPreview: true,
+        refreshPreview: false,
+        forcePreviewFullDocument: true,
       });
       return true;
     },
@@ -13432,7 +14185,8 @@ function DesignEditor() {
       );
       if (nextContent === baseContent) return true;
       applyFileContentUpdate(activeFile.id, nextContent, {
-        refreshPreview: true,
+        refreshPreview: false,
+        forcePreviewFullDocument: true,
       });
       return true;
     },
@@ -13526,7 +14280,16 @@ function DesignEditor() {
         if (commitRelativeStyleDeltaToSelectedLayers(property, relativeDelta))
           return;
       }
-      if (commitStylesToSelectedLayers({ [property]: value })) return;
+      // Page properties render only when there is no concrete DOM element
+      // selection. Screen/layer ids can remain in the broader selection ref
+      // while Escape exposes Page (especially after overview/breakpoint
+      // navigation); never let that stale structural selection hijack a page
+      // background/font edit away from the body.
+      if (
+        selectedElement &&
+        commitStylesToSelectedLayers({ [property]: value })
+      )
+        return;
       commitVisualStyles(selector, { [property]: value });
     },
     [
@@ -13535,6 +14298,7 @@ function DesignEditor() {
       commitStylesToSelectedLayers,
       commitVisualStyles,
       handleClearBreakpointOverride,
+      selectedElement,
       selectedElement?.selector,
       selectedElement?.sourceId,
       selectedCanvasSelectorCandidates,
@@ -13559,6 +14323,83 @@ function DesignEditor() {
     [canEditDesign, selectedElement, handleStyleChange],
   );
 
+  // BUG-DOUBLE-TOGGLE-RACE: commitVisualStyles commits Cmd+U/Cmd+Shift+X
+  // through the SHORTHAND "textDecoration" property, but its synchronous
+  // optimistic patch to selectedElement.computedStyles only merges the exact
+  // key(s) it was given — it never decomposes "textDecoration" into the
+  // LONGHAND "textDecorationLine" the toggle READS to decide its next value.
+  // `textDecorationLine` only catches up once the bridge's async
+  // getComputedStyle round trip lands. A second Cmd+U within that window
+  // therefore recomputes nextTextDecorationLineValue from the STALE
+  // pre-toggle value, lands on the SAME target the first press already
+  // committed, and the style-commit pipeline dedupes the identical value as
+  // a no-op — consecutive toggles silently stop alternating.
+  //
+  // Fix: track our own optimistic textDecorationLine value per selected
+  // element, updated synchronously the instant we commit, and prefer it over
+  // the (possibly still-stale) computedStyles reading for the SAME element.
+  // Shared between underline and strikethrough since both toggle tokens
+  // within the same textDecorationLine value — a separate ref per hotkey
+  // would let one clobber the other's still-in-flight token.
+  const optimisticTextDecorationLineRef =
+    useRef<OptimisticTextDecorationLineEntry | null>(null);
+  const readOptimisticTextDecorationLine = useCallback(() => {
+    if (!selectedElement) return undefined;
+    return resolveOptimisticTextDecorationLine(
+      optimisticTextDecorationLineRef.current,
+      selectedElement.sourceId ?? selectedElement.selector,
+      selectedElement.computedStyles.textDecorationLine,
+    );
+  }, [selectedElement]);
+
+  // Typography hotkeys — Figma's Cmd+U (toggle underline) and Cmd+Shift+X
+  // (toggle strikethrough). Mirror handleOpacityHotkey's guard/commit shape
+  // and toggleTextDecorationLine's read/write split in
+  // edit-panel/typography-properties.tsx: reads the clean computed longhand
+  // `textDecorationLine`, commits through the shorthand "textDecoration"
+  // property name (see nextTextDecorationLineValue's doc comment).
+  const handleToggleUnderlineHotkey = useCallback(() => {
+    if (!canEditDesign || !selectedElement) return;
+    const nextValue = nextTextDecorationLineValue(
+      readOptimisticTextDecorationLine(),
+      "underline",
+    );
+    const elementKey = selectedElement.sourceId ?? selectedElement.selector;
+    if (elementKey) {
+      optimisticTextDecorationLineRef.current = {
+        key: elementKey,
+        value: nextValue,
+      };
+    }
+    handleStyleChange("textDecoration", nextValue);
+  }, [
+    canEditDesign,
+    selectedElement,
+    handleStyleChange,
+    readOptimisticTextDecorationLine,
+  ]);
+
+  const handleToggleStrikethroughHotkey = useCallback(() => {
+    if (!canEditDesign || !selectedElement) return;
+    const nextValue = nextTextDecorationLineValue(
+      readOptimisticTextDecorationLine(),
+      "line-through",
+    );
+    const elementKey = selectedElement.sourceId ?? selectedElement.selector;
+    if (elementKey) {
+      optimisticTextDecorationLineRef.current = {
+        key: elementKey,
+        value: nextValue,
+      };
+    }
+    handleStyleChange("textDecoration", nextValue);
+  }, [
+    canEditDesign,
+    selectedElement,
+    handleStyleChange,
+    readOptimisticTextDecorationLine,
+  ]);
+
   const handleStylesChange = useCallback(
     (styles: Record<string, string>, meta?: StyleChangeMeta) => {
       // Interaction-states phase 2 — see handleStyleChange's matching branch
@@ -13655,7 +14496,11 @@ function DesignEditor() {
         )
           return;
       }
-      if (commitStylesToSelectedLayers(Object.fromEntries(entries))) return;
+      if (
+        selectedElement &&
+        commitStylesToSelectedLayers(Object.fromEntries(entries))
+      )
+        return;
       commitVisualStyles(selector, Object.fromEntries(entries));
     },
     [
@@ -13664,6 +14509,7 @@ function DesignEditor() {
       commitStylesToSelectedLayers,
       commitVisualStyles,
       handleClearBreakpointOverride,
+      selectedElement,
       selectedCanvasSelectorCandidates,
       selectedElement?.selector,
       selectedElement?.sourceId,
@@ -13747,8 +14593,10 @@ function DesignEditor() {
       details?: {
         sourceId?: string;
         anchorSourceId?: string;
+        anchorElementInfo?: ElementInfo;
         requestId?: string;
         dropMode?: "flow-insert" | "absolute-container";
+        forceFlowPositionOverride?: boolean;
         sourceRect?: { x: number; y: number; width: number; height: number };
         anchorRect?: { x: number; y: number; width: number; height: number };
       },
@@ -13846,20 +14694,27 @@ function DesignEditor() {
           rawAbsoluteContainerOffset.y !== absoluteContainerOffset.y),
       );
       const nextContent =
-        isAbsoluteCodeLayerNode(targetNode) && movedNodeAttrId
-          ? details?.dropMode === "absolute-container"
-            ? absoluteContainerOffset
-              ? setAbsolutePositioningForNodeInHtml(
-                  patch.content,
-                  movedNodeAttrId,
-                  absoluteContainerOffset,
-                )
-              : patch.content
-            : removeAbsolutePositioningFromNodeInHtml(
+        movedNodeAttrId && details?.dropMode === "absolute-container"
+          ? absoluteContainerOffset
+            ? setAbsolutePositioningForNodeInHtml(
                 patch.content,
                 movedNodeAttrId,
+                absoluteContainerOffset,
               )
-          : patch.content;
+            : patch.content
+          : movedNodeAttrId &&
+              details?.dropMode === "flow-insert" &&
+              details.forceFlowPositionOverride
+            ? setFlowPositioningOverrideForNodeInHtml(
+                patch.content,
+                movedNodeAttrId,
+              )
+            : isAbsoluteCodeLayerNode(targetNode) && movedNodeAttrId
+              ? removeAbsolutePositioningFromNodeInHtml(
+                  patch.content,
+                  movedNodeAttrId,
+                )
+              : patch.content;
       const nextProjection = buildCodeLayerProjection(nextContent);
       const movedNode =
         (movedNodeAttrId
@@ -14210,8 +15065,10 @@ function DesignEditor() {
       details?: {
         sourceId?: string;
         anchorSourceId?: string;
+        anchorElementInfo?: ElementInfo;
         requestId?: string;
         dropMode?: "flow-insert" | "absolute-container";
+        forceFlowPositionOverride?: boolean;
         sourceRect?: { x: number; y: number; width: number; height: number };
         anchorRect?: { x: number; y: number; width: number; height: number };
       },
@@ -14314,20 +15171,27 @@ function DesignEditor() {
           rawAbsoluteContainerOffset.y !== absoluteContainerOffset.y),
       );
       const nextContent =
-        isAbsoluteCodeLayerNode(targetNode) && movedNodeAttrId
-          ? details?.dropMode === "absolute-container"
-            ? absoluteContainerOffset
-              ? setAbsolutePositioningForNodeInHtml(
-                  patch.content,
-                  movedNodeAttrId,
-                  absoluteContainerOffset,
-                )
-              : patch.content
-            : removeAbsolutePositioningFromNodeInHtml(
+        movedNodeAttrId && details?.dropMode === "absolute-container"
+          ? absoluteContainerOffset
+            ? setAbsolutePositioningForNodeInHtml(
                 patch.content,
                 movedNodeAttrId,
+                absoluteContainerOffset,
               )
-          : patch.content;
+            : patch.content
+          : movedNodeAttrId &&
+              details?.dropMode === "flow-insert" &&
+              details.forceFlowPositionOverride
+            ? setFlowPositioningOverrideForNodeInHtml(
+                patch.content,
+                movedNodeAttrId,
+              )
+            : isAbsoluteCodeLayerNode(targetNode) && movedNodeAttrId
+              ? removeAbsolutePositioningFromNodeInHtml(
+                  patch.content,
+                  movedNodeAttrId,
+                )
+              : patch.content;
       const nextProjection = buildCodeLayerProjection(nextContent);
       applyFileContentUpdate(
         screenId,
@@ -15130,20 +15994,35 @@ function DesignEditor() {
         return;
       }
       try {
-        const result = (await callAction("import-design-source", {
+        const figmaPasteCall = resolveFigmaPasteImportCall(content);
+        const result = (await callAction(figmaPasteCall.action, {
           designId: id,
-          sourceType: "figma-paste-html",
-          content,
-          originalName: "figma-paste.html",
+          ...figmaPasteCall.payload,
         })) as ImportResult;
         if (result?.error) throw new Error(result.error);
         await Promise.all([
           queryClient.invalidateQueries({ queryKey: ["action", "get-design"] }),
           queryClient.invalidateQueries({ queryKey: ["action"] }),
         ]);
+        const figmaStrategyLabel =
+          result?.strategy === "restNodes"
+            ? t("designEditor.import.figmaPasteRestLabel")
+            : result?.strategy === "htmlFallback"
+              ? t("designEditor.import.figmaPasteHtmlLabel")
+              : undefined;
         toast.success(
           importResultSummary(result, t("designEditor.import.figmaSuccess")),
+          figmaStrategyLabel ? { description: figmaStrategyLabel } : undefined,
         );
+        if (result?.figmaApiKeyMissing) {
+          toast.info(t("designEditor.import.figmaPasteApiKeyHint"));
+        } else if (
+          result?.strategy === "htmlFallback" &&
+          (result?.matchStatus === "ambiguous" ||
+            result?.matchStatus === "none")
+        ) {
+          toast.info(t("designEditor.import.figmaPasteMatchGuidance"));
+        }
         if (result?.warnings?.length) {
           toast.warning(t("designEditor.import.warningsToast"), {
             description: result.warnings[0],
@@ -15287,8 +16166,6 @@ function DesignEditor() {
       const frames = getAllScreenFrameEntries({
         overviewScreens,
         canvasFrameGeometryById,
-        boardFrameGeometry,
-        boardFileId,
       });
       const anchorCanvasPoint = (() => {
         if (overviewSelectedScreenIds.length === 1) {
@@ -15362,7 +16239,6 @@ function DesignEditor() {
       applyFileContentUpdate,
       applyLocalContentUpdate,
       boardFileId,
-      boardFrameGeometry,
       canEditDesign,
       canvasFrameGeometryById,
       getFreshActiveContent,
@@ -15452,8 +16328,6 @@ function DesignEditor() {
         const frame = getAllScreenFrameEntries({
           overviewScreens,
           canvasFrameGeometryById,
-          boardFrameGeometry,
-          boardFileId,
         }).find((entry) => entry.id === target.frameId);
         if (frame) {
           insertDroppedImageFiles(files, target.frameId, {
@@ -15467,7 +16341,6 @@ function DesignEditor() {
     },
     [
       boardFileId,
-      boardFrameGeometry,
       canvasFrameGeometryById,
       insertDroppedImageFiles,
       overviewScreens,
@@ -15956,7 +16829,8 @@ function DesignEditor() {
         // instead of the optimistic refreshPreview:false structural-delete
         // path.
         applyFileContentUpdate(file.id, content, {
-          refreshPreview: useBreakpointScopedDelete,
+          refreshPreview: false,
+          forcePreviewFullDocument: useBreakpointScopedDelete,
         });
       }
       if (!didDelete) return;
@@ -16012,7 +16886,10 @@ function DesignEditor() {
         : null;
       if (patch && patch.result.status === "applied") {
         deleteRuntimeElement(selectedElement.selector);
-        applyLocalContentUpdate(patch.content, { refreshPreview: true });
+        applyLocalContentUpdate(patch.content, {
+          refreshPreview: false,
+          forcePreviewFullDocument: true,
+        });
         setSelectedElement(null);
         setSelectedLayerIdsState([]);
       }
@@ -16067,9 +16944,255 @@ function DesignEditor() {
     selectedElement,
   ]);
 
+  const sendRuntimeLayerSemanticHandoff = useCallback(
+    (
+      operation: "group" | "ungroup" | "auto-layout",
+      layerIds: readonly string[],
+      options: {
+        desiredChange?: string;
+        description?: string;
+        commandContext?: string;
+      } = {},
+    ): boolean => {
+      const owners = layerIds
+        .map((layerId) => codeLayerOwnerByNodeIdRef.current.get(layerId))
+        .filter(
+          (
+            owner,
+          ): owner is NonNullable<
+            ReturnType<typeof codeLayerOwnerByNodeIdRef.current.get>
+          > => Boolean(owner?.runtimeOnly),
+        );
+      if (owners.length !== layerIds.length || owners.length === 0)
+        return false;
+      const screenId = owners[0]!.fileId;
+      if (owners.some((owner) => owner.fileId !== screenId)) return false;
+      const connectionId = overviewScreens.find(
+        (screen) => screen.id === screenId,
+      )?.connectionId;
+      const rootPath = connectionId
+        ? localhostConnectionRootPathByIdRef.current.get(connectionId)
+        : undefined;
+      const sourceAnchors = owners.map((owner, index) => {
+        const info = elementInfoFromCodeLayerNode(owner.node);
+        return reactSourceAnchorForPendingEdit({
+          info,
+          id: `subject-${index + 1}`,
+          rootPath,
+          runtimeMultiplicity: runtimeMultiplicityForElementProvenance(
+            runtimeLayerSnapshotsById,
+            info,
+          ),
+        });
+      });
+      if (sourceAnchors.some((anchor) => !anchor)) {
+        toast.error(t("designEditor.toasts.reactSourceAnchorsLoading"));
+        return true;
+      }
+      const subjectAnchorIds = sourceAnchors.map(
+        (_anchor, index) => `subject-${index + 1}`,
+      );
+      const handoff = buildReactSemanticHandoff({
+        operation,
+        desiredChange:
+          options.desiredChange ??
+          (operation === "group"
+            ? "Wrap the selected runtime React elements in one new group container while preserving their visual order and layout."
+            : operation === "ungroup"
+              ? "Remove the selected runtime React container wrapper and preserve its children in the same visual position and order."
+              : owners.length > 1
+                ? "Wrap the selected runtime React elements in an inferred auto-layout container while preserving their visual order."
+                : "Convert the selected runtime React container to inferred auto layout without changing unrelated behavior."),
+        sourceAnchors: sourceAnchors.filter(
+          (anchor): anchor is NonNullable<typeof anchor> => Boolean(anchor),
+        ),
+        runtimeRelationship: {
+          kind:
+            operation === "group"
+              ? "wrap"
+              : operation === "ungroup"
+                ? "unwrap"
+                : owners.length > 1
+                  ? "wrap"
+                  : "style",
+          subjectAnchorIds,
+          screenId,
+          description:
+            options.description ??
+            `${operation} ${owners.length} selected runtime React layer${owners.length === 1 ? "" : "s"}`,
+        },
+        versionHashes: [],
+      });
+      if (!handoff.ok) {
+        toast.error(handoff.rejection.reason);
+        return true;
+      }
+      sendToDesignAgentChat({
+        message: t("designEditor.pendingVisualStyles.agentMessage"),
+        context: [
+          options.commandContext ??
+            "Apply this runtime Layers-panel command to the connected React source.",
+          "The compiler metadata is for exact source anchoring and validation only; do not use a generic AST structural transform.",
+          "Read every target file, obtain human write consent, write with expectedVersionHash and requireExpectedVersionHash: true, then verify the resulting HMR/runtime relationship.",
+          JSON.stringify(handoff.handoff, null, 2),
+        ].join("\n\n"),
+        submit: true,
+        openSidebar: true,
+      });
+      setActiveLeftPanel("agent");
+      return true;
+    },
+    [overviewScreens, runtimeLayerSnapshotsById, t],
+  );
+
+  const sendRuntimeLayerMoveSemanticHandoff = useCallback(
+    (
+      subjectLayerId: string,
+      targetLayerId: string,
+      placement: "before" | "after" | "inside",
+    ): boolean => {
+      const subjectOwner =
+        codeLayerOwnerByNodeIdRef.current.get(subjectLayerId);
+      const targetOwner = codeLayerOwnerByNodeIdRef.current.get(targetLayerId);
+      if (!subjectOwner || !targetOwner) return false;
+
+      const sourceAnchorForOwner = (
+        owner: typeof subjectOwner,
+        anchorId: "subject" | "target",
+      ) => {
+        const screen = overviewScreens.find(
+          (candidate) => candidate.id === owner.fileId,
+        );
+        const rootPath = screen?.connectionId
+          ? localhostConnectionRootPathByIdRef.current.get(screen.connectionId)
+          : undefined;
+        const info = elementInfoFromCodeLayerNode(owner.node);
+        return reactSourceAnchorForPendingEdit({
+          info,
+          id: anchorId,
+          rootPath,
+          runtimeMultiplicity: runtimeMultiplicityForElementProvenance(
+            runtimeLayerSnapshotsById,
+            info,
+          ),
+          reason:
+            anchorId === "subject"
+              ? `Runtime Layers-panel move subject in screen ${owner.fileId}.`
+              : `Runtime Layers-panel move target in screen ${owner.fileId}.`,
+        });
+      };
+
+      const subjectAnchor = sourceAnchorForOwner(subjectOwner, "subject");
+      const targetAnchor = sourceAnchorForOwner(targetOwner, "target");
+      if (!subjectAnchor || !targetAnchor) {
+        // Mixed runtime/source moves are only safe when BOTH endpoints carry
+        // exact compiler provenance. Never fall back to selectors or a generic
+        // source/AST move for the missing side.
+        toast.error(t("designEditor.toasts.reactSourceAnchorsLoading"));
+        return true;
+      }
+
+      const handoff = buildRuntimeReactStructureMoveHandoff({
+        subjectAnchor,
+        targetAnchor,
+        placement,
+        sourceScreenId: subjectOwner.fileId,
+        targetScreenId: targetOwner.fileId,
+      });
+      if (!handoff.ok) {
+        toast.error(handoff.rejection.reason);
+        return true;
+      }
+
+      sendToDesignAgentChat({
+        message: t("designEditor.pendingVisualStyles.agentMessage"),
+        context: [
+          "Apply this runtime Layers-panel move/reparent to the connected React source.",
+          `The exact subject belongs to screen ${subjectOwner.fileId}; the exact target belongs to screen ${targetOwner.fileId}.`,
+          "Compiler provenance is for exact anchoring and validation only. Never apply a generic AST reparent or structure transform.",
+          "Read every affected file first, obtain human write consent, write with each read's expectedVersionHash and requireExpectedVersionHash: true, re-read/re-plan on conflict, and keep any optimistic preview pending only until HMR confirms the intended runtime relationship.",
+          JSON.stringify(handoff.handoff, null, 2),
+        ].join("\n\n"),
+        submit: true,
+        openSidebar: true,
+      });
+      setActiveLeftPanel("agent");
+      return true;
+    },
+    [overviewScreens, runtimeLayerSnapshotsById, t],
+  );
+
+  const sendRuntimeLayerStateSemanticHandoff = useCallback(
+    (
+      layerId: string,
+      state: "locked" | "hidden",
+      enabled: boolean,
+    ): boolean => {
+      const owner = codeLayerOwnerByNodeIdRef.current.get(layerId);
+      if (!owner?.runtimeOnly) return false;
+
+      const screen = overviewScreens.find(
+        (candidate) => candidate.id === owner.fileId,
+      );
+      const rootPath = screen?.connectionId
+        ? localhostConnectionRootPathByIdRef.current.get(screen.connectionId)
+        : undefined;
+      const info = elementInfoFromCodeLayerNode(owner.node);
+      const subjectAnchor = reactSourceAnchorForPendingEdit({
+        info,
+        id: "subject",
+        rootPath,
+        runtimeMultiplicity: runtimeMultiplicityForElementProvenance(
+          runtimeLayerSnapshotsById,
+          info,
+        ),
+        reason: `Runtime Layers-panel ${state} state for layer ${layerId} in screen ${owner.fileId}.`,
+      });
+      if (!subjectAnchor) {
+        toast.error(t("designEditor.toasts.reactSourceAnchorsLoading"));
+        return false;
+      }
+
+      const handoff = buildRuntimeReactLayerStateHandoff({
+        subjectAnchor,
+        screenId: owner.fileId,
+        state,
+        enabled,
+      });
+      if (!handoff.ok) {
+        toast.error(handoff.rejection.reason);
+        return false;
+      }
+
+      const attributeName = `data-agent-native-${state}`;
+      sendToDesignAgentChat({
+        message: t("designEditor.pendingVisualStyles.agentMessage"),
+        context: [
+          `Apply this runtime Layers-panel ${state} change to the connected React source.`,
+          `Use the exact compiler anchor to ${enabled ? `set ${attributeName}=\"true\" on` : `remove ${attributeName} from`} the existing JSX host element. The runtime Layers snapshot recognizes this durable source metadata; do not replace it with CSS, a transient DOM mutation, or a wrapper.`,
+          "Compiler provenance is for exact anchoring and validation only. Never apply a generic AST transform.",
+          "Read the affected file first, obtain human write consent, write with that read's expectedVersionHash and requireExpectedVersionHash: true, re-read/re-plan on conflict, and keep the optimistic layer-state preview only until HMR confirms the source metadata.",
+          JSON.stringify(handoff.handoff, null, 2),
+        ].join("\n\n"),
+        submit: true,
+        openSidebar: true,
+      });
+      setActiveLeftPanel("agent");
+      return true;
+    },
+    [overviewScreens, runtimeLayerSnapshotsById, t],
+  );
+
   // Wrap the current multi-layer selection into a new group container.
   const handleGroupSelection = useCallback(() => {
     if (!canEditDesign || !activeFile) return;
+    const selectedRuntimeLayerIds = selectedLayerIdsState.filter(
+      (layerId) => codeLayerOwnerByNodeIdRef.current.get(layerId)?.runtimeOnly,
+    );
+    if (selectedRuntimeLayerIds.length > 0) {
+      sendRuntimeLayerSemanticHandoff("group", selectedRuntimeLayerIds);
+      return;
+    }
     const baseContent = getFreshActiveContent();
     // Collect the DOM-node layer ids that belong to the active screen.
     // Build a set of ids present in the active content so stale ids from
@@ -16122,6 +17245,7 @@ function DesignEditor() {
     files,
     getFreshActiveContent,
     selectedLayerIdsState,
+    sendRuntimeLayerSemanticHandoff,
     t,
   ]);
 
@@ -16646,18 +17770,101 @@ function DesignEditor() {
   //      container via the same wrapNodes substrate handleGroupSelection/
   //      handleFrameSelection use, passing autoLayout: true so the wrapper is
   //      created with display:flex/gap in the same call.
-  //  (c) selection of overview screens: no-op with a subtle toast (screens
-  //      aren't DOM containers — there's nothing to convert).
+  //  (c) exactly one selected overview SCREEN: convert the authored body (or
+  //      one fragment root) for inline HTML/Alpine. Local React screens route
+  //      compiler-provenanced roots through the semantic coding-agent handoff;
+  //      multiple screens remain unsupported because screens cannot safely be
+  //      nested without a first-class screen-container model.
   const handleAddAutoLayout = useCallback(() => {
     if (!canEditDesign) return;
 
     if (viewModeRef.current === "overview") {
       if (overviewSelectedScreenIds.length === 0) return;
+      if (overviewSelectedScreenIds.length !== 1 || selectedElement !== null) {
+        toast(t("designEditor.toasts.autoLayoutScreensUnsupported"));
+        return;
+      }
+      const screenId = overviewSelectedScreenIds[0]!;
+      if (
+        effectiveCodeLayerStateRef.current.lockedIds.has(screenId) ||
+        effectiveCodeLayerStateRef.current.hiddenIds.has(screenId)
+      ) {
+        return;
+      }
+      const screen = overviewScreens.find(
+        (candidate) => candidate.id === screenId,
+      );
+      if (!screen) return;
+      const screenSourceType =
+        normalizeDesignSourceType(screen.sourceType) ?? designSourceType;
+
+      if (screenSourceType === "localhost") {
+        const snapshot = runtimeLayerSnapshotsById[screenId];
+        if (!snapshot) {
+          toast.error(t("designEditor.toasts.reactSourceAnchorsLoading"));
+          return;
+        }
+        const runtimeSubjectIds = getRuntimeScreenAutoLayoutSubjectIds(
+          buildCodeLayerProjection(snapshot.html),
+        );
+        if (runtimeSubjectIds.length === 0) {
+          toast.error(t("designEditor.toasts.reactSourceAnchorsLoading"));
+          return;
+        }
+        sendRuntimeLayerSemanticHandoff("auto-layout", runtimeSubjectIds, {
+          desiredChange:
+            runtimeSubjectIds.length > 1
+              ? "Wrap the selected screen's top-level React roots in one inferred auto-layout container while preserving their visual order and all unrelated behavior."
+              : "Enable inferred auto layout on the selected screen's editable React root container while preserving its children and all unrelated behavior.",
+          description: `enable auto layout on the editable root of screen ${screenId}`,
+          commandContext:
+            "Apply this selected-screen auto-layout command to the connected React source.",
+        });
+        return;
+      }
+
+      if (screenSourceType === "inline") {
+        const baseContent = getScreenContent(screenId);
+        if (!baseContent) return;
+        const result = enableInlineScreenAutoLayout({
+          content: baseContent,
+          width: screen.width,
+          height: screen.height,
+        });
+        if (result.status === "unsupported") {
+          toast(t("designEditor.toasts.autoLayoutScreensUnsupported"));
+          return;
+        }
+        if (result.status === "failed") {
+          toast.error(
+            codeLayerPatchMessage(
+              result.message,
+              t("designEditor.toasts.layerMoveFailed"),
+            ),
+            { duration: 4000 },
+          );
+          return;
+        }
+        if (result.status === "applied") {
+          applyFileContentUpdate(screenId, result.content, {
+            forcePreviewFullDocument: true,
+          });
+        }
+        return;
+      }
+
       toast(t("designEditor.toasts.autoLayoutScreensUnsupported"));
       return;
     }
 
     if (!activeFile) return;
+    const selectedRuntimeLayerIds = selectedLayerIdsState.filter(
+      (layerId) => codeLayerOwnerByNodeIdRef.current.get(layerId)?.runtimeOnly,
+    );
+    if (selectedRuntimeLayerIds.length > 0) {
+      sendRuntimeLayerSemanticHandoff("auto-layout", selectedRuntimeLayerIds);
+      return;
+    }
     const baseContent = getFreshActiveContent();
     const nodeIds = getActiveFileSelectedNodeIds(baseContent);
     if (nodeIds.length === 0) return;
@@ -16779,12 +17986,20 @@ function DesignEditor() {
     applyLocalContentUpdate(nextContent, { skipPreview: true });
   }, [
     activeFile,
+    applyFileContentUpdate,
     applyLocalContentUpdate,
     canEditDesign,
+    designSourceType,
     getActiveFileSelectedNodeIds,
     getFreshActiveContent,
+    getScreenContent,
+    overviewScreens,
     overviewSelectedScreenIds,
     rectFromCodeLayerNode,
+    runtimeLayerSnapshotsById,
+    selectedElement,
+    selectedLayerIdsState,
+    sendRuntimeLayerSemanticHandoff,
     t,
   ]);
 
@@ -16795,16 +18010,9 @@ function DesignEditor() {
     setUiHidden((current) => !current);
   }, []);
 
-  // Item 6 (residual): Figma's Shift+C — Show/Hide comments. No existing
-  // comment-pin visibility state was found anywhere in this app (grepped
-  // DesignCanvas.tsx/MultiScreenCanvas.tsx for commentPins/annotations/
-  // showComments/hideComments — none exist), and DesignCanvas has no prop to
-  // suppress pin rendering, so this can only toggle a local flag + surface it
-  // through the menu's isCommentsHidden/onToggleComments props for now. It
-  // does NOT actually hide comment pins on the canvas yet. Whoever owns
-  // DesignCanvas.tsx/CommentPin rendering should add a
-  // `commentPinsHidden?: boolean` prop (mirroring handToolActive/
-  // spacePanActive's pattern) and this handler should pass it through.
+  // Figma's Shift+C — Show/Hide comments. The state is passed through every
+  // mounted DesignCanvas so both focused and overview comment pins disappear
+  // without unmounting/recreating their preview iframe.
   const [commentsHidden, setCommentsHidden] = useState(false);
   const handleToggleComments = useCallback(() => {
     setCommentsHidden((current) => !current);
@@ -16819,6 +18027,13 @@ function DesignEditor() {
   // can immediately keep working with them.
   const handleUngroupSelection = useCallback(() => {
     if (!canEditDesign || !activeFile) return;
+    const selectedRuntimeLayerIds = selectedLayerIdsState.filter(
+      (layerId) => codeLayerOwnerByNodeIdRef.current.get(layerId)?.runtimeOnly,
+    );
+    if (selectedRuntimeLayerIds.length > 0) {
+      sendRuntimeLayerSemanticHandoff("ungroup", selectedRuntimeLayerIds);
+      return;
+    }
     const initialContent = getFreshActiveContent();
     // Filter to active-file nodes only (mirrors handleGroupSelection fix).
     // A stale id from another file must not be passed to unwrap or it will
@@ -16913,6 +18128,7 @@ function DesignEditor() {
     files,
     getFreshActiveContent,
     selectedLayerIdsState,
+    sendRuntimeLayerSemanticHandoff,
     t,
   ]);
 
@@ -16920,9 +18136,13 @@ function DesignEditor() {
    * Handle a primitive being drag-dropped onto another primitive in the
    * MultiScreenCanvas overview (CONTRACT: onPrimitiveReparent prop).
    *
-   * Same-screen: applies a moveNode intent then rebases the moved node's
-   * absolute coordinates relative to the target rectangle. Cross-screen uses
-   * moveNodeBetweenDocuments and persists both files.
+   * Same-screen: applies a moveNode intent then, for an "inside" (absolute
+   * container) drop, rebases the moved node's absolute coordinates relative
+   * to the target rectangle. For a "before"/"after" auto-layout flow-insert,
+   * skips the absolute rebase and strips positioning instead so the node
+   * becomes a real flow child at the resolved sibling index — mirroring
+   * handleCrossScreenElementDrop's targetDropMode branch below. Cross-screen
+   * uses moveNodeBetweenDocuments and persists both files.
    */
   const handleOverviewPrimitiveReparent = useCallback(
     ({
@@ -16930,12 +18150,13 @@ function DesignEditor() {
       sourceScreenId,
       targetNodeId,
       targetScreenId,
+      placement = "inside",
     }: {
       sourceNodeId: string;
       sourceScreenId: string;
       targetNodeId: string;
       targetScreenId: string;
-      placement: "inside";
+      placement?: "before" | "after" | "inside";
     }) => {
       if (!canEditDesign) return;
 
@@ -16944,12 +18165,18 @@ function DesignEditor() {
         const baseContent = getScreenContent(sourceScreenId);
         if (!baseContent) return;
 
-        // 1. Move the node inside the target container.
+        // 1. Move the node relative to the target anchor. For "inside" the
+        // anchor is the container itself (append); for "before"/"after" the
+        // anchor is a sibling child already inside an auto-layout container
+        // (flow-insert at that index) — applyMoveNodeEdit's
+        // prepareMovedFragmentForParent already strips absolute positioning
+        // from the moved fragment's root when the destination parent is a
+        // flow container, regardless of which placement resolved it there.
         const movePatch = applyVisualEdit(baseContent, {
           kind: "moveNode",
           target: { nodeId: sourceNodeId },
           anchor: { nodeId: targetNodeId },
-          placement: "inside",
+          placement,
         });
         if (movePatch.result.status !== "applied") {
           toast.error(
@@ -16968,6 +18195,33 @@ function DesignEditor() {
               n.dataAttributes["data-agent-native-node-id"] === sourceNodeId ||
               n.id === sourceNodeId,
           )?.dataAttributes["data-agent-native-node-id"] ?? sourceNodeId;
+
+        if (placement !== "inside") {
+          // Auto-layout flow-insert: belt-and-suspenders alongside
+          // prepareMovedFragmentForParent above — make sure the moved node
+          // itself carries no leftover position/left/top so it renders as a
+          // pure flow child at its new index instead of an absolute layer
+          // sitting on top of its new siblings.
+          const flowContent = removeAbsolutePositioningFromNodeInHtml(
+            movePatch.content,
+            movedNodeAttrId,
+          );
+          applyFileContentUpdate(sourceScreenId, flowContent, {
+            skipPreview: true,
+          });
+          const nextProjection = buildCodeLayerProjection(flowContent);
+          const movedNodeAfter = nextProjection.nodes.find(
+            (n) =>
+              n.dataAttributes["data-agent-native-node-id"] === sourceNodeId ||
+              n.id === sourceNodeId,
+          );
+          if (movedNodeAfter) {
+            setSelectedLayerIdsState([movedNodeAfter.id]);
+            setSelectedElement(elementInfoFromCodeLayerNode(movedNodeAfter));
+          }
+          return;
+        }
+
         const sourcePosition = getAbsolutePositioningForNodeInHtml(
           baseContent,
           sourceNodeId,
@@ -17048,7 +18302,7 @@ function DesignEditor() {
       const result = moveNodeBetweenDocuments(sourceContent, destContent, {
         nodeId: nodeAttrId,
         anchorNodeId: anchorAttrId,
-        placement: "inside",
+        placement,
       });
       if (result.status !== "applied") {
         toast.error(
@@ -17071,26 +18325,39 @@ function DesignEditor() {
       }
 
       const destNodeAttrId = result.movedNodeId ?? nodeAttrId;
-      const sourcePosition = getAbsolutePositioningForNodeInHtml(
-        sourceContent,
-        nodeAttrId,
-      );
-      const targetPosition = getAbsolutePositioningForNodeInHtml(
-        destContent,
-        anchorAttrId,
-      );
-      // Same parent-relative rebase + board-poison stripping as the
-      // same-screen branch above (see computeReparentedChildPosition), plus
-      // the same normalization safety net when the DESTINATION is the board.
-      const rebasedDestContent =
-        sourcePosition && targetPosition
-          ? setAbsolutePositioningForNodeInHtml(
+      // "inside" rebases to a parent-relative absolute position (matches the
+      // same-screen branch above and historic behavior for dropping onto a
+      // plain absolute container). "before"/"after" is an auto-layout
+      // flow-insert — moveNodeBetweenDocuments's prepareMovedFragmentForParent
+      // already stripped absolute positioning from the moved fragment's
+      // root, so just belt-and-suspenders clear it again by node id rather
+      // than reintroducing position:absolute via the rebase below.
+      const nextDestContent = (() => {
+        const rebasedDestContent = (() => {
+          if (placement !== "inside") {
+            return removeAbsolutePositioningFromNodeInHtml(
               result.destHtml,
               destNodeAttrId,
-              computeReparentedChildPosition(sourcePosition, targetPosition),
-            )
-          : result.destHtml;
-      const nextDestContent = (() => {
+            );
+          }
+          const sourcePosition = getAbsolutePositioningForNodeInHtml(
+            sourceContent,
+            nodeAttrId,
+          );
+          const targetPosition = getAbsolutePositioningForNodeInHtml(
+            destContent,
+            anchorAttrId,
+          );
+          // Same parent-relative rebase + board-poison stripping as the
+          // same-screen branch above (see computeReparentedChildPosition).
+          return sourcePosition && targetPosition
+            ? setAbsolutePositioningForNodeInHtml(
+                result.destHtml,
+                destNodeAttrId,
+                computeReparentedChildPosition(sourcePosition, targetPosition),
+              )
+            : result.destHtml;
+        })();
         if (!boardFileId || targetScreenId !== boardFileId) {
           return rebasedDestContent;
         }
@@ -17117,11 +18384,13 @@ function DesignEditor() {
 
       applyFileContentUpdate(sourceScreenId, result.sourceHtml, {
         recordHistory: false,
-        refreshPreview: true,
+        refreshPreview: false,
+        forcePreviewFullDocument: true,
       });
       applyFileContentUpdate(targetScreenId, nextDestContent, {
         recordHistory: false,
-        refreshPreview: true,
+        refreshPreview: false,
+        forcePreviewFullDocument: true,
       });
 
       // Re-select the moved node in the destination.
@@ -17198,6 +18467,50 @@ function DesignEditor() {
       if (!canEditDesign) return;
       if (sourceScreenId === targetScreenId) return;
 
+      const findLayerOwner = (
+        screenId: string,
+        nodeId: string | undefined,
+        selector: string | undefined,
+      ) =>
+        Array.from(codeLayerOwnerByNodeIdRef.current.entries()).find(
+          ([candidateId, owner]) =>
+            owner.fileId === screenId &&
+            ((nodeId &&
+              (candidateId === nodeId ||
+                bridgeSourceIdForCodeLayerNode(owner.node) === nodeId)) ||
+              (selector && owner.node.selector === selector)),
+        );
+      const sourceOwnerEntry = findLayerOwner(
+        sourceScreenId,
+        sourceNodeId,
+        sourceSelector,
+      );
+      const targetOwnerEntry = findLayerOwner(
+        targetScreenId,
+        targetAnchorNodeId,
+        targetAnchorSelector,
+      );
+      if (
+        sourceOwnerEntry?.[1].runtimeOnly ||
+        targetOwnerEntry?.[1].runtimeOnly
+      ) {
+        if (!sourceOwnerEntry || !targetOwnerEntry) {
+          // A runtime/source cross-screen drop without an exact target (for
+          // example, dropping on the bare screen root) cannot satisfy the
+          // semantic handoff's two-anchor contract. Do not fall through to a
+          // selector guess or mutate stored wrapper HTML that does not own the
+          // runtime React node.
+          toast.error(t("designEditor.toasts.reactSourceAnchorsLoading"));
+          return;
+        }
+        sendRuntimeLayerMoveSemanticHandoff(
+          sourceOwnerEntry[0],
+          targetOwnerEntry[0],
+          targetAnchorPlacement ?? "inside",
+        );
+        return;
+      }
+
       const sourceContent = getScreenContent(sourceScreenId);
       const rawDestContent = getScreenContent(targetScreenId);
       if (!sourceContent || !rawDestContent) return;
@@ -17400,11 +18713,13 @@ function DesignEditor() {
 
       applyFileContentUpdate(sourceScreenId, result.sourceHtml, {
         recordHistory: false,
-        refreshPreview: true,
+        refreshPreview: false,
+        forcePreviewFullDocument: true,
       });
       applyFileContentUpdate(targetScreenId, nextDestContent, {
         recordHistory: false,
-        refreshPreview: true,
+        refreshPreview: false,
+        forcePreviewFullDocument: true,
       });
 
       // Switch active screen to the target and select the moved node; viewMode
@@ -17440,6 +18755,7 @@ function DesignEditor() {
       getScreenContent,
       id,
       recordContentHistoryEntry,
+      sendRuntimeLayerMoveSemanticHandoff,
       t,
     ],
   );
@@ -18150,6 +19466,40 @@ function DesignEditor() {
           : pendingNonStyleUndo.edit,
       ]);
       setPendingLiveNonStyleEdits(nextPending);
+      // Bug fix — undo reverted the DOM via requestPendingLiveNonStyleRevert
+      // above but never resynced the inspector panel's selectedElement, so
+      // the right panel kept showing pre-undo text until deselect/reselect.
+      // Mirrors recordPendingVisualStyleEdit's direct object-patch resync
+      // (~line 9514): a plain merge of the revert payload already on this
+      // undo entry, not a DOM re-query or content-string rebuild (those
+      // don't exist for pending live edits, which never touch
+      // ydoc/activeFile.content).
+      if (
+        pendingNonStyleUndo.kind === "text" &&
+        pendingNonStyleUndo.edit.screenId === activeFile?.id
+      ) {
+        const { sourceId: revertedSourceId, selector: revertedSelector } =
+          pendingNonStyleUndo.edit;
+        const { revertValue, revertHtml } = pendingNonStyleUndo;
+        setSelectedElement((prev) => {
+          if (!prev) return prev;
+          if (
+            !pendingEditTargetsSelectedElement({
+              editSourceId: revertedSourceId,
+              editSelector: revertedSelector,
+              selectedSourceId: prev.sourceId,
+              selectedSelector: prev.selector,
+            })
+          ) {
+            return prev;
+          }
+          return {
+            ...prev,
+            textContent: revertValue,
+            htmlContent: revertHtml ?? prev.htmlContent,
+          };
+        });
+      }
       syncUndoRedoState();
       return;
     }
@@ -18173,6 +19523,39 @@ function DesignEditor() {
         },
       ]);
       setPendingVisualStyleEdits(nextPending);
+      // Bug fix — same stale-inspector-panel issue as the pendingNonStyleUndo
+      // branch above, for style undo. Merge the reverted style values
+      // (already computed as pendingStyleUndo.revertStyles) into
+      // selectedElement.computedStyles, guarded to the currently-selected
+      // element so an undo on a different/background screen doesn't
+      // clobber the panel for whatever the user has selected right now.
+      if (pendingStyleUndo.edit.screenId === activeFile?.id) {
+        const {
+          sourceId: revertedStyleSourceId,
+          selector: revertedStyleSelector,
+        } = pendingStyleUndo.edit;
+        const revertedStyles = pendingStyleUndo.revertStyles;
+        setSelectedElement((prev) => {
+          if (!prev) return prev;
+          if (
+            !pendingEditTargetsSelectedElement({
+              editSourceId: revertedStyleSourceId,
+              editSelector: revertedStyleSelector,
+              selectedSourceId: prev.sourceId,
+              selectedSelector: prev.selector,
+            })
+          ) {
+            return prev;
+          }
+          return {
+            ...prev,
+            computedStyles: {
+              ...prev.computedStyles,
+              ...revertedStyles,
+            },
+          };
+        });
+      }
       syncUndoRedoState();
       return;
     }
@@ -18543,6 +19926,36 @@ function DesignEditor() {
         ],
       });
       setPendingLiveNonStyleEdits(nextPending);
+      // Bug fix — same stale-inspector-panel issue as handleUndo. Redo
+      // reapplies pendingTextRedo.edit.value/html via
+      // setPendingTextRevertRequest above, but never resynced
+      // selectedElement, so resync with the same values here.
+      if (pendingTextRedo.edit.screenId === activeFile?.id) {
+        const {
+          sourceId: redoneSourceId,
+          selector: redoneSelector,
+          value: redoneValue,
+          html: redoneHtml,
+        } = pendingTextRedo.edit;
+        setSelectedElement((prev) => {
+          if (!prev) return prev;
+          if (
+            !pendingEditTargetsSelectedElement({
+              editSourceId: redoneSourceId,
+              editSelector: redoneSelector,
+              selectedSourceId: prev.sourceId,
+              selectedSelector: prev.selector,
+            })
+          ) {
+            return prev;
+          }
+          return {
+            ...prev,
+            textContent: redoneValue,
+            htmlContent: redoneHtml ?? prev.htmlContent,
+          };
+        });
+      }
       syncUndoRedoState();
       return;
     }
@@ -18574,6 +19987,37 @@ function DesignEditor() {
         ],
       });
       setPendingVisualStyleEdits(nextPending);
+      // Bug fix — same stale-inspector-panel issue as handleUndo's style
+      // branch. Merge the redo's own style values (already applied to the
+      // DOM via setPendingVisualStyleRevertRequest above) into
+      // selectedElement.computedStyles.
+      if (pendingLiveRedo.edit.screenId === activeFile?.id) {
+        const {
+          sourceId: redoneStyleSourceId,
+          selector: redoneStyleSelector,
+          styles: redoneStyles,
+        } = pendingLiveRedo.edit;
+        setSelectedElement((prev) => {
+          if (!prev) return prev;
+          if (
+            !pendingEditTargetsSelectedElement({
+              editSourceId: redoneStyleSourceId,
+              editSelector: redoneStyleSelector,
+              selectedSourceId: prev.sourceId,
+              selectedSelector: prev.selector,
+            })
+          ) {
+            return prev;
+          }
+          return {
+            ...prev,
+            computedStyles: {
+              ...prev.computedStyles,
+              ...redoneStyles,
+            },
+          };
+        });
+      }
       syncUndoRedoState();
       return;
     }
@@ -18956,7 +20400,7 @@ function DesignEditor() {
     const frames = getAllScreenFrameEntries({
       overviewScreens,
       canvasFrameGeometryById,
-      boardFrameGeometry,
+      boardContentBounds,
       boardFileId,
     });
     const bounds = getFrameGroupBounds(frames);
@@ -18971,7 +20415,7 @@ function DesignEditor() {
     });
   }, [
     boardFileId,
-    boardFrameGeometry,
+    boardContentBounds,
     canvasFrameGeometryById,
     overviewScreens,
   ]);
@@ -18980,7 +20424,7 @@ function DesignEditor() {
     const allFrames = getAllScreenFrameEntries({
       overviewScreens,
       canvasFrameGeometryById,
-      boardFrameGeometry,
+      boardContentBounds,
       boardFileId,
     });
     const selectedIds = new Set(overviewSelectedScreenIds);
@@ -19007,7 +20451,7 @@ function DesignEditor() {
     });
   }, [
     boardFileId,
-    boardFrameGeometry,
+    boardContentBounds,
     canvasFrameGeometryById,
     overviewScreens,
     overviewSelectedScreenIds,
@@ -19214,7 +20658,10 @@ function DesignEditor() {
         clearPendingLiveEditState();
       }
 
-      if (activeFile && viewMode === "overview") {
+      // Interact operates inside one live screen. Annotate is different: its
+      // overlay is intentionally board-wide in overview so users can mark the
+      // canvas around/across screens without remounting their preview iframes.
+      if (next === "interact" && activeFile && viewMode === "overview") {
         viewModeRef.current = "single";
         setScreenZoom(FOCUSED_SCREEN_ZOOM);
         setViewMode("single");
@@ -19250,17 +20697,10 @@ function DesignEditor() {
   );
 
   useEffect(() => {
-    if (
-      embedded ||
-      mode !== "annotate" ||
-      !activeFile ||
-      viewMode === "overview"
-    ) {
-      return;
-    }
+    if (embedded || mode !== "annotate" || !activeFile) return;
     if (!canEditDesign) return;
     setDrawMode(true);
-  }, [activeFile?.id, canEditDesign, embedded, mode, viewMode]);
+  }, [activeFile?.id, canEditDesign, embedded, mode]);
 
   const handleViewModeToggle = useCallback(() => {
     if (viewModeRef.current === "overview") {
@@ -19364,8 +20804,51 @@ function DesignEditor() {
     runEditorViewTransition,
   ]);
 
+  const handleShowKeyboardShortcuts = useCallback(() => {
+    if (!keyboardShortcutsOpen) {
+      const activeElement = document.activeElement;
+      keyboardShortcutsReturnFocusRef.current =
+        activeElement instanceof HTMLElement ? activeElement : null;
+    }
+    setUiHidden(false);
+    setKeyboardShortcutsOpen(true);
+  }, [keyboardShortcutsOpen]);
+
+  const handleShowKeyboardShortcutsFromMenu = useCallback(() => {
+    keyboardShortcutsReturnFocusRef.current = projectMenuTriggerRef.current;
+    suppressProjectMenuReturnFocusRef.current = true;
+    setUiHidden(false);
+    setKeyboardShortcutsOpen(true);
+  }, []);
+
+  const handleCloseKeyboardShortcuts = useCallback(() => {
+    setKeyboardShortcutsOpen(false);
+    const returnFocusTarget = keyboardShortcutsReturnFocusRef.current;
+    keyboardShortcutsReturnFocusRef.current = null;
+    window.requestAnimationFrame(() => {
+      if (returnFocusTarget?.isConnected) {
+        returnFocusTarget.focus({ preventScroll: true });
+      }
+    });
+  }, []);
+
   const handleEscapeHotkey = useCallback(() => {
+    if (keyboardShortcutsOpen) {
+      handleCloseKeyboardShortcuts();
+      return;
+    }
     if (cancelActiveEditorDrag()) return;
+    // A delivery-confirmation wait freezes the complete annotation batch.
+    // Escape must not clear it while the submitted snapshot is in flight.
+    if (overviewAnnotationSending || focusedAnnotationSending) return;
+    // Escape is a deliberate annotate-mode exit, same as the overlay's X.
+    // Route it through the same per-surface clear semantics instead of merely
+    // hiding the overlay and leaving a stale batch to reappear later.
+    if (drawMode && mode === "annotate") {
+      if (viewMode === "overview") handleExitOverviewDrawMode();
+      else handleExitFocusedDrawMode();
+      return;
+    }
     // BP-DEEP item 5 — Framer-style click-to-target: Escape's first job when
     // a breakpoint is the active edit target is to return to Base, matching
     // "click the base frame / empty canvas" — mirrors the other early-return
@@ -19392,6 +20875,68 @@ function DesignEditor() {
       enterOverviewFromZoom();
       return;
     }
+    // Figma parity — pop the plain-canvas selection one level at a time
+    // (child layer -> parent layer -> containing screen/frame -> fully
+    // deselected) instead of deselecting everything on the first Escape.
+    // The decision itself is a pure, unit-tested function
+    // (resolveEscapePopSelectionAction in design-editor/selection-state.ts);
+    // this reuses the same codeLayerOwnerByNodeIdRef/parentId ancestor walk
+    // handleSelectParentLayer (Shift+Enter / "\\") already uses, inlined
+    // here (rather than calling selectCodeLayerNodesForHotkey directly)
+    // since that helper is declared later in this component and referencing
+    // it from this callback's deps would hit its temporal-dead-zone before
+    // this render's declarations run.
+    const escapeSelectedLayerId =
+      selectedLayerIdsState[selectedLayerIdsState.length - 1];
+    const escapeOwner = escapeSelectedLayerId
+      ? codeLayerOwnerByNodeIdRef.current.get(escapeSelectedLayerId)
+      : undefined;
+    // BUG-ESCAPE-SHELL: the flat codeLayerOwnerByNodeIdRef map (built from
+    // projection.nodes) still contains <html>/<body> entries with real
+    // parentId links even though the VISUAL layers tree collapses them away
+    // (shared/code-layer.ts's isCollapsibleDocumentShellNode). A bare
+    // Boolean(escapeOwner?.node.parentId) check treats a top-level layer's
+    // collapsed <body> ancestor as a selectable parent, so popping from the
+    // screen root would select <body> then <html> instead of stopping at the
+    // screen/frame level. hasSelectableCodeLayerParent excludes those shell
+    // nodes so the pop walk matches what the layers panel shows.
+    const escapeParentOwner = escapeOwner?.node.parentId
+      ? codeLayerOwnerByNodeIdRef.current.get(escapeOwner.node.parentId)
+      : undefined;
+    const popAction = resolveEscapePopSelectionAction({
+      hasSelectedLayer: Boolean(escapeOwner),
+      hasLayerParent: hasSelectableCodeLayerParent({
+        parentNode: escapeParentOwner?.node,
+      }),
+      viewMode,
+    });
+    if (popAction.kind === "pop-to-parent-layer" && escapeOwner) {
+      const parentOwner = escapeParentOwner;
+      if (parentOwner && parentOwner.fileId === escapeOwner.fileId) {
+        setActiveFileId(parentOwner.fileId);
+        setOverviewSelectedScreenIds([]);
+        setSelectedLayerIdsState([parentOwner.node.id]);
+        setSelectedElement(elementInfoFromCodeLayerNode(parentOwner.node));
+        setExpandedLayerIds((current) => {
+          const next = new Set(current);
+          next.add(parentOwner.fileId);
+          collectCodeLayerAncestors(
+            parentOwner.tree,
+            parentOwner.node.id,
+          ).forEach((ancestorId) => next.add(ancestorId));
+          return next.size === current.length ? current : Array.from(next);
+        });
+        return;
+      }
+      // Parent couldn't be resolved (e.g. cross-file) — fall through to a
+      // full deselect below rather than silently doing nothing.
+    } else if (popAction.kind === "pop-to-screen-frame" && escapeOwner) {
+      setSelectedElement(null);
+      setSelectedLayerIdsState([]);
+      setOverviewSelectedScreenIds([escapeOwner.fileId]);
+      setOverviewClearSelectionRequest((request) => request + 1);
+      return;
+    }
     setSelectedElement(null);
     setHoveredElement(null);
     setOverviewSelectedScreenIds([]);
@@ -19411,10 +20956,17 @@ function DesignEditor() {
     cancelActiveEditorDrag,
     drawMode,
     enterOverviewFromZoom,
+    focusedAnnotationSending,
     handleBreakpointBarSelect,
+    keyboardShortcutsOpen,
+    handleCloseKeyboardShortcuts,
+    handleExitFocusedDrawMode,
+    handleExitOverviewDrawMode,
     mode,
+    overviewAnnotationSending,
     pinMode,
     selectedElement,
+    selectedLayerIdsState,
     viewMode,
   ]);
 
@@ -19687,8 +21239,6 @@ function DesignEditor() {
       const frames = getAllScreenFrameEntries({
         overviewScreens,
         canvasFrameGeometryById,
-        boardFrameGeometry,
-        boardFileId,
       });
       const nextFrame = frames.find((frame) => frame.id === nextScreen.id);
       const bounds = nextFrame ? getFrameGroupBounds([nextFrame]) : null;
@@ -19701,13 +21251,7 @@ function DesignEditor() {
         });
       }
     },
-    [
-      activeFile,
-      boardFileId,
-      boardFrameGeometry,
-      canvasFrameGeometryById,
-      overviewScreens,
-    ],
+    [activeFile, canvasFrameGeometryById, overviewScreens],
   );
 
   // Current Figma — Tab/Shift+Tab traverse siblings within the selected
@@ -19754,6 +21298,15 @@ function DesignEditor() {
       owner.node.parentId,
     );
     if (!parentOwner || parentOwner.fileId !== owner.fileId) return;
+    // BUG-ESCAPE-SHELL (same mechanism as handleEscapeHotkey's pop walk): the
+    // flat ownership map still resolves a top-level layer's parentId to the
+    // collapsed <html>/<body> shell node, which the layers panel never shows
+    // as selectable. Without this guard, Shift+Enter/"\\" on a top-level
+    // layer would select <body> instead of no-op'ing like the comment above
+    // already documents.
+    if (!hasSelectableCodeLayerParent({ parentNode: parentOwner.node })) {
+      return;
+    }
     selectCodeLayerNodesForHotkey(
       parentOwner.fileId,
       [parentOwner.node],
@@ -19957,6 +21510,13 @@ function DesignEditor() {
     },
     // H2: Cmd+Alt+K — create component from the current selection.
     onCreateComponent: canEditDesign ? handleCreateComponentHotkey : undefined,
+    // Cmd+Alt+B — Detach instance. Only wired while the selection actually is
+    // a component instance, matching onOpacityChange's "absent handler is a
+    // no-op" convention just below.
+    onDetachInstance:
+      canEditDesign && selectedComponentNodeId
+        ? handleDetachInstanceMenuAction
+        : undefined,
     // H2: plain digit 1-9/0 — set selection opacity. Only supplied while a
     // layer is selected so unselected digit presses fall through untouched
     // (useDesignHotkeys treats an absent handler as "not handled").
@@ -19964,6 +21524,17 @@ function DesignEditor() {
       canEditDesign && selectedElement
         ? ({ opacity }) => handleOpacityHotkey(opacity)
         : undefined,
+    // Cmd+U / Cmd+Shift+X — toggle underline/strikethrough. Only wired while
+    // a layer is selected, matching onOpacityChange's "absent handler is a
+    // no-op" convention.
+    onToggleUnderline:
+      canEditDesign && selectedElement
+        ? handleToggleUnderlineHotkey
+        : undefined,
+    onToggleStrikethrough:
+      canEditDesign && selectedElement
+        ? handleToggleStrikethroughHotkey
+        : undefined,
     onFlipHorizontal: canEditDesign ? handleFlipHorizontal : undefined,
     onFlipVertical: canEditDesign ? handleFlipVertical : undefined,
     onSwapFillStroke: canEditDesign ? handleSwapFillStroke : undefined,
@@ -19980,6 +21551,7 @@ function DesignEditor() {
     // editing actions, so they work regardless of canEditDesign.
     onToggleUi: handleToggleUi,
     onToggleComments: handleToggleComments,
+    onShowKeyboardShortcuts: handleShowKeyboardShortcuts,
   });
 
   const startRetryGeneration = useCallback(
@@ -20747,6 +22319,56 @@ function DesignEditor() {
     }
   }, [renderPngBlob, showPngCaptureError, t]);
 
+  const handleCopyAsFigmaSvg = useCallback(async () => {
+    if (figmaSvgExportingRef.current) return;
+    if (!canCopyFigmaSvgToClipboard()) {
+      toast.error(t("designEditor.toasts.figmaSvgUnsupported"));
+      return;
+    }
+
+    figmaSvgExportingRef.current = true;
+    setFigmaSvgExporting(true);
+    try {
+      // The export action defaults to `filename: "index.html"` when no
+      // fileId is given -- that only happens to work for a design whose
+      // screen is literally named index.html. This context menu is shared
+      // between single-screen edit view and overview mode, so resolve the
+      // actual target screen the same way PNG export does (selectedScreenIds
+      // covers both: activeFile.id in single-screen view, the
+      // overview-selected screen id(s) in overview mode) instead of letting
+      // the action guess. Regression: "Copy as SVG" on any non-index.html
+      // screen failed with "Design file not found".
+      const targetFileId = activeFile?.id ?? selectedScreenIds[0] ?? undefined;
+      await copyDesignAsFigmaSvg({
+        designId: id,
+        fileId: targetFileId,
+        nodeId: selectedElementLayerId ?? undefined,
+      });
+      toast.success(t("designEditor.toasts.figmaSvgCopied"));
+    } catch (error) {
+      if (error instanceof FigmaSvgCopyError) {
+        const key =
+          error.code === "blocked"
+            ? "designEditor.toasts.figmaSvgBlocked"
+            : error.code === "unsupported"
+              ? "designEditor.toasts.figmaSvgUnsupported"
+              : error.code === "render-failed"
+                ? "designEditor.toasts.figmaSvgRenderError"
+                : "designEditor.toasts.figmaSvgWriteError";
+        toast.error(t(key));
+      } else {
+        toast.error(
+          error instanceof Error
+            ? error.message
+            : t("designEditor.toasts.figmaSvgExportError"),
+        );
+      }
+    } finally {
+      figmaSvgExportingRef.current = false;
+      setFigmaSvgExporting(false);
+    }
+  }, [activeFile?.id, id, selectedElementLayerId, selectedScreenIds, t]);
+
   const handleDownloadSvg = useCallback(
     async (settings?: Partial<ExportSettingsValue>) => {
       const iframe = document.querySelector<HTMLIFrameElement>(
@@ -21148,37 +22770,107 @@ ${serializedHtml}
       new Map(activeCodeLayerProjection.nodes.map((node) => [node.id, node])),
     [activeCodeLayerProjection],
   );
-  const codeLayerModelsByFile = useMemo(
-    () =>
-      files.map((file) => {
-        const content =
-          file.id === activeFile?.id
-            ? activeProjectionContent
-            : getProjectionContentForScreen(file.id);
-        const projection =
-          file.id === activeFile?.id
-            ? activeCodeLayerProjection
-            : buildCodeLayerProjection(content);
-        const tree =
-          file.id === activeFile?.id
-            ? activeCodeLayerTree
-            : buildCodeLayerTree(projection);
-        return {
-          fileId: file.id,
-          projection,
-          tree,
-          nodeById: new Map(projection.nodes.map((node) => [node.id, node])),
-        };
-      }),
-    [
-      activeCodeLayerProjection,
-      activeCodeLayerTree,
-      activeProjectionContent,
-      activeFile?.id,
-      files,
-      getProjectionContentForScreen,
-    ],
+  const overviewScreenById = useMemo(
+    () => new Map(overviewScreens.map((screen) => [screen.id, screen])),
+    [overviewScreens],
   );
+  type CodeLayerFileModel = {
+    fileId: string;
+    projection: CodeLayerProjection;
+    sourceProjection: CodeLayerProjection;
+    runtimeOnly: boolean;
+    tree: CodeLayerTreeNode[];
+    nodeById: Map<string, CodeLayerNode>;
+  };
+  const codeLayerModelCacheRef = useRef<Map<string, CodeLayerFileModel>>(
+    new Map(),
+  );
+  const codeLayerModelsArrayRef = useRef<CodeLayerFileModel[]>([]);
+  const codeLayerModelsByFile = useMemo(() => {
+    const cache = codeLayerModelCacheRef.current;
+    const liveFileIds = new Set(files.map((file) => file.id));
+    const models = files.map((file): CodeLayerFileModel => {
+      const sourceProjection =
+        getCodeLayerProjectionForScreen(file.id) ??
+        buildCodeLayerProjection(getProjectionContentForScreen(file.id));
+      const runtimeSnapshot = runtimeLayerSnapshotsById[file.id];
+      const runtimeProjectionEligible = shouldUseRuntimeLayerProjection({
+        screen: overviewScreenById.get(file.id),
+        fallbackSourceType: designSourceType,
+        // Eligibility follows the persisted route URL, not `content`: the
+        // active projection content may already be an SSR HTML snapshot.
+        content: file.content,
+      });
+      const runtimeProjection =
+        runtimeSnapshot && runtimeProjectionEligible
+          ? getRuntimeCodeLayerProjection(file.id, runtimeSnapshot.html)
+          : null;
+      const useRuntimeProjection = shouldPreferRuntimeLayerProjection({
+        eligible: runtimeProjectionEligible,
+        runtimeNodeCount: runtimeProjection?.nodes.length ?? 0,
+        sourceNodeCount: sourceProjection.nodes.length,
+      });
+      const projection = useRuntimeProjection
+        ? runtimeProjection!
+        : sourceProjection;
+      const cached = cache.get(file.id);
+      if (
+        cached &&
+        cached.projection === projection &&
+        cached.sourceProjection === sourceProjection &&
+        cached.runtimeOnly === useRuntimeProjection
+      ) {
+        return cached;
+      }
+      const tree = useRuntimeProjection
+        ? buildCodeLayerTree(projection)
+        : file.id === activeFile?.id
+          ? activeCodeLayerTree
+          : buildCodeLayerTree(projection);
+      const model: CodeLayerFileModel = {
+        fileId: file.id,
+        projection,
+        sourceProjection,
+        runtimeOnly: useRuntimeProjection,
+        tree,
+        nodeById: new Map(projection.nodes.map((node) => [node.id, node])),
+      };
+      cache.set(file.id, model);
+      return model;
+    });
+    for (const fileId of cache.keys()) {
+      if (!liveFileIds.has(fileId)) cache.delete(fileId);
+    }
+    for (const fileId of runtimeProjectionCacheRef.current.keys()) {
+      if (!liveFileIds.has(fileId)) {
+        runtimeProjectionCacheRef.current.delete(fileId);
+      }
+    }
+    for (const fileId of nonActiveProjectionCacheRef.current.keys()) {
+      if (!liveFileIds.has(fileId)) {
+        nonActiveProjectionCacheRef.current.delete(fileId);
+      }
+    }
+    const previousModels = codeLayerModelsArrayRef.current;
+    if (
+      previousModels.length === models.length &&
+      models.every((model, index) => model === previousModels[index])
+    ) {
+      return previousModels;
+    }
+    codeLayerModelsArrayRef.current = models;
+    return models;
+  }, [
+    activeCodeLayerTree,
+    activeFile?.id,
+    designSourceType,
+    files,
+    getCodeLayerProjectionForScreen,
+    getProjectionContentForScreen,
+    getRuntimeCodeLayerProjection,
+    overviewScreenById,
+    runtimeLayerSnapshotsById,
+  ]);
   const codeLayerModelByFileId = useMemo(
     () => new Map(codeLayerModelsByFile.map((model) => [model.fileId, model])),
     [codeLayerModelsByFile],
@@ -21186,7 +22878,12 @@ ${serializedHtml}
   const codeLayerOwnerByNodeId = useMemo(() => {
     const owners = new Map<
       string,
-      { fileId: string; node: CodeLayerNode; tree: CodeLayerTreeNode[] }
+      {
+        fileId: string;
+        node: CodeLayerNode;
+        tree: CodeLayerTreeNode[];
+        runtimeOnly: boolean;
+      }
     >();
     codeLayerModelsByFile.forEach((model) => {
       model.projection.nodes.forEach((node) => {
@@ -21194,6 +22891,7 @@ ${serializedHtml}
           fileId: model.fileId,
           node,
           tree: model.tree,
+          runtimeOnly: model.runtimeOnly,
         });
       });
     });
@@ -21278,6 +22976,22 @@ ${serializedHtml}
         }
         const value = override[kind];
         if (value === undefined) return;
+        // The optimistic override exists only until the connected source/HMR
+        // snapshot confirms the durable JSX metadata. Once source and preview
+        // agree, drop this axis so subsequent source edits remain authoritative.
+        if (!fileIds.has(id) && sourceIds.has(id) === value) {
+          const remaining = { ...override };
+          delete remaining[kind];
+          if (
+            remaining.hidden === undefined &&
+            remaining.locked === undefined
+          ) {
+            layerStateOverridesRef.current.delete(id);
+          } else {
+            layerStateOverridesRef.current.set(id, remaining);
+          }
+          return;
+        }
         if (value) next.add(id);
         else next.delete(id);
       });
@@ -21355,25 +23069,48 @@ ${serializedHtml}
     },
     [codeLayerModelByFileId],
   );
-  const activeCodeLayerPanelNodes = useMemo(
-    () =>
-      codeLayerTreeToPanelNodes(
-        activeCodeLayerTree,
-        lockedLayerIds,
-        hiddenLayerIds,
-      ),
-    [activeCodeLayerTree, hiddenLayerIds, lockedLayerIds],
-  );
-
   const visualScreenFileIds = useMemo(
     () => new Set(overviewScreens.map((screen) => screen.id)),
     [overviewScreens],
   );
-  const layerPanelFiles = useMemo<LayersPanelFile[]>(
-    () =>
+  // One bottom-to-top screen stack owns both canvas paint order (`geometry.z`)
+  // and the Layers file rows. LayersPanel reverses each sibling group for its
+  // topmost-first display, so feed it this canonical bottom-to-top sequence.
+  const canonicalOverviewScreenIds = useMemo(
+    () => getCanonicalScreenStack(overviewScreens, canvasFrameGeometryById),
+    [canvasFrameGeometryById, overviewScreens],
+  );
+  const canonicalVisualFiles = useMemo(() => {
+    const visualFileById = new Map(
       files
         .filter((file) => visualScreenFileIds.has(file.id))
-        .map((file) => ({
+        .map((file) => [file.id, file] as const),
+    );
+    return canonicalOverviewScreenIds
+      .map((screenId) => visualFileById.get(screenId))
+      .filter((file): file is (typeof files)[number] => Boolean(file));
+  }, [canonicalOverviewScreenIds, files, visualScreenFileIds]);
+  const layerPanelFiles = useMemo<LayersPanelFile[]>(
+    () =>
+      canonicalVisualFiles.map((file) => ({
+        id: file.id,
+        name: prettyScreenName(file.filename),
+        filename: file.filename,
+        fileType: file.fileType,
+        detail: file.filename,
+        locked: lockedLayerIds.has(file.id),
+        hidden: hiddenLayerIds.has(file.id),
+        lockable: true,
+        hideable: true,
+        renamable: true,
+      })),
+    [canonicalVisualFiles, hiddenLayerIds, lockedLayerIds],
+  );
+  const overviewLayerPanelFiles = useMemo<LayersPanelFile[]>(
+    () =>
+      canonicalVisualFiles.map((file) => {
+        const model = codeLayerModelByFileId.get(file.id);
+        return {
           id: file.id,
           name: prettyScreenName(file.filename),
           filename: file.filename,
@@ -21384,39 +23121,18 @@ ${serializedHtml}
           lockable: true,
           hideable: true,
           renamable: true,
-        })),
-    [files, hiddenLayerIds, lockedLayerIds, visualScreenFileIds],
-  );
-  const overviewLayerPanelFiles = useMemo<LayersPanelFile[]>(
-    () =>
-      files
-        .filter((file) => visualScreenFileIds.has(file.id))
-        .map((file) => {
-          const model = codeLayerModelByFileId.get(file.id);
-          return {
-            id: file.id,
-            name: prettyScreenName(file.filename),
-            filename: file.filename,
-            fileType: file.fileType,
-            detail: file.filename,
-            locked: lockedLayerIds.has(file.id),
-            hidden: hiddenLayerIds.has(file.id),
-            lockable: true,
-            hideable: true,
-            renamable: true,
-            layers: codeLayerTreeToPanelNodes(
-              model?.tree ?? [],
-              lockedLayerIds,
-              hiddenLayerIds,
-            ),
-          };
-        }),
+          layers: codeLayerTreeToPanelNodes(
+            model?.tree ?? [],
+            lockedLayerIds,
+            hiddenLayerIds,
+          ),
+        };
+      }),
     [
+      canonicalVisualFiles,
       codeLayerModelByFileId,
-      files,
       hiddenLayerIds,
       lockedLayerIds,
-      visualScreenFileIds,
     ],
   );
 
@@ -21438,16 +23154,31 @@ ${serializedHtml}
     return nodes.length > 0 ? nodes : undefined;
   }, [boardFileId, codeLayerModelByFileId, lockedLayerIds, hiddenLayerIds]);
 
-  const activeLayerPanelNodes = useMemo<LayersPanelNode[]>(
-    () => activeCodeLayerPanelNodes,
-    [activeCodeLayerPanelNodes],
-  );
+  const activeLayerPanelNodes = useMemo<LayersPanelNode[]>(() => {
+    const activeTree = activeFile?.id
+      ? (codeLayerModelByFileId.get(activeFile.id)?.tree ?? activeCodeLayerTree)
+      : activeCodeLayerTree;
+    return codeLayerTreeToPanelNodes(
+      activeTree,
+      lockedLayerIds,
+      hiddenLayerIds,
+    );
+  }, [
+    activeCodeLayerTree,
+    activeFile?.id,
+    codeLayerModelByFileId,
+    hiddenLayerIds,
+    lockedLayerIds,
+  ]);
 
   const selectedLayerIds = useMemo(() => {
     const validIds = new Set(
       (viewMode === "overview"
         ? codeLayerModelsByFile.flatMap((model) => model.projection.nodes)
-        : activeCodeLayerProjection.nodes
+        : activeFile?.id
+          ? (codeLayerModelByFileId.get(activeFile.id)?.projection.nodes ??
+            activeCodeLayerProjection.nodes)
+          : activeCodeLayerProjection.nodes
       ).map((node) => node.id),
     );
     const fileIds = new Set(files.map((file) => file.id));
@@ -21490,6 +23221,8 @@ ${serializedHtml}
     return filtered;
   }, [
     activeCodeLayerProjection.nodes,
+    activeFile?.id,
+    codeLayerModelByFileId,
     codeLayerModelsByFile,
     createdOverviewLayerSelection,
     files,
@@ -21765,15 +23498,22 @@ ${serializedHtml}
   const selectedScreenGeometry = useMemo<ScreenGeometrySelection | null>(() => {
     return getSelectedScreenGeometryForInspector({
       selectedInspectorElementCount: selectedInspectorElements.length,
-      selectedScreenIds,
+      // Inspector geometry is selection-driven, never active-file-driven.
+      // `selectedScreenIds` deliberately falls back to activeFile for agent
+      // context/navigation, but feeding that fallback into the inspector made
+      // a cleared selection immediately reappear as the active screen. That
+      // broke Figma's Escape semantics and made Page properties unreachable.
+      selectedScreenIds:
+        viewMode === "overview" ? overviewSelectedScreenIds : [],
       overviewScreens,
       canvasFrameGeometryById,
     });
   }, [
     canvasFrameGeometryById,
+    overviewSelectedScreenIds,
     overviewScreens,
     selectedInspectorElements.length,
-    selectedScreenIds,
+    viewMode,
   ]);
 
   const layerPanelSelectedIds = useMemo(
@@ -22324,16 +24064,28 @@ ${serializedHtml}
         ?.connectionId ?? "")
     : "";
 
-  // Fetch the active localhost connection's stored rootPath so the write-
-  // consent dialog can show a real folder path instead of the raw connection
-  // id when no per-screen sourceFile is available. Scoped to the single
-  // connection id (not the full list) and only enabled once we have one.
+  // Fetch the connected roots used by every localhost screen. Besides the
+  // consent dialog, this lets React debug provenance such as /@fs/ absolute
+  // paths be reduced to safe project-relative source anchors before the
+  // semantic coding-agent handoff. The ref is read by gesture callbacks above
+  // without making root-path hydration part of their render identity.
   const { data: activeLocalhostConnectionResult } = useActionQuery<{
     connections?: Array<{ id: string; rootPath?: string | null }>;
   }>(
     "list-localhost-connections",
-    { id: activeLocalhostConnectionId || undefined },
-    { enabled: Boolean(activeLocalhostConnectionId) },
+    {},
+    {
+      enabled: overviewScreens.some(
+        (screen) => screen.sourceType === "localhost" && screen.connectionId,
+      ),
+    },
+  );
+  localhostConnectionRootPathByIdRef.current = new Map(
+    (activeLocalhostConnectionResult?.connections ?? []).flatMap((connection) =>
+      connection.rootPath
+        ? ([[connection.id, connection.rootPath]] as Array<[string, string]>)
+        : [],
+    ),
   );
   const activeLocalhostConnectionRootPath =
     activeLocalhostConnectionResult?.connections?.find(
@@ -22586,29 +24338,25 @@ ${serializedHtml}
 
     requestLocalhostWrite({
       files: [relPath],
-      onGranted: ({ bridgeToken }) => {
+      onGranted: () => {
         void (async () => {
           setApplyToSourcePending(true);
           try {
             // Read the file's current versionHash immediately before writing
-            // so write-local-file can detect a 409 conflict if the on-disk
-            // file changed since this snapshot (e.g. the dev process or
-            // another editor session touched it between opening the screen
-            // and clicking "Apply to source"). This is a best-effort
-            // freshness check, not a lock — the read/write pair still has a
-            // small race window, but it's far tighter than sending no hash.
-            let expectedVersionHash: string | undefined;
-            try {
-              const readResult = (await callAction("read-local-file", {
-                designId: id,
-                connectionId,
-                path: relPath,
-              })) as { versionHash?: string } | undefined;
-              expectedVersionHash = readResult?.versionHash;
-            } catch {
-              // If the pre-write read fails (e.g. file briefly missing),
-              // fall through and write without a version guard rather than
-              // blocking the whole apply-to-source flow on it.
+            // so write-local-file can reject a concurrent on-disk edit. Never
+            // downgrade to an unguarded overwrite when the read fails: the
+            // semantic React path is agent-driven, and this legacy whole-file
+            // path is intentionally limited to directly writable HTML/CSS.
+            const readResult = (await callAction("read-local-file", {
+              designId: id,
+              connectionId,
+              path: relPath,
+            })) as { versionHash?: string } | undefined;
+            const expectedVersionHash = readResult?.versionHash;
+            if (!expectedVersionHash) {
+              throw new Error(
+                `Could not verify the current version of ${relPath}; no source was written.`,
+              );
             }
 
             await callAction("write-local-file", {
@@ -22631,9 +24379,6 @@ ${serializedHtml}
           } finally {
             setApplyToSourcePending(false);
           }
-          // Suppress unused-var warning; bridgeToken is checked by the bridge
-          // internally via the X-Bridge-Token header (set in write-local-file).
-          void bridgeToken;
         })();
       },
       onCancel: () => {
@@ -22656,11 +24401,24 @@ ${serializedHtml}
   const selectedDomLayerIds = selectedLayerIds.filter(
     (id) => !id.startsWith("__") && !fileIdSet.has(id),
   );
+  const selectedDomLayerOwners = selectedDomLayerIds.map((layerId) =>
+    codeLayerOwnerByNodeId.get(layerId),
+  );
+  const selectedRuntimeLayerOwners = selectedDomLayerOwners.filter(
+    (owner) => owner?.runtimeOnly,
+  );
+  const selectedLayersUseCompatibleSourceBackend =
+    selectedRuntimeLayerOwners.length === 0 ||
+    (selectedRuntimeLayerOwners.length === selectedDomLayerIds.length &&
+      selectedRuntimeLayerOwners.every(
+        (owner) => owner?.fileId === selectedRuntimeLayerOwners[0]?.fileId,
+      ));
   const canGroup =
     canEditDesign &&
     viewMode === "single" &&
     Boolean(activeFile) &&
-    selectedDomLayerIds.length >= 2;
+    selectedDomLayerIds.length >= 2 &&
+    selectedLayersUseCompatibleSourceBackend;
   // canUngroup: one or more DOM-node layers selected (L16: handleUngroupSelection
   // loops all selected containers), and EVERY selected layer must be a
   // container with at least one element child. L3: code-layer's applyUnwrap
@@ -22674,11 +24432,41 @@ ${serializedHtml}
     viewMode === "single" &&
     Boolean(activeFile) &&
     selectedDomLayerIds.length >= 1 &&
+    selectedLayersUseCompatibleSourceBackend &&
     selectedDomLayerIds.every((id) => {
       const node = codeLayerOwnerByNodeId.get(id)?.node;
       return Boolean(node) && node!.children.length > 0;
     });
 
+  const handleScreenLayerMove = useCallback(
+    (intent: LayersPanelMoveIntent) => {
+      const nextOrder = reorderCanonicalScreenStack({
+        orderedIds: canonicalOverviewScreenIds,
+        draggedIds: intent.draggedIds,
+        targetId: intent.targetId,
+        placement: intent.placement,
+      });
+      if (!nextOrder) return;
+
+      const before = getCanvasFrameGeometry(designDataJsonRef.current);
+      const after = cloneCanvasFrameGeometry(before);
+      nextOrder.forEach((screenId, z) => {
+        const screenIndex = overviewScreens.findIndex(
+          (screen) => screen.id === screenId,
+        );
+        const screen = overviewScreens[screenIndex];
+        if (!screen || screenIndex < 0) return;
+        const fallback = getInitialFrameGeometry(screenIndex, {
+          width: screen.width ?? 1280,
+          height: screen.height ?? 2560,
+        });
+        after[screenId] = { ...fallback, ...before[screenId], z };
+      });
+      handleGeometryCommit(before, after);
+    },
+    [canonicalOverviewScreenIds, handleGeometryCommit, overviewScreens],
+  );
+
   const canMoveLayer = useCallback(
     (intent: LayersPanelMoveIntent) => {
       const targetOwner = codeLayerOwnerByNodeId.get(intent.targetId);
@@ -22688,6 +24476,21 @@ ${serializedHtml}
       const targetFile = !targetOwner
         ? files.find((file) => file.id === intent.targetId)
         : undefined;
+      const draggedScreenIds = intent.draggedIds.filter((draggedId) =>
+        visualScreenFileIds.has(draggedId),
+      );
+      if (draggedScreenIds.length > 0) {
+        return Boolean(
+          draggedScreenIds.length === intent.draggedIds.length &&
+          targetFile &&
+          visualScreenFileIds.has(targetFile.id) &&
+          intent.placement !== "inside" &&
+          draggedScreenIds.every(
+            (screenId) =>
+              screenId !== targetFile.id && !lockedLayerIds.has(screenId),
+          ),
+        );
+      }
       // L8: a locked or hidden row can still be used as a before/after/inside
       // drop ANCHOR — locking/hiding a layer shouldn't make it impossible to
       // position other layers relative to it in the panel. Only dragging
@@ -22695,11 +24498,35 @@ ${serializedHtml}
       if (!targetOwner && !targetFile) {
         return false;
       }
+      const runtimeDraggedOwners = intent.draggedIds.map((draggedId) =>
+        codeLayerOwnerByNodeId.get(draggedId),
+      );
+      const hasRuntimeDraggedOwner = runtimeDraggedOwners.some(
+        (owner) => owner?.runtimeOnly,
+      );
+      if (targetOwner?.runtimeOnly || hasRuntimeDraggedOwner) {
+        if (!targetOwner?.runtimeOnly || intent.draggedIds.length !== 1) {
+          return false;
+        }
+        const draggedId = intent.draggedIds[0]!;
+        const draggedOwner = runtimeDraggedOwners[0];
+        return Boolean(
+          draggedOwner?.runtimeOnly &&
+          draggedId !== intent.targetId &&
+          draggedOwner.fileId === targetOwner.fileId &&
+          !effectiveCodeLayerState.lockedIds.has(draggedId) &&
+          !collectCodeLayerAncestors(
+            targetOwner.tree,
+            intent.targetId,
+          ).includes(draggedId),
+        );
+      }
       return intent.draggedIds.some((draggedId) => {
         const draggedOwner = codeLayerOwnerByNodeId.get(draggedId);
         if (
           draggedId === intent.targetId ||
           !draggedOwner ||
+          draggedOwner.runtimeOnly ||
           // L8: dragging a LOCKED row is still blocked (locked means
           // don't-touch-this-layer). A HIDDEN row is now draggable — hidden
           // only means "not rendered in canvas", not "structurally frozen".
@@ -22727,7 +24554,13 @@ ${serializedHtml}
         return true;
       });
     },
-    [codeLayerOwnerByNodeId, effectiveCodeLayerState, files],
+    [
+      codeLayerOwnerByNodeId,
+      effectiveCodeLayerState,
+      files,
+      lockedLayerIds,
+      visualScreenFileIds,
+    ],
   );
 
   // L19: dropping a layer directly onto a file/screen row (which has no
@@ -22929,6 +24762,15 @@ ${serializedHtml}
     (intent: LayersPanelMoveIntent) => {
       if (!canEditDesign) return;
       if (!canMoveLayer(intent)) return;
+      if (
+        intent.draggedIds.length > 0 &&
+        intent.draggedIds.every((draggedId) =>
+          visualScreenFileIds.has(draggedId),
+        )
+      ) {
+        handleScreenLayerMove(intent);
+        return;
+      }
       const targetOwner = codeLayerOwnerByNodeId.get(intent.targetId);
       if (!targetOwner) {
         const targetFile = files.find((file) => file.id === intent.targetId);
@@ -22937,6 +24779,51 @@ ${serializedHtml}
         }
         return;
       }
+      const runtimeDraggedOwner =
+        intent.draggedIds.length === 1
+          ? codeLayerOwnerByNodeId.get(intent.draggedIds[0]!)
+          : undefined;
+      if (targetOwner.runtimeOnly || runtimeDraggedOwner?.runtimeOnly) {
+        if (!runtimeDraggedOwner) {
+          return;
+        }
+        const executionMode = resolveRuntimeStructureMoveExecutionMode({
+          subjectRuntimeOnly: runtimeDraggedOwner.runtimeOnly,
+          targetRuntimeOnly: targetOwner.runtimeOnly,
+          sourceScreenId: runtimeDraggedOwner.fileId,
+          targetScreenId: targetOwner.fileId,
+        });
+        if (executionMode === "screen-bridge") {
+          // Keep the existing fast, optimistic in-iframe path when one
+          // screen-scoped bridge owns both runtime endpoints. Cross-screen or
+          // mixed runtime/source ownership cannot be represented by that
+          // one-screen StructureMove message and must go through the semantic
+          // coding-agent handoff below.
+          runtimeStructureMoveRevisionRef.current += 1;
+          setRuntimeStructureMoveRequest({
+            requestId: runtimeStructureMoveRevisionRef.current,
+            screenId: targetOwner.fileId,
+            subject: {
+              selector: runtimeDraggedOwner.node.selector,
+              sourceId: bridgeSourceIdForCodeLayerNode(
+                runtimeDraggedOwner.node,
+              ),
+            },
+            anchor: {
+              selector: targetOwner.node.selector,
+              sourceId: bridgeSourceIdForCodeLayerNode(targetOwner.node),
+            },
+            placement: intent.placement,
+          });
+          return;
+        }
+        sendRuntimeLayerMoveSemanticHandoff(
+          intent.draggedIds[0]!,
+          intent.targetId,
+          intent.placement,
+        );
+        return;
+      }
       // L8: locked/hidden is no longer a blocker for using this row as a drop
       // anchor (see canMoveLayer) — only dragging a LOCKED row is blocked,
       // checked per-draggedId below. Hidden rows are draggable.
@@ -23289,23 +25176,32 @@ ${serializedHtml}
       files,
       getFreshActiveContent,
       handleLayerMoveToScreen,
+      handleScreenLayerMove,
       recordContentHistoryEntry,
       recordLocalContentHistoryEntry,
+      sendRuntimeLayerMoveSemanticHandoff,
       t,
+      visualScreenFileIds,
     ],
   );
 
   const handleLayerHover = useCallback(
     (layerId: string) => {
       const owner = codeLayerOwnerByNodeId.get(layerId);
-      if (!owner || owner.fileId !== activeFile?.id) return;
+      if (!owner) return;
+      // Match handleLayerSelectionChange: hover from the LayersPanel must
+      // follow the hovered layer's owning screen even when it isn't the
+      // active screen (overview mode shows layers from every screen), not
+      // just silently no-op like the previous same-file-only guard did.
       setHoveredElement(elementInfoFromCodeLayerNode(owner.node));
+      setHoveredElementScreenId(owner.fileId);
     },
-    [activeFile?.id, codeLayerOwnerByNodeId],
+    [codeLayerOwnerByNodeId],
   );
 
   const handleLayerLeave = useCallback((_layerId: string) => {
     setHoveredElement(null);
+    setHoveredElementScreenId(null);
   }, []);
 
   const handleLayerSelectionChange = useCallback(
@@ -23755,10 +25651,6 @@ ${serializedHtml}
   const handleToggleLayerLocked = useCallback(
     (layerId: string, locked: boolean) => {
       if (!canEditDesign) return;
-      layerStateOverridesRef.current.set(layerId, {
-        ...layerStateOverridesRef.current.get(layerId),
-        locked,
-      });
       const applyLockedState = () => {
         setLockedLayerIds((current) => {
           const next = new Set(current);
@@ -23767,11 +25659,26 @@ ${serializedHtml}
           return next;
         });
       };
+      const owner = codeLayerOwnerByNodeId.get(layerId);
+      if (owner?.runtimeOnly) {
+        if (!sendRuntimeLayerStateSemanticHandoff(layerId, "locked", locked)) {
+          return;
+        }
+        layerStateOverridesRef.current.set(layerId, {
+          ...layerStateOverridesRef.current.get(layerId),
+          locked,
+        });
+        applyLockedState();
+        return;
+      }
+      layerStateOverridesRef.current.set(layerId, {
+        ...layerStateOverridesRef.current.get(layerId),
+        locked,
+      });
       if (files.some((file) => file.id === layerId)) {
         applyLockedState();
         return;
       }
-      const owner = codeLayerOwnerByNodeId.get(layerId);
       const node = owner?.node;
       if (!owner || !node) {
         applyLockedState();
@@ -23804,16 +25711,13 @@ ${serializedHtml}
       codeLayerOwnerByNodeId,
       files,
       getFreshActiveContent,
+      sendRuntimeLayerStateSemanticHandoff,
     ],
   );
 
   const handleToggleLayerHidden = useCallback(
     (layerId: string, hidden: boolean) => {
       if (!canEditDesign) return;
-      layerStateOverridesRef.current.set(layerId, {
-        ...layerStateOverridesRef.current.get(layerId),
-        hidden,
-      });
       const applyHiddenState = () => {
         setHiddenLayerIds((current) => {
           const next = new Set(current);
@@ -23822,11 +25726,26 @@ ${serializedHtml}
           return next;
         });
       };
+      const owner = codeLayerOwnerByNodeId.get(layerId);
+      if (owner?.runtimeOnly) {
+        if (!sendRuntimeLayerStateSemanticHandoff(layerId, "hidden", hidden)) {
+          return;
+        }
+        layerStateOverridesRef.current.set(layerId, {
+          ...layerStateOverridesRef.current.get(layerId),
+          hidden,
+        });
+        applyHiddenState();
+        return;
+      }
+      layerStateOverridesRef.current.set(layerId, {
+        ...layerStateOverridesRef.current.get(layerId),
+        hidden,
+      });
       if (files.some((file) => file.id === layerId)) {
         applyHiddenState();
         return;
       }
-      const owner = codeLayerOwnerByNodeId.get(layerId);
       const node = owner?.node;
       if (!owner || !node) {
         applyHiddenState();
@@ -23859,6 +25778,7 @@ ${serializedHtml}
       codeLayerOwnerByNodeId,
       files,
       getFreshActiveContent,
+      sendRuntimeLayerStateSemanticHandoff,
     ],
   );
 
@@ -23907,14 +25827,13 @@ ${serializedHtml}
         const iframe = canvasContainerRef.current?.querySelector<HTMLElement>(
           "[data-design-preview-iframe]",
         );
-        if (iframe) {
-          const iframeRect = iframe.getBoundingClientRect();
-          const factor = zoom / 100;
-          return {
-            x: Math.max(0, (clientX - iframeRect.left) / factor),
-            y: Math.max(0, (clientY - iframeRect.top) / factor),
-          };
-        }
+        const point = computeIframeLocalCanvasPoint({
+          clientX,
+          clientY,
+          iframeRect: iframe?.getBoundingClientRect() ?? null,
+          zoomPercent: zoom,
+        });
+        if (point) return point;
       }
       // Overview mode: fall back to container-relative coords (overview uses its
       // own coordinate mapping for paste; this value is a best-effort fallback).
@@ -24017,7 +25936,6 @@ ${serializedHtml}
           ? screen.previewToken
           : undefined;
       const screenSnapshot = liveScreenSnapshotsById[screen.id]?.html;
-      const screenContentSignature = getContentSignature(screenContent);
       const useRuntimeReplacement = shouldUseOverviewRuntimeReplacement({
         sourceType: screenSourceType,
         externalSnapshotHtml: screenSnapshot,
@@ -24029,11 +25947,14 @@ ${serializedHtml}
             content: screenContent,
           })
         : undefined;
-      const screenContentKey = screenIsActive
-        ? [screen.id, contentRenderRevision].join(":")
-        : [screen.id, screen.updatedAt ?? "", screenContentSignature, 0].join(
-            ":",
-          );
+      const screenContentKey = getOverviewScreenContentKey({
+        screenId: screen.id,
+        screenIsActive,
+        contentRenderRevision,
+        updatedAt: screen.updatedAt,
+        content: screenContent,
+        useRuntimeReplacement,
+      });
 
       return (
         <DesignCanvas
@@ -24074,6 +25995,11 @@ ${serializedHtml}
                 }
               : null
           }
+          runtimeStructureMoveRequest={
+            runtimeStructureMoveRequest?.screenId === screen.id
+              ? runtimeStructureMoveRequest
+              : null
+          }
           screenId={screen.id}
           zoom={100}
           deviceFrame="none"
@@ -24084,6 +26010,15 @@ ${serializedHtml}
           onExternalContentSnapshot={(snapshot) =>
             handleScreenExternalContentSnapshot(screen.id, snapshot)
           }
+          onRuntimeLayerSnapshot={
+            shouldUseRuntimeLayerProjection({
+              screen,
+              fallbackSourceType: designSourceType,
+              content: screenContent,
+            })
+              ? getRuntimeLayerSnapshotCallback(screen.id)
+              : undefined
+          }
           fusionUrl={designFusionUrl}
           onComponentSourceJump={handleComponentSourceJump}
           motionTracks={screenIsActive ? motionTracksWire : []}
@@ -24212,8 +26147,10 @@ ${serializedHtml}
       pendingVisualStyleBaselineResetRequest,
       pendingTextRevertRequest,
       pendingStructureAckRequest,
+      runtimeStructureMoveRequest,
       contentRenderRevision,
       handleScreenExternalContentSnapshot,
+      handleScreenRuntimeLayerSnapshot,
       designFusionUrl,
       handleComponentSourceJump,
       motionTracksWire,
@@ -24430,7 +26367,19 @@ ${serializedHtml}
       setCreatedOverviewLayerSelection(null);
       setSelectedElement(null);
       setHoveredElement(null);
-      setSelectedLayerIdsState([pickedId]);
+      // PICK-RACE — see computeOverviewScreenPickSelectionIds's doc comment
+      // (design-editor/selection-state.ts) for the full race this closes:
+      // MultiScreenCanvas's shift-click toggle can't report its full
+      // multi-id array through the single-id onPick signature, so a
+      // shift-held pick must leave the current selection alone rather than
+      // clobber it to a wrong singleton.
+      setSelectedLayerIdsState((current) =>
+        computeOverviewScreenPickSelectionIds({
+          pickedId,
+          shiftKeyHeld: shiftKeyHeldRef.current,
+          currentSelectedLayerIds: current,
+        }),
+      );
       setActiveFileId(pickedId);
       setActiveTool("move");
       setMode("edit");
@@ -24706,6 +26655,7 @@ ${serializedHtml}
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
         <Button
+          ref={projectMenuTriggerRef}
           variant="ghost"
           size="icon"
           className="size-8 shrink-0 cursor-pointer rounded-md text-muted-foreground hover:bg-accent hover:text-foreground [&_svg]:size-[calc(var(--spacing)*5.5)]"
@@ -24717,6 +26667,11 @@ ${serializedHtml}
       <DropdownMenuContent
         align="start"
         className="design-editor-app-menu-content w-64"
+        onCloseAutoFocus={(event) => {
+          if (!suppressProjectMenuReturnFocusRef.current) return;
+          event.preventDefault();
+          suppressProjectMenuReturnFocusRef.current = false;
+        }}
       >
         <DropdownMenuItem asChild>
           <Link to="/">
@@ -24831,6 +26786,14 @@ ${serializedHtml}
             ? t("designEditor.stopPinningComments")
             : t("designEditor.pinComment")}
         </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onClick={handleShowKeyboardShortcutsFromMenu}>
+          <IconKeyboard className="mr-2 h-4 w-4" />
+          {t("designEditor.keyboardShortcuts.title")}
+          <DropdownMenuShortcut>
+            {"⌃⇧?" /* i18n-ignore keyboard shortcut */}
+          </DropdownMenuShortcut>
+        </DropdownMenuItem>
         {isSignedIn && (
           <>
             <DropdownMenuSeparator />
@@ -25185,6 +27148,85 @@ ${serializedHtml}
           ) : null}
         </div>
       </div>
+      {activeScreenIsLocalSource &&
+      viewMode === "single" &&
+      activeScreenPreviewUrl ? (
+        <div className="mt-1 flex min-w-0 items-center gap-1">
+          <a
+            href={activeScreenPreviewUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="flex h-7 min-w-0 flex-1 items-center gap-1.5 rounded-md border border-border bg-[var(--design-editor-panel-raised-bg)] px-2 text-[11px] text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            aria-label={"Open local preview" /* i18n-ignore */}
+            title={activeScreenPreviewUrl}
+          >
+            <IconLink className="size-3 shrink-0" />
+            <span className="min-w-0 flex-1 truncate font-mono">
+              {activeScreenPreviewUrl}
+            </span>
+            <IconExternalLink className="size-3 shrink-0" />
+          </a>
+          {(activeLocalhostRouteIsWritable ||
+            activeLocalhostRouteIsCompiledSource) &&
+          canEditDesign &&
+          id ? (
+            activeLocalhostRouteIsCompiledSource ? (
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <span className="inline-flex">
+                    <Button
+                      size="icon"
+                      variant="outline"
+                      className="size-7"
+                      disabled
+                      aria-label={t("designEditor.applyToSource")}
+                    >
+                      <IconDeviceFloppy className="size-3" />
+                    </Button>
+                  </span>
+                </TooltipTrigger>
+                <TooltipContent side="bottom">
+                  {t("designEditor.applyToSourceUnavailableCompiled")}
+                </TooltipContent>
+              </Tooltip>
+            ) : (
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Button
+                    size="icon"
+                    variant="outline"
+                    className="size-7"
+                    disabled={
+                      applyToSourcePending || !activeLocalhostSourceWriteContent
+                    }
+                    aria-label={
+                      applyToSourcePending
+                        ? t("designEditor.writingToSource")
+                        : t("designEditor.applyToSource")
+                    }
+                    onClick={handleApplyToSource}
+                  >
+                    {applyToSourcePending ? (
+                      <Spinner className="size-3" />
+                    ) : (
+                      <IconDeviceFloppy className="size-3" />
+                    )}
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent side="bottom">
+                  {!activeLocalhostSourceWriteContent
+                    ? NO_LOCALHOST_WRITE_CONTENT_MESSAGE
+                    : activeLocalhostRelPath
+                      ? t("designEditor.applyToSourcePath", {
+                          path: activeLocalhostRelPath,
+                        })
+                      : t("designEditor.applyToSource")}
+                </TooltipContent>
+              </Tooltip>
+            )
+          ) : null}
+        </div>
+      ) : null}
       {/* BP-DEEP v2 items 4/6/7 — the unified breakpoint/device segmented
           control gets its own slim row under the actions row: it needs
           ~130px+ (growing with each breakpoint) and the actions row above
@@ -25198,7 +27240,7 @@ ${serializedHtml}
   const leftContentWidth =
     activeLeftPanel === "code"
       ? Math.max(leftSidebarWidth, 640)
-      : Math.max(Math.min(leftSidebarWidth, 420), 320);
+      : Math.max(Math.min(leftSidebarWidth, 420), 220);
   const routeCodeFileId =
     activeLeftPanel === "code" ? searchParams.get("fileId") : null;
   const routeCodeFilename =
@@ -25497,9 +27539,14 @@ ${serializedHtml}
               onScale={handleScaleTool}
               onCommentPin={handlePinToolToggle}
               onModeChange={handleModeChange}
+              shortcutsPanelOpen={keyboardShortcutsOpen}
             />
           )}
 
+        {!embedded && keyboardShortcutsOpen && !questionFlowActive ? (
+          <KeyboardShortcutsPanel onClose={handleCloseKeyboardShortcuts} />
+        ) : null}
+
         {/* Canvas */}
         {questionFlowActive ? (
           <div className="relative mx-1 h-full min-w-0 flex-1 overflow-hidden rounded-xl bg-[var(--design-editor-canvas-bg)]">
@@ -25517,11 +27564,19 @@ ${serializedHtml}
           <CanvasContextMenu
             ref={canvasContextMenuRef}
             selectedCount={selectedElement ? 1 : selectedScreenIds.length}
+            layerCandidates={canvasLayerHitCandidates}
+            onSelectLayer={handleContextMenuSelectLayer}
             hasClipboard={hasCanvasClipboard}
             hasPropsClipboard={hasPropsClipboard}
             hasAnimationClipboard={hasAnimationClipboard}
             isLocked={activeLayerLocked}
             isHidden={activeLayerHidden}
+            labels={{
+              selectLayer: t("designEditor.componentInstances.selectLayer"),
+              goToMainComponent: t("designEditor.componentInstances.goToMain"),
+              swapInstance: t("designEditor.componentInstances.swap"),
+              detachInstance: t("designEditor.componentInstances.detach"),
+            }}
             // U4/U8: hasCanvasClipboard only reflects copies made in THIS
             // tab/window. Peek the live system clipboard right as the menu
             // opens so a copy made elsewhere is picked up before the
@@ -25529,6 +27584,7 @@ ${serializedHtml}
             // until the user's first same-tab copy even though a real
             // clipboard payload is already sitting in the OS clipboard.
             onOpenChange={(open) => {
+              if (!open) setCanvasLayerHitCandidates([]);
               if (open) void refreshClipboardFromSystemClipboard();
             }}
             canPasteHere={
@@ -25593,6 +27649,11 @@ ${serializedHtml}
               (selectedElement ||
                 (viewMode === "overview" && selectedScreenIds.length === 1)),
             )}
+            canCopyAsSvg={Boolean(
+              canEditDesign &&
+              (selectedElement ||
+                (viewMode === "overview" && selectedScreenIds.length === 1)),
+            )}
             canGroup={canGroup}
             canUngroup={canUngroup}
             canPasteToReplace={
@@ -25614,6 +27675,11 @@ ${serializedHtml}
               Boolean(selectedElement) &&
               !selectedElementAlreadyComponent
             }
+            // Figma instance-only cluster: only meaningful when the current
+            // selection IS a recognised component instance.
+            isComponentInstance={
+              canEditDesign && Boolean(selectedComponentNodeId)
+            }
             canFlipHorizontal={canEditDesign && Boolean(selectedElement)}
             canFlipVertical={canEditDesign && Boolean(selectedElement)}
             canAddAutoLayout={
@@ -25682,11 +27748,21 @@ ${serializedHtml}
             onPasteAnimation={handlePasteAnimation}
             onCopyAsCode={handleCopySelection}
             onCopyAsPng={() => void handleCopyAsPng()}
+            onCopyAsSvg={() => void handleCopyAsFigmaSvg()}
             onPasteToReplace={canEditDesign ? handlePasteToReplace : undefined}
             onFrameSelection={canEditDesign ? handleFrameSelection : undefined}
             onCreateComponent={
               canEditDesign ? handleCreateComponentHotkey : undefined
             }
+            onGoToMainComponent={
+              canEditDesign ? handleGoToMainComponentMenuAction : undefined
+            }
+            onSwapInstance={
+              canEditDesign ? handleSwapInstanceMenuAction : undefined
+            }
+            onDetachInstance={
+              canEditDesign ? handleDetachInstanceMenuAction : undefined
+            }
             onFlipHorizontal={canEditDesign ? handleFlipHorizontal : undefined}
             onFlipVertical={canEditDesign ? handleFlipVertical : undefined}
             onAddAutoLayout={canEditDesign ? handleAddAutoLayout : undefined}
@@ -25695,70 +27771,6 @@ ${serializedHtml}
           >
             {activeFile ? (
               <div className="flex min-w-0 flex-1 flex-col overflow-hidden">
-                {/* "Apply to source" affordance: write the current editor
-                    content back to the local HTML/CSS file via the bridge.
-                    Shown enabled for localhost-backed screens where the route
-                    maps to an .html/.htm/.css file (opens the consent dialog
-                    on first use), and shown disabled with an explanatory
-                    tooltip for compiled framework routes (.jsx/.tsx) where
-                    source write-back isn't available yet — rather than
-                    disappearing entirely, which reads as a bug. */}
-                {(activeLocalhostRouteIsWritable ||
-                  activeLocalhostRouteIsCompiledSource) &&
-                  canEditDesign &&
-                  id && (
-                    <div className="flex items-center gap-2 border-b border-border/50 bg-muted/30 px-3 py-1.5">
-                      {activeLocalhostRouteIsCompiledSource ? (
-                        <Tooltip>
-                          <TooltipTrigger asChild>
-                            <span className="inline-flex">
-                              <Button
-                                size="sm"
-                                variant="outline"
-                                className="h-6 gap-1.5 px-2 !text-[11px]"
-                                disabled
-                              >
-                                <IconDeviceFloppy className="size-3 shrink-0" />
-                                {activeLocalhostRelPath
-                                  ? t("designEditor.applyToSourcePath", {
-                                      path: activeLocalhostRelPath,
-                                    })
-                                  : t("designEditor.applyToSource")}
-                              </Button>
-                            </span>
-                          </TooltipTrigger>
-                          <TooltipContent side="bottom">
-                            {t("designEditor.applyToSourceUnavailableCompiled")}
-                          </TooltipContent>
-                        </Tooltip>
-                      ) : (
-                        <Button
-                          size="sm"
-                          variant="outline"
-                          className="h-6 gap-1.5 px-2 !text-[11px]"
-                          disabled={
-                            applyToSourcePending ||
-                            !activeLocalhostSourceWriteContent
-                          }
-                          title={
-                            activeLocalhostSourceWriteContent
-                              ? undefined
-                              : NO_LOCALHOST_WRITE_CONTENT_MESSAGE
-                          }
-                          onClick={handleApplyToSource}
-                        >
-                          <IconDeviceFloppy className="size-3 shrink-0" />
-                          {applyToSourcePending
-                            ? t("designEditor.writingToSource")
-                            : activeLocalhostRelPath
-                              ? t("designEditor.applyToSourcePath", {
-                                  path: activeLocalhostRelPath,
-                                })
-                              : t("designEditor.applyToSource")}
-                        </Button>
-                      )}
-                    </div>
-                  )}
                 {/* §6.4 / BP-DEEP v2 — breakpoint targeting no longer
                     renders any bar over or above the canvas (the earlier
                     floating overlay covered screen headers; the chrome-row
@@ -25863,6 +27875,8 @@ ${serializedHtml}
                         cameraCommand={cameraCommand}
                         activeId={activeFileId}
                         selectedScreenIds={overviewSelectedScreenIds}
+                        hiddenScreenIds={hiddenLayerIds}
+                        lockedScreenIds={lockedLayerIds}
                         fullViewScreenIds={fullViewScreenIds}
                         activeScreenHasHoveredChild={
                           Boolean(hoveredElement) &&
@@ -26040,6 +28054,7 @@ ${serializedHtml}
                   ) : (
                     <>
                       <DesignCanvas
+                        screenId={activeFile.id}
                         content={activeContent}
                         contentKey={`${activeFile.id}:${contentRenderRevision}`}
                         styleRevertRequest={
@@ -26078,6 +28093,12 @@ ${serializedHtml}
                               }
                             : null
                         }
+                        runtimeStructureMoveRequest={
+                          runtimeStructureMoveRequest?.screenId ===
+                          activeFile.id
+                            ? runtimeStructureMoveRequest
+                            : null
+                        }
                         zoom={zoom}
                         onZoomChange={setZoom}
                         deviceFrame={deviceFrame}
@@ -26092,6 +28113,15 @@ ${serializedHtml}
                             snapshot,
                           );
                         }}
+                        onRuntimeLayerSnapshot={
+                          shouldUseRuntimeLayerProjection({
+                            screen: activeOverviewScreen,
+                            fallbackSourceType: designSourceType,
+                            content: activeContent,
+                          })
+                            ? handleActiveRuntimeLayerSnapshot
+                            : undefined
+                        }
                         fusionUrl={designFusionUrl}
                         previewWidthPx={activeBreakpointWidthState}
                         shaderFillPreview={shaderFillPreview}
@@ -26160,11 +28190,13 @@ ${serializedHtml}
                         tweakValues={cssVarValues}
                         drawMode={drawMode}
                         onExitDrawMode={() => {
-                          setDrawMode(false);
-                          setPinMode(false);
-                          setActiveTool("move");
-                          setMode("edit");
+                          handleExitFocusedDrawMode();
                         }}
+                        drawOverlayResetSignal={focusedAnnotationResetSignal}
+                        retainDrawOverlayWhenHidden
+                        onAnnotationSendingChange={
+                          handleFocusedAnnotationSendingChange
+                        }
                         pinMode={pinMode}
                         commentPinsHidden={commentsHidden}
                         onExitPinMode={() => {
@@ -26232,6 +28264,23 @@ ${serializedHtml}
                       )}
                     </>
                   )}
+                  {/* This overview annotation overlay is deliberately outside
+                      the overview/single subtree. Entering a focused screen
+                      hides it without unmounting it, so board-wide work is
+                      still available when the user returns. Its reset signal
+                      is separate from DesignCanvas's focused-screen batch. */}
+                  <SharedDrawOverlay
+                    visible={
+                      viewMode === "overview" && drawMode && mode === "annotate"
+                    }
+                    clearSignal={overviewAnnotationResetSignal}
+                    scopeKey="overview"
+                    retainSurfaceWhenHidden
+                    zoom={100}
+                    onClose={handleExitOverviewDrawMode}
+                    onSend={handleSendOverviewAnnotations}
+                    sending={overviewAnnotationSending}
+                  />
                 </div>
               </div>
             ) : (
@@ -26350,6 +28399,7 @@ ${serializedHtml}
                   tweakValues={tweakSelections}
                   activeContent={activeContent}
                   activeFileUpdatedAt={activeFile?.updatedAt ?? null}
+                  componentSwapPickerRequest={componentSwapPickerRequest}
                   onComponentPropApplied={handleComponentPropApplied}
                   onTweakChange={handleTweakChange}
                   onRequestTweaks={handleRequestTweaks}
diff --git a/templates/design/app/pages/DesignEditor.zoom.test.ts b/templates/design/app/pages/DesignEditor.zoom.test.ts
index 6cce5fe098..45d649b122 100644
--- a/templates/design/app/pages/DesignEditor.zoom.test.ts
+++ b/templates/design/app/pages/DesignEditor.zoom.test.ts
@@ -4,6 +4,8 @@ import {
   clampOverviewDisplayZoom,
   clampZoom,
   computeFitCameraForFrames,
+  computeIframeLocalCanvasPoint,
+  readOverviewZoomPercentFromTransform,
   DEFAULT_OVERVIEW_ZOOM,
   getAllScreenFrameEntries,
   getNextZoomStepDown,
@@ -127,15 +129,29 @@ describe("getAllScreenFrameEntries", () => {
     expect(Number.isFinite(b.geometry.y)).toBe(true);
   });
 
-  it("includes the board frame when provided and not already a screen", () => {
+  it("includes actual board content bounds when provided and not already a screen", () => {
     const entries = getAllScreenFrameEntries({
       overviewScreens: [],
       canvasFrameGeometryById: {},
       boardFileId: "board-1",
-      boardFrameGeometry: { x: -1000, y: -1000, width: 2000, height: 2000 },
+      boardContentBounds: { x: 120, y: 80, width: 240, height: 160 },
     });
     expect(entries).toHaveLength(1);
-    expect(entries[0]!.id).toBe("board-1");
+    expect(entries[0]).toEqual({
+      id: "board-1",
+      geometry: { x: 120, y: 80, width: 240, height: 160 },
+    });
+  });
+
+  it("does not include an empty board in fit or placement entries", () => {
+    expect(
+      getAllScreenFrameEntries({
+        overviewScreens: [],
+        canvasFrameGeometryById: {},
+        boardFileId: "board-1",
+        boardContentBounds: null,
+      }),
+    ).toEqual([]);
   });
 
   it("returns an empty list for no screens and no board", () => {
@@ -554,3 +570,88 @@ describe("computeFitCameraForFrames", () => {
     expect(camera!.zoom).toBeLessThanOrEqual(25600);
   });
 });
+
+describe("computeIframeLocalCanvasPoint — PASTE-HERE-IN-CONTENT", () => {
+  // handleIframeContextMenu opens the canvas context menu imperatively via a
+  // ref, bypassing CanvasContextMenu's own onContextMenuCapture (the only
+  // place that normally attaches canvasX/canvasY to the menu's point). This
+  // is the shared math both paths now use so "Paste here" lands under the
+  // cursor whether the right-click hit the canvas background or actual
+  // rendered screen content.
+  it("converts a viewport point to iframe-local document coordinates at 100% zoom", () => {
+    expect(
+      computeIframeLocalCanvasPoint({
+        clientX: 150,
+        clientY: 220,
+        iframeRect: { left: 50, top: 100 },
+        zoomPercent: 100,
+      }),
+    ).toEqual({ x: 100, y: 120 });
+  });
+
+  it("divides by the zoom factor so a zoomed-out iframe still maps to the correct document point", () => {
+    // 50% zoom means 1 document px renders as 0.5 screen px, so a 100px
+    // on-screen offset from the iframe's origin is 200 document px.
+    expect(
+      computeIframeLocalCanvasPoint({
+        clientX: 150,
+        clientY: 100,
+        iframeRect: { left: 50, top: 50 },
+        zoomPercent: 50,
+      }),
+    ).toEqual({ x: 200, y: 100 });
+  });
+
+  it("clamps negative offsets (click above/left of the iframe origin) to zero", () => {
+    expect(
+      computeIframeLocalCanvasPoint({
+        clientX: 10,
+        clientY: 10,
+        iframeRect: { left: 50, top: 50 },
+        zoomPercent: 100,
+      }),
+    ).toEqual({ x: 0, y: 0 });
+  });
+
+  it("returns null when there is no iframe rect to measure against", () => {
+    expect(
+      computeIframeLocalCanvasPoint({
+        clientX: 10,
+        clientY: 10,
+        iframeRect: null,
+        zoomPercent: 100,
+      }),
+    ).toBeNull();
+  });
+
+  it("returns null for a non-positive zoom percent instead of dividing by zero", () => {
+    expect(
+      computeIframeLocalCanvasPoint({
+        clientX: 10,
+        clientY: 10,
+        iframeRect: { left: 0, top: 0 },
+        zoomPercent: 0,
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("readOverviewZoomPercentFromTransform", () => {
+  it("reads the live scale written during an unsettled overview gesture", () => {
+    expect(
+      readOverviewZoomPercentFromTransform(
+        "translate(42px, -18px) scale(0.375)",
+        100,
+      ),
+    ).toBe(37.5);
+  });
+
+  it("falls back for missing, malformed, zero, or negative scales", () => {
+    expect(readOverviewZoomPercentFromTransform("", 64)).toBe(64);
+    expect(
+      readOverviewZoomPercentFromTransform("translate(1px, 2px)", 64),
+    ).toBe(64);
+    expect(readOverviewZoomPercentFromTransform("scale(0)", 64)).toBe(64);
+    expect(readOverviewZoomPercentFromTransform("scale(-2)", 64)).toBe(64);
+  });
+});
diff --git a/templates/design/app/pages/design-editor/alpine-inline-pilot.spec.ts b/templates/design/app/pages/design-editor/alpine-inline-pilot.spec.ts
new file mode 100644
index 0000000000..bdf5ac0315
--- /dev/null
+++ b/templates/design/app/pages/design-editor/alpine-inline-pilot.spec.ts
@@ -0,0 +1,242 @@
+import {
+  applyVisualEdit,
+  buildCodeLayerProjection,
+  buildCodeLayerTree,
+  ensureCodeLayerNodeIdsInHtml,
+  moveNodeBetweenDocuments,
+} from "@shared/code-layer";
+import { describe, expect, it } from "vitest";
+
+import {
+  collectCodeLayerAncestors,
+  findCodeLayerSiblingOrder,
+} from "./code-layer-state";
+
+const ALPINE_PILOT_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Alpine design pilot</title>
+  </head>
+  <body>
+    <main data-agent-native-layer-name="App shell" x-data="{ open: true, count: 0 }">
+      <nav data-agent-native-layer-name="Actions">
+        <button data-agent-native-layer-name="Primary action" @click="count++" :class="{ 'is-active': count > 0 }">Create</button>
+        <button data-agent-native-layer-name="Secondary action" @click="open = !open">Toggle</button>
+      </nav>
+      <section data-agent-native-layer-name="Card" x-show="open">
+        <h2 data-agent-native-layer-name="Card title">Project alpha</h2>
+        <p data-agent-native-layer-name="Card body" x-text="\`Count: \${count}\`">Count: 0</p>
+      </section>
+      <section data-agent-native-layer-name="Drop zone"></section>
+      <div data-agent-native-layer-name="Floating badge" style="position: absolute; left: 24px; top: 32px; color: rgb(12, 18, 28)">New</div>
+    </main>
+    <script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js" defer></script>
+  </body>
+</html>`;
+
+function nodeByName(html: string, name: string) {
+  const node = buildCodeLayerProjection(html).nodes.find(
+    (candidate) => candidate.layerName === name,
+  );
+  expect(node, `expected layer named ${name}`).toBeTruthy();
+  return node!;
+}
+
+function attrIdByName(html: string, name: string) {
+  const id = nodeByName(html, name).dataAttributes["data-agent-native-node-id"];
+  expect(id, `expected stable id for ${name}`).toBeTruthy();
+  return id!;
+}
+
+function latest(items: readonly string[]) {
+  return items[items.length - 1]!;
+}
+
+describe("net-new HTML/Alpine visual-edit pilot", () => {
+  it("keeps every source-backed layer selectable and stable through edits, reparenting, auto layout, reload, undo, and redo", () => {
+    const stamped = ensureCodeLayerNodeIdsInHtml(ALPINE_PILOT_HTML);
+    expect(stamped.changed).toBe(true);
+
+    const initialProjection = buildCodeLayerProjection(stamped.content);
+    const meaningfulTags = initialProjection.nodes
+      .filter((node) => node.tag !== "html" && node.tag !== "body")
+      .map((node) => node.tag);
+    expect(meaningfulTags).toEqual([
+      "main",
+      "nav",
+      "button",
+      "button",
+      "section",
+      "h2",
+      "p",
+      "section",
+      "div",
+    ]);
+    expect(
+      new Set(
+        initialProjection.nodes.map(
+          (node) => node.dataAttributes["data-agent-native-node-id"],
+        ),
+      ).size,
+    ).toBe(initialProjection.nodes.length);
+
+    const initialTree = buildCodeLayerTree(initialProjection);
+    const primary = nodeByName(stamped.content, "Primary action");
+    const secondary = nodeByName(stamped.content, "Secondary action");
+    const actions = nodeByName(stamped.content, "Actions");
+    expect(findCodeLayerSiblingOrder(initialTree, primary.id)).toMatchObject({
+      siblingIds: [primary.id, secondary.id],
+      index: 0,
+      parentId: actions.id,
+    });
+    expect(collectCodeLayerAncestors(initialTree, primary.id)).toEqual([
+      nodeByName(stamped.content, "App shell").id,
+      actions.id,
+    ]);
+
+    const stableIds = Object.fromEntries(
+      initialProjection.nodes.map((node) => [
+        node.layerName,
+        node.dataAttributes["data-agent-native-node-id"],
+      ]),
+    );
+    const history = [stamped.content];
+
+    const styleEdit = applyVisualEdit(latest(history), {
+      kind: "style",
+      target: { nodeId: attrIdByName(latest(history), "Card") },
+      property: "background-color",
+      value: "rgb(250, 250, 252)",
+    });
+    expect(styleEdit.result.status).toBe("applied");
+    history.push(styleEdit.content);
+
+    const textEdit = applyVisualEdit(latest(history), {
+      kind: "textContent",
+      target: { nodeId: attrIdByName(latest(history), "Card title") },
+      value: "Project beta",
+    });
+    expect(textEdit.result.status).toBe("applied");
+    history.push(textEdit.content);
+
+    const autoLayoutEdit = applyVisualEdit(latest(history), {
+      kind: "autoLayout",
+      targetId: attrIdByName(latest(history), "Drop zone"),
+      enabled: true,
+      direction: "row",
+      gap: "12px",
+    });
+    expect(autoLayoutEdit.result.status).toBe("applied");
+    history.push(autoLayoutEdit.content);
+
+    const reparentEdit = applyVisualEdit(latest(history), {
+      kind: "moveNode",
+      target: { nodeId: attrIdByName(latest(history), "Floating badge") },
+      anchor: { nodeId: attrIdByName(latest(history), "Drop zone") },
+      placement: "inside",
+    });
+    expect(reparentEdit.result.status).toBe("applied");
+    history.push(reparentEdit.content);
+
+    const badgeAfterReparent = nodeByName(latest(history), "Floating badge");
+    const dropZoneAfterReparent = nodeByName(latest(history), "Drop zone");
+    expect(badgeAfterReparent.parentId).toBe(dropZoneAfterReparent.id);
+    expect(badgeAfterReparent.style.position).toBeUndefined();
+    expect(badgeAfterReparent.style.left).toBeUndefined();
+    expect(badgeAfterReparent.style.top).toBeUndefined();
+    expect(dropZoneAfterReparent.layout.isFlexContainer).toBe(true);
+    expect(dropZoneAfterReparent.layout.flexDirection).toBe("row");
+    expect(dropZoneAfterReparent.layout.gap).toBe("12px");
+
+    const reorderEdit = applyVisualEdit(latest(history), {
+      kind: "moveNode",
+      target: { nodeId: attrIdByName(latest(history), "Secondary action") },
+      anchor: { nodeId: attrIdByName(latest(history), "Primary action") },
+      placement: "before",
+    });
+    expect(reorderEdit.result.status).toBe("applied");
+    history.push(reorderEdit.content);
+
+    const reloadedProjection = buildCodeLayerProjection(latest(history));
+    for (const node of reloadedProjection.nodes) {
+      expect(node.dataAttributes["data-agent-native-node-id"]).toBe(
+        stableIds[node.layerName],
+      );
+    }
+    expect(latest(history)).toContain('x-data="{ open: true, count: 0 }"');
+    expect(latest(history)).toContain('x-show="open"');
+    expect(latest(history)).toContain('@click="count++"');
+    expect(latest(history)).toContain(":class=\"{ 'is-active': count > 0 }\"");
+    expect(latest(history)).toContain('x-text="`Count: ${count}`"');
+
+    const finalTree = buildCodeLayerTree(reloadedProjection);
+    const finalSecondary = nodeByName(latest(history), "Secondary action");
+    const finalPrimary = nodeByName(latest(history), "Primary action");
+    expect(
+      findCodeLayerSiblingOrder(finalTree, finalSecondary.id),
+    ).toMatchObject({
+      siblingIds: [finalSecondary.id, finalPrimary.id],
+      index: 0,
+    });
+
+    // The editor history stores full source snapshots. Undo and redo must
+    // therefore restore both structure and Alpine directives byte-for-byte.
+    const undoSnapshot = history[history.length - 2]!;
+    expect(undoSnapshot).toBe(reparentEdit.content);
+    const redoSnapshot = latest(history);
+    expect(redoSnapshot).toBe(reorderEdit.content);
+    expect(buildCodeLayerProjection(undoSnapshot).nodes).toHaveLength(
+      reloadedProjection.nodes.length,
+    );
+    expect(buildCodeLayerProjection(redoSnapshot).nodes).toHaveLength(
+      reloadedProjection.nodes.length,
+    );
+  });
+
+  it("puts a cross-screen drop into destination auto-layout flow without damaging Alpine directives", () => {
+    const source = ensureCodeLayerNodeIdsInHtml(
+      `<main><div data-agent-native-layer-name="Movable" x-data="{ enabled: true }" x-show="enabled" class="absolute md:!fixed left-20 top-10 rounded" style="position: absolute; left: 80px; top: 40px">Move me</div></main>`,
+    ).content;
+    const destination = ensureCodeLayerNodeIdsInHtml(
+      `<main><section data-agent-native-layer-name="Destination" style="display: flex; flex-direction: column; gap: 8px"><button @click="saved = true">Existing</button></section></main>`,
+    ).content;
+
+    const result = moveNodeBetweenDocuments(source, destination, {
+      nodeId: attrIdByName(source, "Movable"),
+      anchorNodeId: attrIdByName(destination, "Existing"),
+      placement: "before",
+    });
+
+    expect(result.status).toBe("applied");
+    expect(result.sourceHtml).not.toContain("Move me");
+    expect(result.destHtml).toContain('x-data="{ enabled: true }"');
+    expect(result.destHtml).toContain('x-show="enabled"');
+    expect(result.destHtml).toContain('@click="saved = true"');
+    const moved = nodeByName(result.destHtml, "Movable");
+    expect(moved.style.position).toBeUndefined();
+    expect(moved.style.left).toBeUndefined();
+    expect(moved.style.top).toBeUndefined();
+    expect(moved.classes).toEqual(["left-20", "top-10", "rounded"]);
+    expect(moved.parentId).toBe(nodeByName(result.destHtml, "Destination").id);
+  });
+
+  it("preserves an intentional absolute Auto layout child while reordering siblings", () => {
+    const html = ensureCodeLayerNodeIdsInHtml(
+      `<section data-agent-native-layer-name="Layout" style="display: flex; gap: 8px"><div data-agent-native-layer-name="Pinned" style="position: absolute; right: 4px; top: 4px">Pinned</div><div data-agent-native-layer-name="Flow child">Flow</div></section>`,
+    ).content;
+
+    const reordered = applyVisualEdit(html, {
+      kind: "moveNode",
+      target: { nodeId: attrIdByName(html, "Pinned") },
+      anchor: { nodeId: attrIdByName(html, "Flow child") },
+      placement: "after",
+    });
+
+    expect(reordered.result.status).toBe("applied");
+    const pinned = nodeByName(reordered.content, "Pinned");
+    expect(pinned.style.position).toBe("absolute");
+    expect(pinned.style.right).toBe("4px");
+    expect(pinned.style.top).toBe("4px");
+  });
+});
diff --git a/templates/design/app/pages/design-editor/code-layer-state.spec.ts b/templates/design/app/pages/design-editor/code-layer-state.spec.ts
new file mode 100644
index 0000000000..08d6317d03
--- /dev/null
+++ b/templates/design/app/pages/design-editor/code-layer-state.spec.ts
@@ -0,0 +1,373 @@
+import type { CodeLayerNode } from "@shared/code-layer";
+import { describe, expect, it } from "vitest";
+
+import type { ElementInfo } from "@/components/design/types";
+
+import {
+  codeLayerNodeMatchesBridgeTarget,
+  elementInfoFromCodeLayerNode,
+  refreshedBoundingRectSize,
+  refreshedComputedStyles,
+  resolveCodeLayerNodeFromBridge,
+} from "./code-layer-state";
+
+function makeElementInfo(overrides: Partial<ElementInfo> = {}): ElementInfo {
+  return {
+    tagName: "div",
+    classes: [],
+    computedStyles: {},
+    boundingRect: { x: 0, y: 0, width: 0, height: 0 },
+    isFlexChild: false,
+    isFlexContainer: false,
+    ...overrides,
+  };
+}
+
+function makeNode(overrides: Partial<CodeLayerNode> = {}): CodeLayerNode {
+  const selector = overrides.selector ?? "div";
+  return {
+    id: overrides.id ?? "node-1",
+    tag: overrides.tag ?? "div",
+    layerName: overrides.layerName ?? "Div",
+    layerNameSource: overrides.layerNameSource ?? "tag",
+    selector,
+    selectors: overrides.selectors ?? [selector],
+    path: overrides.path ?? selector,
+    attributes: overrides.attributes ?? {},
+    dataAttributes: overrides.dataAttributes ?? {},
+    classes: overrides.classes ?? [],
+    textSnippet: overrides.textSnippet ?? null,
+    style: overrides.style ?? {},
+    styleTokens: overrides.styleTokens ?? [],
+    parentId: overrides.parentId,
+    children: overrides.children ?? [],
+    layout: overrides.layout ?? {
+      siblingIndex: 0,
+      nthOfType: 1,
+      isFlexContainer: false,
+      isGridContainer: false,
+    },
+    capabilities: overrides.capabilities ?? [],
+    confidence: overrides.confidence ?? 1,
+    source: overrides.source ?? null,
+    componentInstance: overrides.componentInstance,
+  };
+}
+
+describe("elementInfoFromCodeLayerNode provenance", () => {
+  it("preserves exact React source anchors from runtime projection attributes", () => {
+    const info = elementInfoFromCodeLayerNode(
+      makeNode({
+        dataAttributes: {
+          "data-source-file": " app/components/Card.tsx ",
+          "data-source-line": "18",
+          "data-source-column": "7",
+          "data-component-name": " Card ",
+        },
+      }),
+    );
+
+    expect(info.provenance).toEqual({
+      sourceFile: "app/components/Card.tsx",
+      line: 18,
+      column: 7,
+      component: "Card",
+    });
+  });
+
+  it.each(["0", "-1", "1.5", "1e2", "NaN", "9007199254740992"])(
+    "omits non-positive or non-integer source coordinate %s",
+    (coordinate) => {
+      const info = elementInfoFromCodeLayerNode(
+        makeNode({
+          dataAttributes: {
+            "data-source-file": "app/Card.tsx",
+            "data-source-line": coordinate,
+            "data-source-column": coordinate,
+          },
+        }),
+      );
+
+      expect(info.provenance).toEqual({ sourceFile: "app/Card.tsx" });
+    },
+  );
+
+  it("accepts zero-padded positive integer source coordinates", () => {
+    const info = elementInfoFromCodeLayerNode(
+      makeNode({
+        dataAttributes: {
+          "data-source-line": "0012",
+          "data-source-column": "0003",
+        },
+      }),
+    );
+
+    expect(info.provenance).toEqual({ line: 12, column: 3 });
+  });
+
+  it("omits provenance entirely when no source attribute has a usable value", () => {
+    const info = elementInfoFromCodeLayerNode(
+      makeNode({
+        dataAttributes: {
+          "data-source-file": "  ",
+          "data-source-line": "0",
+          "data-source-column": "not-a-number",
+          "data-component-name": "  ",
+        },
+      }),
+    );
+
+    expect(info.provenance).toBeUndefined();
+  });
+});
+
+describe("resolveCodeLayerNodeFromBridge", () => {
+  it("resolves a unique sourceId match regardless of selector", () => {
+    const target = makeNode({
+      id: "target",
+      dataAttributes: { "data-agent-native-node-id": "target" },
+    });
+    const other = makeNode({ id: "other" });
+    const projection = { nodes: [other, target] };
+
+    const resolved = resolveCodeLayerNodeFromBridge(
+      projection,
+      "body > div",
+      "target",
+    );
+
+    expect(resolved).toBe(target);
+  });
+
+  it("finds the sourceId match even when an unrelated earlier node matches the selector first", () => {
+    // Regression: the old implementation was a single combined `.find()`
+    // over (selector OR sourceId), so a selector-only match earlier in the
+    // array could win over the correct sourceId match later in the array.
+    const selectorMatchButWrongNode = makeNode({
+      id: "decoy",
+      selector: "body > div",
+      selectors: ["body > div"],
+      path: "body > div",
+    });
+    const realTarget = makeNode({
+      id: "target",
+      selector: "body > div",
+      selectors: ["body > div"],
+      path: "body > div",
+      dataAttributes: { "data-agent-native-node-id": "target" },
+    });
+    const projection = { nodes: [selectorMatchButWrongNode, realTarget] };
+
+    const resolved = resolveCodeLayerNodeFromBridge(
+      projection,
+      "body > div",
+      "target",
+    );
+
+    expect(resolved).toBe(realTarget);
+  });
+
+  it("resolves a selector when it matches exactly one node", () => {
+    const target = makeNode({
+      id: "only-match",
+      selector: "ul > li:nth-of-type(3)",
+      selectors: ["ul > li:nth-of-type(3)"],
+      path: "ul > li:nth-of-type(3)",
+    });
+    const projection = { nodes: [target] };
+
+    const resolved = resolveCodeLayerNodeFromBridge(
+      projection,
+      "ul > li:nth-of-type(3)",
+    );
+
+    expect(resolved).toBe(target);
+  });
+
+  it("refuses to resolve (returns null) when a selector matches multiple nodes and no sourceId disambiguates", () => {
+    // Two repeated card instances share the same generic suffix selector —
+    // exactly the shape a bridge target for a not-yet-stamped repeated
+    // list/card item emits. Silently picking the first would risk mutating
+    // the wrong sibling; the resolver must fail closed instead, mirroring
+    // the server-side resolveTarget's ambiguity-conflict discipline.
+    const cardA = makeNode({
+      id: "card-a",
+      selector: "div > p",
+      selectors: ["div > p"],
+      path: "div > p",
+    });
+    const cardB = makeNode({
+      id: "card-b",
+      selector: "div > p",
+      selectors: ["div > p"],
+      path: "div > p",
+    });
+    const projection = { nodes: [cardA, cardB] };
+
+    const resolved = resolveCodeLayerNodeFromBridge(projection, "div > p");
+
+    expect(resolved).toBeNull();
+  });
+
+  it("returns null when neither sourceId nor selector matches anything", () => {
+    const projection = { nodes: [makeNode({ id: "unrelated" })] };
+
+    const resolved = resolveCodeLayerNodeFromBridge(
+      projection,
+      "section > article",
+      "missing-id",
+    );
+
+    expect(resolved).toBeNull();
+  });
+
+  it("falls back to the selector when sourceId is present but matches no node", () => {
+    const target = makeNode({
+      id: "only-match",
+      selector: "main > h1",
+      selectors: ["main > h1"],
+      path: "main > h1",
+    });
+    const projection = { nodes: [target] };
+
+    const resolved = resolveCodeLayerNodeFromBridge(
+      projection,
+      "main > h1",
+      "stale-pending-id-not-in-projection",
+    );
+
+    expect(resolved).toBe(target);
+  });
+});
+
+describe("codeLayerNodeMatchesBridgeTarget", () => {
+  it("matches by sourceId even when the selector does not match", () => {
+    const node = makeNode({
+      id: "target",
+      dataAttributes: { "data-agent-native-node-id": "target" },
+      selector: "div",
+      selectors: ["div"],
+      path: "div",
+    });
+
+    expect(
+      codeLayerNodeMatchesBridgeTarget(
+        node,
+        "completely > unrelated",
+        "target",
+      ),
+    ).toBe(true);
+  });
+
+  it("falls back to selector matching when sourceId does not match", () => {
+    const node = makeNode({
+      id: "node-a",
+      selector: "ul > li:nth-of-type(2)",
+      selectors: ["ul > li:nth-of-type(2)"],
+      path: "ul > li:nth-of-type(2)",
+    });
+
+    expect(
+      codeLayerNodeMatchesBridgeTarget(
+        node,
+        "ul > li:nth-of-type(2)",
+        "unrelated-id",
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false when neither sourceId nor selector matches", () => {
+    const node = makeNode({
+      id: "node-a",
+      selector: "div",
+      selectors: ["div"],
+    });
+
+    expect(
+      codeLayerNodeMatchesBridgeTarget(node, "section > p", "unrelated-id"),
+    ).toBe(false);
+  });
+});
+
+// BUG-UNDO-RESIZE-GEOMETRY regression coverage — live QA: undo after a canvas
+// drag-RESIZE reverted the DOM correctly but the right panel's Layout W/H
+// stayed stale (167x86 instead of the actually-reverted 116.8x36) until
+// deselect/reselect. Root cause: refreshElementInfoFromContent's resync
+// merged width/height additively (so a value absent from the reverted node
+// never overwrote the pre-undo one) AND never refreshed boundingRect at all,
+// which is what edit-panel/element-classification.ts's cssElementSize falls
+// back to when computedStyles has no parseable width/height.
+describe("refreshedComputedStyles geometry handling", () => {
+  it("clears a stale width/height when the fresh source no longer authors one (fail-before case)", () => {
+    // Before the fix: the additive merge below (`{...info.computedStyles,
+    // ...sourceWithAliases}`) kept `width`/`height` from `info` whenever the
+    // fresh (reverted) node didn't carry them — exactly what happened for an
+    // undo that removed the drag-resize's inline width/height, reverting to
+    // a class-driven size the string parse can't see.
+    const staleInfo = makeElementInfo({
+      computedStyles: { width: "167px", height: "86px", color: "red" },
+    });
+    const result = refreshedComputedStyles(
+      staleInfo,
+      { color: "red" }, // reverted node's inline style: no width/height
+      ["some-class"], // sourceClasses.length > 0 selects the additive-merge branch
+    );
+    expect(result.width).toBeUndefined();
+    expect(result.height).toBeUndefined();
+    // Non-geometry properties still carry over/merge normally.
+    expect(result.color).toBe("red");
+  });
+
+  it("takes the fresh width/height when the reverted source authors an explicit value", () => {
+    const staleInfo = makeElementInfo({
+      computedStyles: { width: "167px", height: "86px" },
+    });
+    const result = refreshedComputedStyles(
+      staleInfo,
+      { width: "116.8px", height: "36px" },
+      ["some-class"],
+    );
+    expect(result.width).toBe("116.8px");
+    expect(result.height).toBe("36px");
+  });
+
+  it("does not affect the no-classes (pure source) branch", () => {
+    const staleInfo = makeElementInfo({
+      computedStyles: { width: "167px", height: "86px" },
+    });
+    const result = refreshedComputedStyles(
+      staleInfo,
+      { width: "116.8px" },
+      [], // sourceClasses.length === 0 selects the pure-source branch
+    );
+    expect(result.width).toBe("116.8px");
+    expect(result.height).toBeUndefined();
+  });
+});
+
+describe("refreshedBoundingRectSize", () => {
+  it("recomputes width/height from the freshly-resolved computedStyles instead of staying pinned to the pre-undo rect (fail-before case)", () => {
+    // Before the fix: refreshElementInfoFromContent's `{...info}` spread (via
+    // canonicalElementInfoForCodeLayerNode, and again in its DOM-parse
+    // fallback) left `boundingRect` completely untouched, so cssElementSize's
+    // fallback-to-boundingRect path kept reporting the pre-undo drag-resize
+    // rect forever — this is what the Layout panel's W/H fields showed when
+    // computedStyles itself had no parseable width/height.
+    const staleInfo = makeElementInfo({
+      boundingRect: { x: 4, y: 8, width: 167, height: 86 },
+    });
+    const result = refreshedBoundingRectSize(staleInfo, {
+      width: "116.8px",
+      height: "36px",
+    });
+    expect(result).toEqual({ x: 4, y: 8, width: 116.8, height: 36 });
+  });
+
+  it("keeps the prior rect size when the fresh computedStyles has no parseable width/height", () => {
+    const staleInfo = makeElementInfo({
+      boundingRect: { x: 4, y: 8, width: 167, height: 86 },
+    });
+    const result = refreshedBoundingRectSize(staleInfo, {});
+    expect(result).toEqual({ x: 4, y: 8, width: 167, height: 86 });
+  });
+});
diff --git a/templates/design/app/pages/design-editor/code-layer-state.ts b/templates/design/app/pages/design-editor/code-layer-state.ts
index f07bdec79b..50775b16b0 100644
--- a/templates/design/app/pages/design-editor/code-layer-state.ts
+++ b/templates/design/app/pages/design-editor/code-layer-state.ts
@@ -306,11 +306,41 @@ export function bridgeSourceIdForCodeLayerNode(node: CodeLayerNode): string {
   );
 }
 
+function positiveIntegerDataAttribute(
+  value: string | undefined,
+): number | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed || !/^\d+$/.test(trimmed)) return undefined;
+  const parsed = Number(trimmed);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function provenanceForCodeLayerNode(
+  node: CodeLayerNode,
+): ElementInfo["provenance"] {
+  const sourceFile = node.dataAttributes["data-source-file"]?.trim();
+  const line = positiveIntegerDataAttribute(
+    node.dataAttributes["data-source-line"],
+  );
+  const column = positiveIntegerDataAttribute(
+    node.dataAttributes["data-source-column"],
+  );
+  const component = node.dataAttributes["data-component-name"]?.trim();
+  if (!sourceFile && !line && !column && !component) return undefined;
+  return {
+    ...(sourceFile ? { sourceFile } : {}),
+    ...(line ? { line } : {}),
+    ...(column ? { column } : {}),
+    ...(component ? { component } : {}),
+  };
+}
+
 export function elementInfoFromCodeLayerNode(node: CodeLayerNode): ElementInfo {
   return {
     tagName: node.tag,
     id: typeof node.attributes.id === "string" ? node.attributes.id : undefined,
     sourceId: bridgeSourceIdForCodeLayerNode(node),
+    provenance: provenanceForCodeLayerNode(node),
     selector: preferredCodeLayerSelector(node),
     classes: node.classes,
     computedStyles: Object.fromEntries(
@@ -347,15 +377,83 @@ export function cssStyleAliases(
   return result;
 }
 
+// BUG-UNDO-RESIZE-GEOMETRY: width/height are the two computedStyles keys the
+// Layout panel's W/H fields actually read (edit-panel/element-classification.ts's
+// cssElementSize parses element.computedStyles.width/height first, falling
+// back to boundingRect only when that's missing/unparseable). Every other
+// computedStyles property is fine to carry over additively when the fresh
+// (reverted/replayed) source doesn't mention it — most style properties come
+// from a CSS class the string-parse can't see, so keeping the previously
+// known value is the right default. Width/height are different: an undo or
+// redo of a resize commit is EXACTLY a change to (or removal of) an inline
+// width/height, so a stale carried-over value here isn't just incomplete —
+// it's actively wrong (it's the pre-undo/pre-redo box size).
+const GEOMETRY_STYLE_PROPERTIES = ["width", "height"] as const;
+
 export function refreshedComputedStyles(
   info: ElementInfo,
   sourceStyles: Record<string, string>,
   sourceClasses: readonly string[],
 ): Record<string, string> {
   const sourceWithAliases = cssStyleAliases(sourceStyles);
-  return sourceClasses.length > 0
-    ? { ...info.computedStyles, ...sourceWithAliases }
-    : sourceWithAliases;
+  const merged: Record<string, string> =
+    sourceClasses.length > 0
+      ? { ...info.computedStyles, ...sourceWithAliases }
+      : { ...sourceWithAliases };
+  GEOMETRY_STYLE_PROPERTIES.forEach((property) => {
+    if (!(property in sourceWithAliases)) delete merged[property];
+  });
+  return merged;
+}
+
+/**
+ * Companion to `refreshedComputedStyles` for the same undo/redo/remote-sync
+ * resync path — `ElementInfo.boundingRect` is otherwise left completely
+ * untouched by `refreshElementInfoFromContent` (both its node-match branch,
+ * via `canonicalElementInfoForCodeLayerNode`'s `{...info}` spread, and its
+ * DOM-parse fallback, via its own `{...info}` spread), so it keeps showing
+ * whatever rect was live-measured before the content change. `cssElementSize`
+ * falls back to `boundingRect.width`/`height` whenever computedStyles has no
+ * parseable value for that axis, so a permanently-stale boundingRect can
+ * still surface the pre-undo/redo size even after `refreshedComputedStyles`
+ * is fixed. Reuses the SAME freshly-resolved computedStyles (already merged
+ * above) so both fields agree, instead of re-deriving from a different
+ * source.
+ *
+ * Exported for unit testing.
+ */
+export function refreshedBoundingRectSize(
+  info: ElementInfo,
+  computedStyles: Record<string, string>,
+): ElementInfo["boundingRect"] {
+  const parsedWidth = parseFloat(computedStyles.width ?? "");
+  const parsedHeight = parseFloat(computedStyles.height ?? "");
+  return {
+    ...info.boundingRect,
+    width:
+      Number.isFinite(parsedWidth) && parsedWidth >= 0
+        ? parsedWidth
+        : info.boundingRect.width,
+    height:
+      Number.isFinite(parsedHeight) && parsedHeight >= 0
+        ? parsedHeight
+        : info.boundingRect.height,
+  };
+}
+
+function codeLayerNodeMatchesSourceId(
+  node: CodeLayerNode,
+  sourceId: string,
+): boolean {
+  return (
+    node.id === sourceId ||
+    node.dataAttributes["data-agent-native-node-id"] === sourceId ||
+    node.dataAttributes["data-code-layer-id"] === sourceId ||
+    node.dataAttributes["data-layer-id"] === sourceId ||
+    node.dataAttributes["data-builder-id"] === sourceId ||
+    node.dataAttributes["data-loc"] === sourceId ||
+    node.attributes.id === sourceId
+  );
 }
 
 export function codeLayerNodeMatchesBridgeTarget(
@@ -363,19 +461,7 @@ export function codeLayerNodeMatchesBridgeTarget(
   selector?: string,
   sourceId?: string,
 ): boolean {
-  if (sourceId) {
-    if (node.id === sourceId) return true;
-    if (
-      node.dataAttributes["data-agent-native-node-id"] === sourceId ||
-      node.dataAttributes["data-code-layer-id"] === sourceId ||
-      node.dataAttributes["data-layer-id"] === sourceId ||
-      node.dataAttributes["data-builder-id"] === sourceId ||
-      node.dataAttributes["data-loc"] === sourceId ||
-      node.attributes.id === sourceId
-    ) {
-      return true;
-    }
-  }
+  if (sourceId && codeLayerNodeMatchesSourceId(node, sourceId)) return true;
   return codeLayerSelectorMatches(node, selector);
 }
 
@@ -384,11 +470,34 @@ export function resolveCodeLayerNodeFromBridge(
   selector?: string,
   sourceId?: string,
 ): CodeLayerNode | null {
-  return (
-    projection.nodes.find((node) =>
-      codeLayerNodeMatchesBridgeTarget(node, selector, sourceId),
-    ) ?? null
+  // Id-based match first, across the WHOLE projection (not just up to
+  // whichever node the old combined-predicate `.find()` reached first) — a
+  // sourceId identifies one node by its own stable id/data-attribute, which
+  // is unique in a well-formed projection, so this branch alone can never be
+  // ambiguous. Checking it before the selector fallback also fixes a subtler
+  // pre-existing bug: the old single-pass `.find()` could match an EARLIER
+  // node purely by selector before ever reaching the correct sourceId match
+  // later in iteration order.
+  if (sourceId) {
+    const idMatch = projection.nodes.find((node) =>
+      codeLayerNodeMatchesSourceId(node, sourceId),
+    );
+    if (idMatch) return idMatch;
+  }
+  // No sourceId (or no node carries it yet, e.g. a bridge target minted a
+  // fresh pending id the projection hasn't picked up) — fall back to the
+  // bridge's structural selector. Unlike an id, a generic short selector
+  // (e.g. a 2-segment "div > p" suffix path) can legitimately match several
+  // repeated list/card/row instances. The server-side resolver for the same
+  // problem (code-layer.ts's resolveTarget) explicitly refuses to resolve a
+  // selector that matches more than one node rather than silently picking
+  // the first DOM-order match — mirror that discipline here so a duplicate/
+  // move/style edit can never silently land on the wrong sibling instance.
+  if (!selector) return null;
+  const selectorMatches = projection.nodes.filter((node) =>
+    codeLayerSelectorMatches(node, selector),
   );
+  return selectorMatches.length === 1 ? selectorMatches[0]! : null;
 }
 
 export function collapsedElementText(value: string | null | undefined): string {
@@ -606,13 +715,15 @@ export function refreshElementInfoFromContent(
     );
   if (node) {
     const sourceInfo = elementInfoFromCodeLayerNode(node);
+    const computedStyles = refreshedComputedStyles(
+      info,
+      sourceInfo.computedStyles,
+      sourceInfo.classes,
+    );
     return {
       ...canonicalElementInfoForCodeLayerNode(info, node),
-      computedStyles: refreshedComputedStyles(
-        info,
-        sourceInfo.computedStyles,
-        sourceInfo.classes,
-      ),
+      computedStyles,
+      boundingRect: refreshedBoundingRectSize(info, computedStyles),
       textContent: sourceInfo.textContent,
       childElementCount: sourceInfo.childElementCount,
       isFlexChild: sourceInfo.isFlexChild,
@@ -626,14 +737,16 @@ export function refreshElementInfoFromContent(
     const element = queryUniqueSelector(doc, info.selector);
     if (!element) return null;
     const classes = Array.from(element.classList);
+    const computedStyles = refreshedComputedStyles(
+      info,
+      parseInlineStyleAttribute(element.getAttribute("style")),
+      classes,
+    );
     return {
       ...info,
       classes,
-      computedStyles: refreshedComputedStyles(
-        info,
-        parseInlineStyleAttribute(element.getAttribute("style")),
-        classes,
-      ),
+      computedStyles,
+      boundingRect: refreshedBoundingRectSize(info, computedStyles),
       textContent: element.textContent?.slice(0, 200) ?? info.textContent,
       childElementCount: element.children.length,
     };
diff --git a/templates/design/app/pages/design-editor/collab-sync.ts b/templates/design/app/pages/design-editor/collab-sync.ts
index 6a23b7e96c..b0930433e3 100644
--- a/templates/design/app/pages/design-editor/collab-sync.ts
+++ b/templates/design/app/pages/design-editor/collab-sync.ts
@@ -41,3 +41,18 @@ export function resolveScreenCollabSyncTarget({
     overviewDocConnected && overviewPresenceFileId === fileId;
   return { writeLiveDoc, syncCollab: !writeLiveDoc };
 }
+
+/** A local transaction already updated the preview optimistically, and a
+ * same-content remote transaction is only an acknowledgement echo. Only a
+ * genuinely different remote snapshot should touch the live document. */
+export function shouldApplyRemotePreviewContent({
+  isLocalEdit,
+  previousContent,
+  nextContent,
+}: {
+  isLocalEdit: boolean;
+  previousContent: string | null;
+  nextContent: string;
+}): boolean {
+  return !isLocalEdit && nextContent !== previousContent;
+}
diff --git a/templates/design/app/pages/design-editor/editor-session.ts b/templates/design/app/pages/design-editor/editor-session.ts
index 519af66807..8513597e9d 100644
--- a/templates/design/app/pages/design-editor/editor-session.ts
+++ b/templates/design/app/pages/design-editor/editor-session.ts
@@ -18,3 +18,36 @@ export function createEditorSaveOperationSource(
 
 /** Yjs origin tracked by the local undo manager. */
 export const LOCAL_EDIT_ORIGIN = `${TAB_ID}:local`;
+
+/**
+ * TIE-BREAK: decides whether polled DB content should be adopted into the
+ * live editor during the file-content reconcile effect (DesignEditor.tsx).
+ * Callers only reach this decision once BOTH of the effect's own
+ * "already reflecting this exact content" early-returns have already ruled
+ * out `dbContent` matching what's currently rendered — so every call here
+ * represents a genuine content difference.
+ *
+ * A strict `dbUpdatedAt > applied` used to be the only "is this newer"
+ * check, which silently DROPPED a real external write whenever it landed in
+ * the same millisecond as the previously-applied one (timestamp
+ * resolution) — the tie was never treated as "newer," so the second write's
+ * content just never rendered. That's only safe to fix by treating a tie as
+ * adoptable while `agentActive` is false: when the agent IS active, a tied
+ * timestamp with different content is more likely a live self-echo race
+ * (the agent's own Yjs-tracked edit still mid-flight), which the caller's
+ * `staleAgentEchoPossible` debounced recovery timer already handles
+ * separately and more carefully — forcing immediate adoption for that case
+ * too would skip the debounce and reintroduce the exact race it exists to
+ * prevent.
+ */
+export function shouldAdoptExternalReconcileContent(args: {
+  appliedUpdatedAt: string | null | undefined;
+  dbUpdatedAt: string | null | undefined;
+  agentActive: boolean;
+}): boolean {
+  const { appliedUpdatedAt, dbUpdatedAt, agentActive } = args;
+  if (!appliedUpdatedAt) return true;
+  if (!dbUpdatedAt) return false;
+  if (dbUpdatedAt > appliedUpdatedAt) return true;
+  return dbUpdatedAt === appliedUpdatedAt && !agentActive;
+}
diff --git a/templates/design/app/pages/design-editor/editor-state.textDecorationToggle.spec.ts b/templates/design/app/pages/design-editor/editor-state.textDecorationToggle.spec.ts
new file mode 100644
index 0000000000..5a1ccc69c9
--- /dev/null
+++ b/templates/design/app/pages/design-editor/editor-state.textDecorationToggle.spec.ts
@@ -0,0 +1,144 @@
+/**
+ * editor-state.textDecorationToggle.spec.ts
+ *
+ * BUG-DOUBLE-TOGGLE-RACE — a second Cmd+U (toggle underline) press within
+ * ~1s of the first silently no-ops instead of removing the underline.
+ *
+ * Root cause: commitVisualStyles commits Cmd+U/Cmd+Shift+X through the
+ * SHORTHAND "textDecoration" property, but its synchronous optimistic patch
+ * to selectedElement.computedStyles only merges the exact key(s) it
+ * committed ("textDecoration") — it never decomposes that shorthand into the
+ * LONGHAND "textDecorationLine" the toggle handler reads to decide its next
+ * value. `computedStyles.textDecorationLine` only catches up once the
+ * bridge's async getComputedStyle round trip lands. A second press inside
+ * that window recomputes nextTextDecorationLineValue from the STALE
+ * pre-toggle value, lands on the exact value the first press already
+ * committed, and the style-commit pipeline dedupes it as a no-op.
+ *
+ * resolveOptimisticTextDecorationLine (DesignEditor.tsx's
+ * handleToggleUnderlineHotkey/handleToggleStrikethroughHotkey now call this)
+ * fixes it by preferring a still-fresh value OUR OWN previous toggle just
+ * recorded for the SAME selected element over the possibly-stale
+ * computedStyles reading. These tests drive it together with the real
+ * (unmodified) nextTextDecorationLineValue to pin the exact double-toggle
+ * sequence QA hit — both "before" (pass plain computedStyles, no tracking —
+ * the old, buggy behavior) and "after" (thread the resolver through, the
+ * fixed behavior).
+ */
+import { describe, expect, it } from "vitest";
+
+import { nextTextDecorationLineValue } from "../../components/design/edit-panel/typography-helpers";
+import {
+  resolveOptimisticTextDecorationLine,
+  type OptimisticTextDecorationLineEntry,
+} from "./editor-state";
+
+const ELEMENT_KEY = "node-42";
+
+describe("BUG-DOUBLE-TOGGLE-RACE — Cmd+U rapid re-toggle", () => {
+  it("BEFORE FIX: reading raw (stale) computedStyles for both presses computes the same target twice", () => {
+    // Simulates the old handler: always reads selectedElement.computedStyles
+    // directly, ignoring what it just committed. computedStyles never
+    // updates between the two presses in this reproduction (the async
+    // bridge round trip hasn't landed yet), so both presses see "none".
+    const staleComputedTextDecorationLine = "none";
+
+    const firstPressTarget = nextTextDecorationLineValue(
+      staleComputedTextDecorationLine,
+      "underline",
+    );
+    const secondPressTarget = nextTextDecorationLineValue(
+      staleComputedTextDecorationLine,
+      "underline",
+    );
+
+    expect(firstPressTarget).toBe("underline");
+    // Bug reproduced: the second press computes the SAME value as the
+    // first instead of toggling it back off — a downstream no-value-change
+    // dedupe would make this a silent no-op.
+    expect(secondPressTarget).toBe(firstPressTarget);
+  });
+
+  it("AFTER FIX: the optimistic tracker makes the second press read the just-committed value and toggle back off", () => {
+    let tracked: OptimisticTextDecorationLineEntry | null = null;
+    const staleComputedTextDecorationLine = "none"; // still hasn't refreshed
+
+    // First Cmd+U press.
+    const firstCurrent = resolveOptimisticTextDecorationLine(
+      tracked,
+      ELEMENT_KEY,
+      staleComputedTextDecorationLine,
+    );
+    const firstPressTarget = nextTextDecorationLineValue(
+      firstCurrent,
+      "underline",
+    );
+    tracked = { key: ELEMENT_KEY, value: firstPressTarget };
+    expect(firstPressTarget).toBe("underline");
+
+    // Second Cmd+U press, still before computedStyles has refreshed.
+    const secondCurrent = resolveOptimisticTextDecorationLine(
+      tracked,
+      ELEMENT_KEY,
+      staleComputedTextDecorationLine,
+    );
+    const secondPressTarget = nextTextDecorationLineValue(
+      secondCurrent,
+      "underline",
+    );
+    tracked = { key: ELEMENT_KEY, value: secondPressTarget };
+
+    // Fixed: alternates back to "none" instead of repeating "underline".
+    expect(secondPressTarget).toBe("none");
+  });
+
+  it("underline and strikethrough toggles compose on the shared tracked value instead of clobbering each other", () => {
+    let tracked: OptimisticTextDecorationLineEntry | null = null;
+    const staleComputedTextDecorationLine = "none";
+
+    const afterUnderline = nextTextDecorationLineValue(
+      resolveOptimisticTextDecorationLine(
+        tracked,
+        ELEMENT_KEY,
+        staleComputedTextDecorationLine,
+      ),
+      "underline",
+    );
+    tracked = { key: ELEMENT_KEY, value: afterUnderline };
+
+    // Toggling strikethrough immediately after, still before any real
+    // computedStyles refresh, must ADD line-through alongside underline
+    // rather than reverting to just line-through.
+    const afterStrikethrough = nextTextDecorationLineValue(
+      resolveOptimisticTextDecorationLine(
+        tracked,
+        ELEMENT_KEY,
+        staleComputedTextDecorationLine,
+      ),
+      "line-through",
+    );
+    tracked = { key: ELEMENT_KEY, value: afterStrikethrough };
+
+    expect(afterStrikethrough.split(" ").sort()).toEqual(
+      ["line-through", "underline"].sort(),
+    );
+  });
+
+  it("falls back to computedStyles for a newly selected different element", () => {
+    const tracked: OptimisticTextDecorationLineEntry = {
+      key: ELEMENT_KEY,
+      value: "underline",
+    };
+    // A different element's own real computed value must win — the tracked
+    // entry belongs to the PREVIOUS selection, not this one.
+    expect(
+      resolveOptimisticTextDecorationLine(tracked, "node-99", "line-through"),
+    ).toBe("line-through");
+  });
+
+  it("falls back to computedStyles when nothing has been tracked yet", () => {
+    expect(
+      resolveOptimisticTextDecorationLine(null, ELEMENT_KEY, "underline"),
+    ).toBe("underline");
+  });
+});
diff --git a/templates/design/app/pages/design-editor/editor-state.ts b/templates/design/app/pages/design-editor/editor-state.ts
index 6f632a420b..d95b7fd7d9 100644
--- a/templates/design/app/pages/design-editor/editor-state.ts
+++ b/templates/design/app/pages/design-editor/editor-state.ts
@@ -244,6 +244,44 @@ export function shouldReplacePreviewAfterVisualStyleCommit(args: {
   return !args.runtimeApplied && !args.runtimeStyleApplied;
 }
 
+export interface OptimisticTextDecorationLineEntry {
+  key: string;
+  value: string;
+}
+
+/**
+ * BUG-DOUBLE-TOGGLE-RACE — Cmd+U (toggle underline) / Cmd+Shift+X (toggle
+ * strikethrough) commit through the SHORTHAND "textDecoration" property, but
+ * commitVisualStyles' synchronous optimistic patch to
+ * selectedElement.computedStyles only merges the exact key(s) it committed —
+ * it never decomposes "textDecoration" into the LONGHAND
+ * "textDecorationLine" the toggle reads to decide its next value.
+ * `computedStyles.textDecorationLine` only catches up once the bridge's
+ * async getComputedStyle round trip lands. A second toggle press within that
+ * window would otherwise recompute nextTextDecorationLineValue from the
+ * STALE pre-toggle value, land on the exact value the first press already
+ * committed, and get deduped as a no-op — consecutive toggles silently stop
+ * alternating.
+ *
+ * Resolves which value a toggle handler should treat as "current": a
+ * still-fresh optimistic value this same toggle family already recorded for
+ * the SAME selected element (`tracked.key === elementKey`) wins over the
+ * (possibly stale) computedStyles reading, since the async measurement that
+ * would refresh computedStyles may not have landed yet. A different/new
+ * element key (or no tracked entry) falls back to computedStyles, so newly
+ * selecting a different element always starts from ITS OWN real state.
+ */
+export function resolveOptimisticTextDecorationLine(
+  tracked: OptimisticTextDecorationLineEntry | null | undefined,
+  elementKey: string | undefined,
+  computedTextDecorationLine: string | undefined,
+): string | undefined {
+  if (tracked && elementKey !== undefined && tracked.key === elementKey) {
+    return tracked.value;
+  }
+  return computedTextDecorationLine;
+}
+
 /**
  * PF12: decide whether a style change from EditPanel (ScrubInput scrub tick /
  * DesignColorPicker drag tick) should skip the expensive source commit
diff --git a/templates/design/app/pages/design-editor/overview-annotation-context.spec.ts b/templates/design/app/pages/design-editor/overview-annotation-context.spec.ts
new file mode 100644
index 0000000000..4c9137655f
--- /dev/null
+++ b/templates/design/app/pages/design-editor/overview-annotation-context.spec.ts
@@ -0,0 +1,75 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+
+import {
+  collectOverviewAnnotationViewportMap,
+  formatOverviewAnnotationMessage,
+} from "./overview-annotation-context";
+
+function rect(left: number, top: number, width: number, height: number) {
+  return {
+    left,
+    top,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect;
+}
+
+describe("overview annotation context", () => {
+  it("maps a stroke to a stable screen id/name using viewport-relative bounds", () => {
+    const container = document.createElement("div");
+    const home = document.createElement("div");
+    home.dataset.frameId = "screen-home";
+    container.append(home);
+    Object.defineProperty(container, "getBoundingClientRect", {
+      value: () => rect(100, 50, 1000, 800),
+    });
+    Object.defineProperty(home, "getBoundingClientRect", {
+      value: () => rect(220, 170, 300, 500),
+    });
+
+    const viewportMap = collectOverviewAnnotationViewportMap({
+      container,
+      screens: [{ id: "screen-home", name: "Home" }],
+      zoom: 35,
+    });
+    expect(viewportMap.screens).toEqual([
+      {
+        id: "screen-home",
+        name: "Home",
+        x: 120,
+        y: 120,
+        width: 300,
+        height: 500,
+      },
+    ]);
+
+    const message = formatOverviewAnnotationMessage({
+      designId: "design-1",
+      designTitle: "Storefront",
+      annotations: [
+        {
+          id: "stroke-1",
+          type: "path",
+          pathData: "M140.0,150.0 L180.0,190.0",
+          color: "#ef4444",
+          lineWidth: 4,
+          position: { x: 0, y: 0 },
+        },
+      ],
+      instruction: "Move this area down",
+      viewportMap,
+    });
+    expect(message).toContain(
+      "Home (screen-home): x=120.0, y=120.0, width=300.0, height=500.0",
+    );
+    expect(message).toContain("stroke regions=Home (screen-home)");
+    expect(message).toContain("35.0% zoom");
+  });
+});
diff --git a/templates/design/app/pages/design-editor/overview-annotation-context.ts b/templates/design/app/pages/design-editor/overview-annotation-context.ts
new file mode 100644
index 0000000000..f20a7d2de5
--- /dev/null
+++ b/templates/design/app/pages/design-editor/overview-annotation-context.ts
@@ -0,0 +1,157 @@
+import type { DrawAnnotation } from "@/components/visual-editor/DrawOverlay";
+
+export interface OverviewAnnotationScreen {
+  id: string;
+  name: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface OverviewAnnotationViewportMap {
+  width: number;
+  height: number;
+  zoom: number;
+  screens: OverviewAnnotationScreen[];
+  board?: { x: number; y: number; width: number; height: number };
+}
+
+function escapeSelector(value: string) {
+  return typeof CSS !== "undefined" && typeof CSS.escape === "function"
+    ? CSS.escape(value)
+    : value.replace(/["\\]/g, "\\$&");
+}
+
+export function collectOverviewAnnotationViewportMap({
+  container,
+  screens,
+  zoom,
+}: {
+  container: HTMLElement;
+  screens: readonly { id: string; name: string }[];
+  zoom: number;
+}): OverviewAnnotationViewportMap {
+  const containerRect = container.getBoundingClientRect();
+  const relativeRect = (rect: DOMRect) => ({
+    x: rect.left - containerRect.left,
+    y: rect.top - containerRect.top,
+    width: rect.width,
+    height: rect.height,
+  });
+  const mappedScreens = screens.flatMap((screen) => {
+    const shell = container.querySelector<HTMLElement>(
+      `[data-frame-id="${escapeSelector(screen.id)}"]`,
+    );
+    return shell
+      ? [
+          {
+            id: screen.id,
+            name: screen.name,
+            ...relativeRect(shell.getBoundingClientRect()),
+          },
+        ]
+      : [];
+  });
+  const boardSurface = container.querySelector<HTMLElement>(
+    "[data-board-surface-layer]",
+  );
+  return {
+    width: containerRect.width,
+    height: containerRect.height,
+    zoom,
+    screens: mappedScreens,
+    board: boardSurface
+      ? relativeRect(boardSurface.getBoundingClientRect())
+      : undefined,
+  };
+}
+
+function annotationBounds(annotation: DrawAnnotation) {
+  if (annotation.type === "text") {
+    return {
+      left: annotation.position.x,
+      top: annotation.position.y,
+      right: annotation.position.x,
+      bottom: annotation.position.y,
+    };
+  }
+  const values = Array.from(
+    annotation.pathData?.matchAll(/-?\d+(?:\.\d+)?/g) ?? [],
+    (match) => Number(match[0]),
+  );
+  const xs = values.filter((_, index) => index % 2 === 0);
+  const ys = values.filter((_, index) => index % 2 === 1);
+  if (!xs.length || !ys.length) return null;
+  return {
+    left: Math.min(...xs),
+    top: Math.min(...ys),
+    right: Math.max(...xs),
+    bottom: Math.max(...ys),
+  };
+}
+
+function mappedAnnotationRegions(
+  annotation: DrawAnnotation,
+  viewportMap: OverviewAnnotationViewportMap,
+) {
+  const bounds = annotationBounds(annotation);
+  if (!bounds) return ["board"];
+  const screens = viewportMap.screens.filter(
+    (screen) =>
+      bounds.right >= screen.x &&
+      bounds.left <= screen.x + screen.width &&
+      bounds.bottom >= screen.y &&
+      bounds.top <= screen.y + screen.height,
+  );
+  return screens.length
+    ? screens.map((screen) => `${screen.name} (${screen.id})`)
+    : ["board outside screens"];
+}
+
+export function formatOverviewAnnotationMessage({
+  designId,
+  designTitle,
+  annotations,
+  instruction,
+  viewportMap,
+}: {
+  designId: string;
+  designTitle?: string;
+  annotations: DrawAnnotation[];
+  instruction: string;
+  viewportMap: OverviewAnnotationViewportMap;
+}) {
+  const drawing = annotations
+    .map((annotation) => {
+      const regions = mappedAnnotationRegions(annotation, viewportMap).join(
+        ", ",
+      );
+      return annotation.type === "path"
+        ? `[stroke regions=${regions} color=${annotation.color} w=${annotation.lineWidth}] ${annotation.pathData}`
+        : `[label regions=${regions} text="${annotation.text ?? ""}" at ${annotation.position.x.toFixed(0)},${annotation.position.y.toFixed(0)}]`;
+    })
+    .join("\n");
+  const screenMap = viewportMap.screens
+    .map(
+      (screen) =>
+        `- ${screen.name} (${screen.id}): x=${screen.x.toFixed(1)}, y=${screen.y.toFixed(1)}, width=${screen.width.toFixed(1)}, height=${screen.height.toFixed(1)}`,
+    )
+    .join("\n");
+  const boardMap = viewportMap.board
+    ? `Board surface: x=${viewportMap.board.x.toFixed(1)}, y=${viewportMap.board.y.toFixed(1)}, width=${viewportMap.board.width.toFixed(1)}, height=${viewportMap.board.height.toFixed(1)}`
+    : "Board surface: the viewport outside the mapped screen rectangles";
+
+  return [
+    `[Annotations on the all-screens canvas for design ${designId}${designTitle ? ` (${designTitle})` : ""}]`,
+    `Overview viewport: ${viewportMap.width.toFixed(0)}x${viewportMap.height.toFixed(0)} at ${viewportMap.zoom.toFixed(1)}% zoom`,
+    "Coordinates and screen bounds are viewport-relative at send time; their x/y positions encode the current canvas pan.",
+    "",
+    "[Screen map]",
+    screenMap || "- No screen rectangles were visible",
+    boardMap,
+    ...(drawing ? ["", "[Drawing]", drawing] : []),
+    "",
+    instruction || "Apply these annotations to the design.",
+  ].join("\n");
+}
diff --git a/templates/design/app/pages/design-editor/overview-camera.ts b/templates/design/app/pages/design-editor/overview-camera.ts
index 3804bbe75f..f7c3b6eebb 100644
--- a/templates/design/app/pages/design-editor/overview-camera.ts
+++ b/templates/design/app/pages/design-editor/overview-camera.ts
@@ -76,9 +76,11 @@ export function getScreenFrameOriginCanvas(args: {
  * `getInitialFrameGeometry(index, ...)` fallback `getSelectedScreenGeometryForInspector`
  * and `getScreenFrameOriginCanvas` above already use — as `FrameEntry[]` for
  * `@shared/canvas-math` bounds/fit helpers (`getFrameGroupBounds`,
- * `getCameraForBounds`). Optionally includes the board frame (real Figma has
- * no board-file equivalent, but a design with only board primitives and no
- * screens should still have something to fit to).
+ * `getCameraForBounds`). Optionally includes the bounds of actual board
+ * content. This must never receive the logical board hit-test surface: that
+ * surface is intentionally enormous and including it would make zoom-to-fit
+ * and adjacent-screen placement behave as though the design were 131,072px
+ * wide even when the board is empty.
  */
 export function getAllScreenFrameEntries(args: {
   overviewScreens: Array<{
@@ -87,7 +89,7 @@ export function getAllScreenFrameEntries(args: {
     height?: number;
   }>;
   canvasFrameGeometryById: CanvasFrameGeometryById;
-  boardFrameGeometry?: FrameGeometry;
+  boardContentBounds?: FrameGeometry | null;
   boardFileId?: string | null;
 }): FrameEntry[] {
   const entries: FrameEntry[] = args.overviewScreens.map((screen, index) => {
@@ -103,10 +105,10 @@ export function getAllScreenFrameEntries(args: {
   });
   if (
     args.boardFileId &&
-    args.boardFrameGeometry &&
+    args.boardContentBounds &&
     !entries.some((entry) => entry.id === args.boardFileId)
   ) {
-    entries.push({ id: args.boardFileId, geometry: args.boardFrameGeometry });
+    entries.push({ id: args.boardFileId, geometry: args.boardContentBounds });
   }
   return entries;
 }
@@ -436,3 +438,57 @@ export function shouldPopToOverviewOnZoomChange(args: {
   if (args.suppressExplicitZoom) return false;
   return shouldPopToOverviewOnZoomOut(args);
 }
+
+/**
+ * PASTE-HERE-IN-CONTENT: converts a viewport client point into a
+ * screen/iframe-local canvas point, given that iframe's own
+ * boundingClientRect and the zoom percent (0-100) currently scaling it.
+ *
+ * Shared by DesignEditor's getContextCanvasPoint (the background/board
+ * right-click path, reached through CanvasContextMenu's own
+ * onContextMenuCapture) and handleIframeContextMenu (a right-click that
+ * lands ON rendered screen content — an element, or empty in-screen space —
+ * which opens the menu imperatively via a ref and so bypasses
+ * onContextMenuCapture, and with it getCanvasPoint, entirely). Before this
+ * was wired into handleIframeContextMenu too, "Paste here" triggered from a
+ * right-click on actual screen content never got a canvasX/canvasY at all
+ * and silently fell back to the position-less cascade/offset paste instead
+ * of landing under the cursor — only a right-click on the empty canvas
+ * background (which still goes through onContextMenuCapture) worked.
+ *
+ * Returns null when there's no iframe rect to measure against or the zoom
+ * factor is non-positive (would divide by zero / invert the sign), matching
+ * "no reliable canvas point" — callers fall back to their own
+ * container-relative or position-less behavior in that case.
+ */
+export function computeIframeLocalCanvasPoint(args: {
+  clientX: number;
+  clientY: number;
+  iframeRect: { left: number; top: number } | null | undefined;
+  zoomPercent: number;
+}): { x: number; y: number } | null {
+  if (!args.iframeRect || !(args.zoomPercent > 0)) return null;
+  const factor = args.zoomPercent / 100;
+  return {
+    x: Math.max(0, (args.clientX - args.iframeRect.left) / factor),
+    y: Math.max(0, (args.clientY - args.iframeRect.top) / factor),
+  };
+}
+
+/**
+ * Reads MultiScreenCanvas's live imperative zoom from the exact inline
+ * transform written by `applyViewToDom` while a wheel/pinch gesture is still
+ * settling. React's `overviewCanvasZoom` intentionally lags those per-frame
+ * DOM writes until the gesture commit, so cursor-sensitive commands must use
+ * this value when it is available.
+ */
+export function readOverviewZoomPercentFromTransform(
+  transform: string | null | undefined,
+  fallbackZoomPercent: number,
+): number {
+  const match = transform?.match(/(?:^|\s)scale\(\s*([-+]?\d*\.?\d+)\s*\)/i);
+  const scale = match ? Number(match[1]) : Number.NaN;
+  return Number.isFinite(scale) && scale > 0
+    ? scale * 100
+    : fallbackZoomPercent;
+}
diff --git a/templates/design/app/pages/design-editor/pending-edits.ts b/templates/design/app/pages/design-editor/pending-edits.ts
index 7f67e022d3..76383da3f9 100644
--- a/templates/design/app/pages/design-editor/pending-edits.ts
+++ b/templates/design/app/pages/design-editor/pending-edits.ts
@@ -18,6 +18,12 @@ import {
 
 import type { ElementInfo } from "@/components/design/types";
 
+import {
+  buildReactSemanticHandoff,
+  redactReactSourceAnchor,
+  type ReactSourceAnchor,
+  type ReactSourceScope,
+} from "./react-semantic-handoff";
 import { camelStyleProperty } from "./style-utils";
 
 export interface PendingVisualStyleEdit {
@@ -26,6 +32,7 @@ export interface PendingVisualStyleEdit {
   screenName: string;
   selector: string;
   sourceId?: string | null;
+  sourceAnchor?: ReactSourceAnchor;
   tagName?: string | null;
   classes: string[];
   styles: Record<string, string>;
@@ -104,6 +111,7 @@ export interface PendingLiveTextEdit {
   screenName: string;
   selector: string;
   sourceId?: string | null;
+  sourceAnchor?: ReactSourceAnchor;
   tagName?: string | null;
   classes: string[];
   value: string;
@@ -120,13 +128,154 @@ export interface PendingLiveStructureEdit {
   screenName: string;
   selector: string;
   sourceId?: string | null;
+  sourceAnchor?: ReactSourceAnchor;
   anchorSelector: string;
   anchorSourceId?: string | null;
+  anchorSourceAnchor?: ReactSourceAnchor;
   placement: "before" | "after" | "inside";
   requestId?: string;
   updatedAt: number;
 }
 
+/**
+ * Convert bridge provenance into a bounded semantic source anchor. Runtime
+ * ids remain useful for correlating the live preview, but they are never
+ * treated as source identities by the coding-agent handoff.
+ */
+interface NormalizedResolvablePath {
+  value: string;
+  absolute: boolean;
+  caseInsensitive: boolean;
+}
+
+function normalizeResolvablePath(
+  rawValue: string | undefined,
+): NormalizedResolvablePath | undefined {
+  const raw = rawValue?.trim().replace(/\\/g, "/");
+  if (!raw || raw.includes("\0")) return undefined;
+
+  let prefix = "";
+  let remainder = raw;
+  let absolute = false;
+  let caseInsensitive = false;
+  const drive = raw.match(/^([a-z]):(\/.*)?$/i);
+  if (drive) {
+    // `C:foo` is drive-relative and must not be treated as a project path.
+    if (!drive[2]?.startsWith("/")) return undefined;
+    prefix = `${drive[1]!.toUpperCase()}:/`;
+    remainder = drive[2].slice(1);
+    absolute = true;
+    caseInsensitive = true;
+  } else if (raw.startsWith("//")) {
+    const [server, share, ...rest] = raw.slice(2).split("/");
+    if (!server || !share) return undefined;
+    prefix = `//${server}/${share}`;
+    remainder = rest.join("/");
+    absolute = true;
+    caseInsensitive = true;
+  } else if (raw.startsWith("/")) {
+    prefix = "/";
+    remainder = raw.slice(1);
+    absolute = true;
+  } else if (/^[a-z]+:/i.test(raw)) {
+    // URL-like values and unsupported drive-relative paths are not files.
+    return undefined;
+  }
+
+  const segments: string[] = [];
+  for (const segment of remainder.split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length > 0) {
+        segments.pop();
+      } else if (!absolute) {
+        // A relative path may not escape its unknown project root.
+        return undefined;
+      }
+      continue;
+    }
+    segments.push(segment);
+  }
+
+  const suffix = segments.join("/");
+  const value = absolute
+    ? prefix.endsWith("/")
+      ? `${prefix}${suffix}`
+      : suffix
+        ? `${prefix}/${suffix}`
+        : prefix
+    : suffix;
+  if (!value) return undefined;
+  return { value, absolute, caseInsensitive };
+}
+
+function sourcePathRelativeToRoot(args: {
+  sourceFile: string;
+  rootPath?: string;
+}): string | undefined {
+  const source = normalizeResolvablePath(args.sourceFile);
+  if (!source) return undefined;
+  if (!source.absolute) return source.value;
+
+  const root = normalizeResolvablePath(args.rootPath);
+  if (!root?.absolute || root.caseInsensitive !== source.caseInsensitive) {
+    return undefined;
+  }
+  const comparableSource = source.caseInsensitive
+    ? source.value.toLowerCase()
+    : source.value;
+  const comparableRoot = root.caseInsensitive
+    ? root.value.toLowerCase()
+    : root.value;
+  const rootPrefix = comparableRoot.endsWith("/")
+    ? comparableRoot
+    : `${comparableRoot}/`;
+  if (!comparableSource.startsWith(rootPrefix)) return undefined;
+  const relative = source.value.slice(rootPrefix.length);
+  return normalizeResolvablePath(relative)?.value;
+}
+
+export function reactSourceAnchorForPendingEdit(args: {
+  info?: Pick<ElementInfo, "provenance" | "sourceId" | "selector"> | null;
+  id?: string;
+  runtimeMultiplicity?: number;
+  scope?: ReactSourceScope;
+  reason?: string;
+  rootPath?: string;
+}): ReactSourceAnchor | undefined {
+  const provenance = args.info?.provenance;
+  const sourceFile = provenance?.sourceFile?.trim();
+  if (!sourceFile || !provenance?.line || !provenance.column) return undefined;
+  const runtimeMultiplicity =
+    Number.isInteger(args.runtimeMultiplicity) &&
+    (args.runtimeMultiplicity ?? 0) > 0
+      ? args.runtimeMultiplicity!
+      : 1;
+  const relPath = sourcePathRelativeToRoot({
+    sourceFile,
+    rootPath: args.rootPath,
+  });
+  return {
+    id:
+      args.id?.trim() ||
+      args.info?.sourceId?.trim() ||
+      args.info?.selector?.trim() ||
+      undefined,
+    // Keep the raw Fiber value only in local state. Prompt serialization goes
+    // through redactReactSourceAnchor, which omits absolute paths until the
+    // connection root has resolved them to a safe project-relative relPath.
+    sourceFile,
+    ...(relPath ? { relPath } : {}),
+    line: provenance.line,
+    column: provenance.column,
+    component: provenance.component,
+    runtimeMultiplicity,
+    ...(args.reason?.trim() ? { reason: args.reason.trim() } : {}),
+    scope:
+      args.scope ?? (runtimeMultiplicity > 1 ? "repeated-render" : "unknown"),
+  };
+}
+
 export type PendingLiveNonStyleEdit =
   | PendingLiveTextEdit
   | PendingLiveStructureEdit;
@@ -289,6 +438,7 @@ export function formatPendingVisualStylePrompt(args: {
     screenName: edit.screenName,
     selector: edit.selector,
     sourceId: edit.sourceId ?? null,
+    sourceAnchor: redactReactSourceAnchor(edit.sourceAnchor),
     tagName: edit.tagName ?? null,
     classes: edit.classes,
     styles: edit.styles,
@@ -297,6 +447,21 @@ export function formatPendingVisualStylePrompt(args: {
   const hasBreakpointScopedEdits = args.edits.some(
     (edit) => edit.breakpoint && edit.breakpoint.upperBoundPx !== null,
   );
+  const reactSourceAnchors = [
+    ...args.edits.map((edit) => edit.sourceAnchor),
+    ...(args.liveEdits ?? []).flatMap((edit) =>
+      edit.kind === "structure"
+        ? [edit.sourceAnchor, edit.anchorSourceAnchor]
+        : [edit.sourceAnchor],
+    ),
+  ].filter((anchor): anchor is ReactSourceAnchor => Boolean(anchor));
+  const hasReactSourceAnchors = reactSourceAnchors.length > 0;
+  const hasRepeatedOrSharedReactScope = reactSourceAnchors.some(
+    (anchor) =>
+      (anchor.runtimeMultiplicity ?? 1) > 1 ||
+      anchor.scope === "repeated-render" ||
+      anchor.scope === "shared-component-definition",
+  );
   const liveEditPayload = (args.liveEdits ?? []).map((edit) => {
     if (edit.kind === "text") {
       return {
@@ -306,12 +471,44 @@ export function formatPendingVisualStylePrompt(args: {
         screenName: edit.screenName,
         selector: edit.selector,
         sourceId: edit.sourceId ?? null,
+        sourceAnchor: redactReactSourceAnchor(edit.sourceAnchor),
         tagName: edit.tagName ?? null,
         classes: edit.classes,
         value: edit.value,
         html: edit.html,
       };
     }
+    const subjectAnchor = edit.sourceAnchor
+      ? { ...edit.sourceAnchor, id: "subject" }
+      : undefined;
+    const targetAnchor = edit.anchorSourceAnchor
+      ? { ...edit.anchorSourceAnchor, id: "target" }
+      : undefined;
+    const semanticHandoff =
+      subjectAnchor && targetAnchor
+        ? buildReactSemanticHandoff({
+            operation: edit.placement === "inside" ? "reparent" : "move",
+            desiredChange: `Move the selected runtime element ${edit.placement} the target runtime element.`,
+            sourceAnchors: [subjectAnchor, targetAnchor],
+            runtimeRelationship: {
+              kind: edit.placement,
+              subjectAnchorIds: ["subject"],
+              targetAnchorId: "target",
+              screenId: edit.screenId,
+              description: `${edit.selector} ${edit.placement} ${edit.anchorSelector}`,
+            },
+            // The packet intentionally starts without a hash: its execution
+            // contract requires read-local-file before every write.
+            versionHashes: [],
+          })
+        : {
+            ok: false as const,
+            rejection: {
+              code: "missing-source-provenance" as const,
+              reason:
+                "Exact subject and target source anchors were not both available for this React structure edit.",
+            },
+          };
     return {
       kind: edit.kind,
       screenId: edit.screenId,
@@ -319,9 +516,14 @@ export function formatPendingVisualStylePrompt(args: {
       screenName: edit.screenName,
       selector: edit.selector,
       sourceId: edit.sourceId ?? null,
+      sourceAnchor: redactReactSourceAnchor(edit.sourceAnchor),
       anchorSelector: edit.anchorSelector,
       anchorSourceId: edit.anchorSourceId ?? null,
+      anchorSourceAnchor: redactReactSourceAnchor(edit.anchorSourceAnchor),
       placement: edit.placement,
+      ...(semanticHandoff.ok
+        ? { semanticHandoff: semanticHandoff.handoff }
+        : { semanticHandoffFailure: semanticHandoff.rejection }),
     };
   });
 
@@ -333,6 +535,12 @@ export function formatPendingVisualStylePrompt(args: {
       : "",
     "",
     "Use the Design source tools to make the source match the current live canvas preview. Read each target screen, resolve source ids/selectors through the code-layer projection, then apply the style, text, and structure changes with focused source edits. Preserve layout, behavior, and unrelated styling.",
+    hasReactSourceAnchors
+      ? "React sourceAnchor fields are source provenance; runtime source ids and selectors are correlation hints only. Verify every project-relative file, line, column, component, and surrounding control flow before editing. Never use a generic AST reparent, group, wrapper, or other structural transform. For semantic structure edits, follow the embedded semanticHandoff packet and use this exact guarded sequence: read-local-file, capture its versionHash, obtain human write consent, write-local-file with expectedVersionHash and requireExpectedVersionHash: true, then keep the preview pending until HMR proves the intended runtime relationship. On a version conflict, re-read and re-plan; never overwrite blindly."
+      : "",
+    hasRepeatedOrSharedReactScope
+      ? "At least one React anchor is repeated at runtime or resolves to a shared component definition. Inspect map/conditional/component call sites and confirm whether the change should affect one instance or every instance before writing source."
+      : "",
     hasBreakpointScopedEdits
       ? "Edits that carry a `breakpoint` field were made while a narrower breakpoint frame was active: apply them as width-scoped overrides (apply-visual-edit with `activeFrameWidthPx` set to breakpoint.activeWidthPx), NOT as base writes — base values must keep rendering at wider viewports."
       : "",
@@ -361,6 +569,43 @@ export function resolveOverviewScreenSourceType(
   );
 }
 
+export function shouldUseRuntimeLayerProjection(args: {
+  screen:
+    | { sourceType?: unknown; bridgeUrl?: string | null }
+    | null
+    | undefined;
+  fallbackSourceType?: DesignSourceType;
+  content: string;
+}): boolean {
+  if (
+    resolveOverviewScreenSourceType(
+      args.screen,
+      args.fallbackSourceType ?? "inline",
+    ) !== "localhost"
+  ) {
+    return false;
+  }
+  try {
+    const url = new URL(args.content.trim());
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function shouldPreferRuntimeLayerProjection(args: {
+  eligible: boolean;
+  runtimeNodeCount: number;
+  sourceNodeCount: number;
+}): boolean {
+  // A hydrated localhost tree is the visible app's ground truth even when SSR
+  // happened to emit the same number of nodes (or more wrappers). Keep the
+  // source projection separately for writes; never use counts to decide which
+  // tree represents the live Layers panel.
+  void args.sourceNodeCount;
+  return args.eligible && args.runtimeNodeCount > 0;
+}
+
 export function shouldShowPendingVisualStyleApply(args: {
   edits: readonly PendingVisualStyleEdit[];
   liveEdits?: readonly PendingLiveNonStyleEdit[];
diff --git a/templates/design/app/pages/design-editor/react-semantic-handoff.test.ts b/templates/design/app/pages/design-editor/react-semantic-handoff.test.ts
new file mode 100644
index 0000000000..8f8705b18c
--- /dev/null
+++ b/templates/design/app/pages/design-editor/react-semantic-handoff.test.ts
@@ -0,0 +1,855 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  formatPendingVisualStylePrompt,
+  reactSourceAnchorForPendingEdit,
+} from "./pending-edits";
+import {
+  buildReactSemanticHandoff,
+  buildRuntimeReactLayerStateHandoff,
+  buildRuntimeReactStructureMoveHandoff,
+  redactReactSourceAnchor,
+  resolveRuntimeStructureMoveExecutionMode,
+  type ReactSourceAnchor,
+} from "./react-semantic-handoff";
+
+const SUBJECT: ReactSourceAnchor = {
+  id: "subject",
+  relPath: "app/components/Card.tsx",
+  sourceFile: "/Users/example/project/app/components/Card.tsx",
+  line: 18,
+  column: 7,
+  component: "Card",
+  runtimeMultiplicity: 1,
+  scope: "single-instance",
+};
+
+const TARGET: ReactSourceAnchor = {
+  id: "target-source",
+  relPath: "app/components/Hero.tsx",
+  sourceFile: "app/components/Hero.tsx",
+  line: 42,
+  column: 5,
+  component: "Hero",
+  runtimeMultiplicity: 1,
+  scope: "single-instance",
+};
+
+function build(
+  overrides: Partial<Parameters<typeof buildReactSemanticHandoff>[0]> = {},
+) {
+  return buildReactSemanticHandoff({
+    operation: "reparent",
+    desiredChange: "Move the card inside the hero container.",
+    sourceAnchors: [SUBJECT],
+    runtimeRelationship: {
+      kind: "inside",
+      subjectAnchorIds: ["subject"],
+    },
+    versionHashes: [
+      {
+        relPath: "app/components/Card.tsx",
+        versionHash: "123-abc",
+      },
+    ],
+    ...overrides,
+  });
+}
+
+describe("buildReactSemanticHandoff", () => {
+  it("builds a bounded coding-agent contract without enabling AST structure transforms", () => {
+    const result = build();
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.handoff).toMatchObject({
+      version: 1,
+      executionMode: "coding-agent",
+      operation: "reparent",
+      sourceAnchors: [
+        {
+          id: "subject",
+          relPath: "app/components/Card.tsx",
+          sourceFile: "app/components/Card.tsx",
+          line: 18,
+          column: 7,
+        },
+      ],
+      versionHashes: [
+        {
+          relPath: "app/components/Card.tsx",
+          versionHash: "123-abc",
+        },
+      ],
+      executionContract: {
+        requiresHumanWriteConsent: true,
+        requiresReadBeforeWrite: true,
+        requiresExpectedVersionHash: true,
+        allowsBlindOverwrite: false,
+        allowsGenericAstStructureTransform: false,
+        preservePreviewUntilHmrConfirmation: true,
+        onVersionConflict: "re-read-and-replan",
+      },
+    });
+    expect(result.handoff.instructions.join(" ")).toContain(
+      "do not apply a generic AST reparent",
+    );
+  });
+
+  it("routes repeated map renders to the coding agent with an explicit scope reason", () => {
+    const result = build({
+      sourceAnchors: [
+        {
+          ...SUBJECT,
+          runtimeMultiplicity: 6,
+          scope: "repeated-render",
+          reason: "The same JSX opening element rendered once per map item.",
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.handoff.deterministicWritebackRejection).toEqual({
+      code: "repeated-runtime-render",
+      reason:
+        "More than one runtime node resolves to the same source anchor, so a deterministic per-instance source edit would be unsafe.",
+    });
+    expect(result.handoff.sourceAnchors[0]).toMatchObject({
+      runtimeMultiplicity: 6,
+      scope: "repeated-render",
+    });
+  });
+
+  it("makes shared component definition scope explicit before repeated-render scope", () => {
+    const result = build({
+      operation: "component-change",
+      sourceAnchors: [
+        {
+          ...SUBJECT,
+          component: "Button",
+          runtimeMultiplicity: 12,
+          scope: "shared-component-definition",
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.handoff.deterministicWritebackRejection.code).toBe(
+      "shared-component-scope",
+    );
+    expect(result.handoff.deterministicWritebackRejection.reason).toContain(
+      "shared component definition",
+    );
+  });
+
+  it("rejects missing file provenance without inventing an anchor", () => {
+    const result = build({
+      sourceAnchors: [{ id: "subject", line: 4, column: 9 }],
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      rejection: {
+        code: "missing-source-provenance",
+        reason: "Source anchor 1 is missing file provenance.",
+      },
+    });
+  });
+
+  it("requires exact positive line and column provenance", () => {
+    const result = build({
+      sourceAnchors: [
+        {
+          id: "subject",
+          relPath: "app/Card.tsx",
+          line: 4,
+        },
+      ],
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      rejection: { code: "invalid-source-location" },
+    });
+  });
+
+  it("redacts an absolute Fiber source path when a safe relPath is available", () => {
+    const result = build();
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const serialized = JSON.stringify(result.handoff);
+    expect(serialized).not.toContain("/Users/example/project");
+    expect(result.handoff.sourceAnchors[0]?.sourceFile).toBe(
+      "app/components/Card.tsx",
+    );
+  });
+
+  it("rejects an absolute-only source path without echoing it", () => {
+    const result = build({
+      sourceAnchors: [
+        {
+          id: "subject",
+          sourceFile: "/Users/private/project/app/Card.tsx",
+          line: 4,
+          column: 2,
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(JSON.stringify(result)).not.toContain("/Users/private");
+    expect(result).toMatchObject({
+      rejection: { code: "unsafe-source-path" },
+    });
+  });
+
+  it("rejects runtime relationships that do not reference bounded anchors", () => {
+    const result = build({
+      runtimeRelationship: {
+        kind: "inside",
+        subjectAnchorIds: ["missing"],
+      },
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      rejection: { code: "invalid-runtime-relationship" },
+    });
+  });
+
+  it("bounds user-authored descriptions and explicit rejection reasons", () => {
+    const result = build({
+      desiredChange: "x".repeat(3_000),
+      runtimeRelationship: {
+        kind: "inside",
+        subjectAnchorIds: ["subject"],
+        description: "y".repeat(1_000),
+      },
+      deterministicRejection: {
+        code: "dynamic-source-expression",
+        reason: "z".repeat(1_000),
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.handoff.desiredChange).toHaveLength(2_000);
+    expect(result.handoff.runtimeRelationship.description).toHaveLength(800);
+    expect(result.handoff.deterministicWritebackRejection.reason).toHaveLength(
+      800,
+    );
+  });
+});
+
+describe("buildRuntimeReactLayerStateHandoff", () => {
+  it.each([
+    ["locked", true, 'data-agent-native-locked="true"', "Set"],
+    ["hidden", true, 'data-agent-native-hidden="true"', "Set"],
+    ["locked", false, "data-agent-native-locked", "Clear"],
+    ["hidden", false, "data-agent-native-hidden", "Clear"],
+  ] as const)(
+    "builds an exact, guarded %s=%s source-metadata handoff",
+    (state, enabled, expectedAttribute, expectedVerb) => {
+      const result = buildRuntimeReactLayerStateHandoff({
+        subjectAnchor: SUBJECT,
+        screenId: "screen-home",
+        state,
+        enabled,
+      });
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.handoff).toMatchObject({
+        version: 1,
+        executionMode: "coding-agent",
+        operation: "set-layer-state",
+        sourceAnchors: [
+          {
+            id: "subject",
+            relPath: "app/components/Card.tsx",
+            sourceFile: "app/components/Card.tsx",
+            line: 18,
+            column: 7,
+          },
+        ],
+        runtimeRelationship: {
+          kind: "metadata",
+          subjectAnchorIds: ["subject"],
+          screenId: "screen-home",
+          sourceScreenId: "screen-home",
+          targetScreenId: "screen-home",
+        },
+        versionHashes: [],
+        executionContract: {
+          requiresHumanWriteConsent: true,
+          requiresReadBeforeWrite: true,
+          requiresExpectedVersionHash: true,
+          allowsBlindOverwrite: false,
+          allowsGenericAstStructureTransform: false,
+          preservePreviewUntilHmrConfirmation: true,
+          onVersionConflict: "re-read-and-replan",
+        },
+      });
+      expect(result.handoff.desiredChange).toContain(expectedAttribute);
+      expect(result.handoff.desiredChange).not.toContain("/Users/example");
+      expect(result.handoff.runtimeRelationship.description).toContain(
+        `${expectedVerb} runtime React layer state "${state}"`,
+      );
+      expect(result.handoff.instructions.join(" ")).toContain(
+        "requireExpectedVersionHash: true",
+      );
+    },
+  );
+
+  it("rejects missing screen ownership instead of emitting an ambiguous state edit", () => {
+    expect(
+      buildRuntimeReactLayerStateHandoff({
+        subjectAnchor: SUBJECT,
+        screenId: " ",
+        state: "hidden",
+        enabled: true,
+      }),
+    ).toEqual({
+      ok: false,
+      rejection: {
+        code: "invalid-runtime-relationship",
+        reason:
+          "Runtime layer state changes require an exact owning screen id.",
+      },
+    });
+  });
+
+  it("preserves repeated-render scope so the agent cannot guess at one JSX instance", () => {
+    const result = buildRuntimeReactLayerStateHandoff({
+      subjectAnchor: {
+        ...SUBJECT,
+        runtimeMultiplicity: 8,
+        scope: "repeated-render",
+      },
+      screenId: "screen-home",
+      state: "locked",
+      enabled: true,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.handoff.deterministicWritebackRejection.code).toBe(
+      "repeated-runtime-render",
+    );
+  });
+});
+
+describe("buildRuntimeReactStructureMoveHandoff", () => {
+  it("builds a cross-screen reparent with exact subject/target anchors and both screen ids", () => {
+    const result = buildRuntimeReactStructureMoveHandoff({
+      subjectAnchor: SUBJECT,
+      targetAnchor: TARGET,
+      placement: "inside",
+      sourceScreenId: "screen-source",
+      targetScreenId: "screen-target",
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.handoff).toMatchObject({
+      operation: "reparent",
+      sourceAnchors: [
+        { id: "subject", relPath: "app/components/Card.tsx" },
+        { id: "target", relPath: "app/components/Hero.tsx" },
+      ],
+      runtimeRelationship: {
+        kind: "inside",
+        subjectAnchorIds: ["subject"],
+        targetAnchorId: "target",
+        screenId: "screen-target",
+        sourceScreenId: "screen-source",
+        targetScreenId: "screen-target",
+      },
+      executionContract: {
+        requiresHumanWriteConsent: true,
+        requiresReadBeforeWrite: true,
+        requiresExpectedVersionHash: true,
+        allowsBlindOverwrite: false,
+        allowsGenericAstStructureTransform: false,
+        preservePreviewUntilHmrConfirmation: true,
+        onVersionConflict: "re-read-and-replan",
+      },
+    });
+    expect(result.handoff.runtimeRelationship.description).toContain(
+      'screen "screen-source" to screen "screen-target"',
+    );
+    expect(result.handoff.instructions.join(" ")).toContain(
+      "requireExpectedVersionHash: true",
+    );
+  });
+
+  it("maps before/after placements to semantic moves", () => {
+    for (const placement of ["before", "after"] as const) {
+      const result = buildRuntimeReactStructureMoveHandoff({
+        subjectAnchor: SUBJECT,
+        targetAnchor: TARGET,
+        placement,
+        sourceScreenId: "screen-a",
+        targetScreenId: "screen-b",
+      });
+      expect(result.ok).toBe(true);
+      if (!result.ok) continue;
+      expect(result.handoff.operation).toBe("move");
+      expect(result.handoff.runtimeRelationship.kind).toBe(placement);
+    }
+  });
+
+  it("allows mixed runtime/source ownership only when both endpoints have exact provenance", () => {
+    const valid = buildRuntimeReactStructureMoveHandoff({
+      subjectAnchor: { ...SUBJECT, scope: "repeated-render" },
+      targetAnchor: TARGET,
+      placement: "inside",
+      sourceScreenId: "runtime-screen",
+      targetScreenId: "source-backed-screen",
+    });
+    expect(valid.ok).toBe(true);
+    if (valid.ok) {
+      expect(valid.handoff.deterministicWritebackRejection.code).toBe(
+        "repeated-runtime-render",
+      );
+    }
+
+    const missingTarget = buildRuntimeReactStructureMoveHandoff({
+      subjectAnchor: SUBJECT,
+      targetAnchor: { id: "target", line: 1, column: 1 },
+      placement: "inside",
+      sourceScreenId: "runtime-screen",
+      targetScreenId: "source-backed-screen",
+    });
+    expect(missingTarget).toMatchObject({
+      ok: false,
+      rejection: { code: "missing-source-provenance" },
+    });
+  });
+
+  it("rejects missing screen ownership instead of emitting an ambiguous handoff", () => {
+    expect(
+      buildRuntimeReactStructureMoveHandoff({
+        subjectAnchor: SUBJECT,
+        targetAnchor: TARGET,
+        placement: "inside",
+        sourceScreenId: " ",
+        targetScreenId: "screen-b",
+      }),
+    ).toEqual({
+      ok: false,
+      rejection: {
+        code: "invalid-runtime-relationship",
+        reason:
+          "Cross-screen runtime structure moves require exact source and target screen ids.",
+      },
+    });
+  });
+});
+
+describe("resolveRuntimeStructureMoveExecutionMode", () => {
+  it("keeps same-screen runtime moves on the fast screen bridge", () => {
+    expect(
+      resolveRuntimeStructureMoveExecutionMode({
+        subjectRuntimeOnly: true,
+        targetRuntimeOnly: true,
+        sourceScreenId: "screen-a",
+        targetScreenId: "screen-a",
+      }),
+    ).toBe("screen-bridge");
+  });
+
+  it("routes cross-screen runtime moves through the semantic handoff", () => {
+    expect(
+      resolveRuntimeStructureMoveExecutionMode({
+        subjectRuntimeOnly: true,
+        targetRuntimeOnly: true,
+        sourceScreenId: "screen-a",
+        targetScreenId: "screen-b",
+      }),
+    ).toBe("semantic-handoff");
+  });
+
+  it("routes either mixed runtime/source direction through the semantic handoff", () => {
+    for (const [subjectRuntimeOnly, targetRuntimeOnly] of [
+      [true, false],
+      [false, true],
+    ] as const) {
+      expect(
+        resolveRuntimeStructureMoveExecutionMode({
+          subjectRuntimeOnly,
+          targetRuntimeOnly,
+          sourceScreenId: "screen-a",
+          targetScreenId: "screen-b",
+        }),
+      ).toBe("semantic-handoff");
+    }
+  });
+});
+
+describe("pending React source anchors", () => {
+  it("creates a project-relative anchor from relative bridge provenance", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "./app\\components\\Card.tsx",
+          line: 18,
+          column: 7,
+          component: "Card",
+        },
+        sourceId: "runtime-card",
+        selector: ".card",
+      },
+    });
+
+    expect(anchor).toEqual({
+      id: "runtime-card",
+      relPath: "app/components/Card.tsx",
+      sourceFile: "./app\\components\\Card.tsx",
+      line: 18,
+      column: 7,
+      component: "Card",
+      runtimeMultiplicity: 1,
+      scope: "unknown",
+    });
+  });
+
+  it("keeps an absolute Fiber path only in local state and redacts it from prompts", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "/Users/private/work/app/Card.tsx",
+          line: 4,
+          column: 2,
+          component: "Card",
+        },
+        sourceId: "runtime-card",
+        selector: ".card",
+      },
+    });
+    expect(anchor).toMatchObject({
+      sourceFile: "/Users/private/work/app/Card.tsx",
+      line: 4,
+      column: 2,
+    });
+    expect(anchor?.relPath).toBeUndefined();
+
+    const prompt = formatPendingVisualStylePrompt({
+      edits: [
+        {
+          screenId: "home",
+          filename: "home",
+          screenName: "Home",
+          selector: ".card",
+          sourceId: "runtime-card",
+          sourceAnchor: anchor,
+          classes: [],
+          styles: { color: "red" },
+          originalStyles: { color: "blue" },
+          updatedAt: 1,
+        },
+      ],
+    });
+
+    expect(prompt).not.toContain("/Users/private");
+    expect(prompt).toContain('"line": 4');
+    expect(prompt).not.toContain('"sourceFile"');
+  });
+
+  it("resolves absolute provenance against the authenticated connection root", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "/Users/example/project/src/components/Card.tsx",
+          line: 14,
+          column: 7,
+          component: "Card",
+        },
+        selector: ".card",
+      },
+      rootPath: "/Users/example/project",
+    });
+
+    expect(anchor).toMatchObject({
+      relPath: "src/components/Card.tsx",
+      line: 14,
+      column: 7,
+    });
+    expect(redactReactSourceAnchor(anchor)).toMatchObject({
+      relPath: "src/components/Card.tsx",
+      sourceFile: "src/components/Card.tsx",
+    });
+  });
+
+  it("resolves Windows drive paths case-insensitively across slash styles", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "C:\\WORKSPACE\\Project\\src\\Card.tsx",
+          line: 14,
+          column: 7,
+        },
+        selector: ".card",
+      },
+      rootPath: "c:/workspace/project/",
+    });
+
+    expect(anchor?.relPath).toBe("src/Card.tsx");
+  });
+
+  it("resolves UNC roots case-insensitively without losing the share boundary", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "\\\\SERVER\\Share\\Project\\src\\Card.tsx",
+          line: 14,
+          column: 7,
+        },
+        selector: ".card",
+      },
+      rootPath: "\\\\server\\share\\project",
+    });
+
+    expect(anchor?.relPath).toBe("src/Card.tsx");
+  });
+
+  it("supports the filesystem root without collapsing its boundary", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "/src/Card.tsx",
+          line: 14,
+          column: 7,
+        },
+        selector: ".card",
+      },
+      rootPath: "/",
+    });
+
+    expect(anchor?.relPath).toBe("src/Card.tsx");
+  });
+
+  it.each([
+    {
+      label: "POSIX sibling-prefix",
+      sourceFile: "/Users/example/project-other/src/Card.tsx",
+      rootPath: "/Users/example/project",
+    },
+    {
+      label: "POSIX traversal outside root",
+      sourceFile: "/Users/example/project/src/../../private/Card.tsx",
+      rootPath: "/Users/example/project",
+    },
+    {
+      label: "relative traversal",
+      sourceFile: "../private/Card.tsx",
+      rootPath: "/Users/example/project",
+    },
+    {
+      label: "Windows sibling-prefix",
+      sourceFile: "C:\\workspace\\project-other\\src\\Card.tsx",
+      rootPath: "C:\\workspace\\project",
+    },
+    {
+      label: "POSIX case mismatch",
+      sourceFile: "/Users/example/Project/src/Card.tsx",
+      rootPath: "/Users/example/project",
+    },
+    {
+      label: "URL-like source",
+      sourceFile: "https://example.test/src/Card.tsx",
+      rootPath: "/Users/example/project",
+    },
+  ])("does not derive relPath across a $label boundary", (fixture) => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: fixture.sourceFile,
+          line: 14,
+          column: 7,
+        },
+        selector: ".card",
+      },
+      rootPath: fixture.rootPath,
+    });
+
+    expect(anchor?.relPath).toBeUndefined();
+  });
+
+  it("normalizes dot segments only when they remain within the root", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "/Users/example/project/src/../Card.tsx",
+          line: 14,
+          column: 7,
+        },
+        selector: ".card",
+      },
+      rootPath: "/Users/example/project",
+    });
+
+    expect(anchor?.relPath).toBe("Card.tsx");
+  });
+
+  it("preserves explicit repeated and shared component scope for agent reasoning", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "app/components/Button.tsx",
+          line: 12,
+          column: 5,
+          component: "Button",
+        },
+        selector: "button",
+      },
+      runtimeMultiplicity: 9,
+      scope: "shared-component-definition",
+      reason: "This host node is owned by the shared Button definition.",
+    });
+
+    expect(anchor).toMatchObject({
+      runtimeMultiplicity: 9,
+      scope: "shared-component-definition",
+      reason: "This host node is owned by the shared Button definition.",
+    });
+  });
+
+  it("infers repeated-render scope from runtime multiplicity", () => {
+    const anchor = reactSourceAnchorForPendingEdit({
+      info: {
+        provenance: {
+          sourceFile: "app/Card.tsx",
+          line: 8,
+          column: 3,
+        },
+        selector: ".card",
+      },
+      runtimeMultiplicity: 4,
+    });
+
+    expect(anchor).toMatchObject({
+      runtimeMultiplicity: 4,
+      scope: "repeated-render",
+    });
+  });
+
+  it("serializes style, text, moving-node, and target anchors into the agent prompt", () => {
+    const targetAnchor: ReactSourceAnchor = {
+      id: "target",
+      relPath: "app/components/Hero.tsx",
+      sourceFile: "app/components/Hero.tsx",
+      line: 9,
+      column: 5,
+      component: "Hero",
+      runtimeMultiplicity: 1,
+      scope: "single-instance",
+    };
+    const prompt = formatPendingVisualStylePrompt({
+      edits: [
+        {
+          screenId: "home",
+          filename: "home",
+          screenName: "Home",
+          selector: ".card",
+          sourceId: "runtime-card",
+          sourceAnchor: SUBJECT,
+          classes: ["card"],
+          styles: { display: "flex" },
+          originalStyles: { display: "block" },
+          updatedAt: 1,
+        },
+      ],
+      liveEdits: [
+        {
+          kind: "text",
+          screenId: "home",
+          filename: "home",
+          screenName: "Home",
+          selector: ".card",
+          sourceId: "runtime-card",
+          sourceAnchor: SUBJECT,
+          classes: ["card"],
+          value: "New text",
+          originalValue: "Old text",
+          updatedAt: 2,
+        },
+        {
+          kind: "structure",
+          screenId: "home",
+          filename: "home",
+          screenName: "Home",
+          selector: ".card",
+          sourceId: "runtime-card",
+          sourceAnchor: SUBJECT,
+          anchorSelector: ".hero",
+          anchorSourceId: "runtime-hero",
+          anchorSourceAnchor: targetAnchor,
+          placement: "inside",
+          updatedAt: 3,
+        },
+      ],
+    });
+
+    expect(prompt).toContain('"sourceAnchor"');
+    expect(prompt).toContain('"anchorSourceAnchor"');
+    expect(prompt).toContain('"relPath": "app/components/Card.tsx"');
+    expect(prompt).toContain('"relPath": "app/components/Hero.tsx"');
+    expect(prompt).not.toContain("/Users/example/project");
+    expect(prompt.match(/"runtimeMultiplicity": 1/g)).toHaveLength(6);
+    expect(prompt).toContain('"semanticHandoff"');
+    expect(prompt).toContain('"executionMode": "coding-agent"');
+    expect(prompt).toContain('"operation": "reparent"');
+    expect(prompt).toContain('"versionHashes": []');
+    expect(prompt).toContain('"subjectAnchorIds": [');
+    expect(prompt).toContain('"targetAnchorId": "target"');
+    expect(prompt).toContain("Never use a generic AST reparent");
+    expect(prompt).toContain(
+      "read-local-file, capture its versionHash, obtain human write consent, write-local-file with expectedVersionHash",
+    );
+    expect(prompt).toContain(
+      "keep the preview pending until HMR proves the intended runtime relationship",
+    );
+  });
+
+  it("includes a safe handoff failure without leaking an unresolved absolute path", () => {
+    const prompt = formatPendingVisualStylePrompt({
+      edits: [],
+      liveEdits: [
+        {
+          kind: "structure",
+          screenId: "home",
+          filename: "home",
+          screenName: "Home",
+          selector: ".card",
+          sourceId: "runtime-card",
+          sourceAnchor: {
+            id: "subject",
+            sourceFile: "/Users/private/work/app/Card.tsx",
+            line: 4,
+            column: 2,
+          },
+          anchorSelector: ".hero",
+          anchorSourceId: "runtime-hero",
+          anchorSourceAnchor: {
+            id: "target",
+            relPath: "app/Hero.tsx",
+            sourceFile: "app/Hero.tsx",
+            line: 8,
+            column: 3,
+          },
+          placement: "inside",
+          updatedAt: 1,
+        },
+      ],
+    });
+
+    expect(prompt).toContain('"semanticHandoffFailure"');
+    expect(prompt).toContain('"code": "unsafe-source-path"');
+    expect(prompt).toContain("does not include a safe project-relative path");
+    expect(prompt).not.toContain("/Users/private");
+  });
+});
diff --git a/templates/design/app/pages/design-editor/react-semantic-handoff.ts b/templates/design/app/pages/design-editor/react-semantic-handoff.ts
new file mode 100644
index 0000000000..22cd21aef3
--- /dev/null
+++ b/templates/design/app/pages/design-editor/react-semantic-handoff.ts
@@ -0,0 +1,586 @@
+/**
+ * Safe context handoff for React changes that require semantic source edits.
+ *
+ * This module deliberately does not transform JSX. Compiler/AST tooling may
+ * verify an anchor or validate syntax elsewhere, but reparenting, grouping,
+ * wrappers, conditional renders, and shared component changes belong to the
+ * coding agent, which can inspect the surrounding program before editing it.
+ */
+
+export type ReactSourceScope =
+  | "single-instance"
+  | "repeated-render"
+  | "shared-component-definition"
+  | "unknown";
+
+/** Optional while an edit is only a live canvas preview. */
+export interface ReactSourceAnchor {
+  id?: string;
+  relPath?: string;
+  sourceFile?: string;
+  line?: number;
+  column?: number;
+  component?: string;
+  runtimeMultiplicity?: number;
+  reason?: string;
+  scope?: ReactSourceScope;
+}
+
+export interface ExactReactSourceAnchor {
+  id: string;
+  relPath: string;
+  sourceFile: string;
+  line: number;
+  column: number;
+  component?: string;
+  runtimeMultiplicity: number;
+  reason?: string;
+  scope: ReactSourceScope;
+}
+
+export type ReactSemanticOperation =
+  | "move"
+  | "reparent"
+  | "group"
+  | "ungroup"
+  | "wrap"
+  | "unwrap"
+  | "insert"
+  | "remove"
+  | "auto-layout"
+  | "set-layer-state"
+  | "component-change";
+
+export type ReactRuntimeRelationshipKind =
+  | "before"
+  | "after"
+  | "inside"
+  | "wrap"
+  | "unwrap"
+  | "remove"
+  | "style"
+  | "metadata";
+
+export interface ReactRuntimeRelationship {
+  kind: ReactRuntimeRelationshipKind;
+  subjectAnchorIds: readonly string[];
+  targetAnchorId?: string;
+  screenId?: string;
+  sourceScreenId?: string;
+  targetScreenId?: string;
+  description?: string;
+}
+
+export interface ReactSourceVersionHash {
+  relPath: string;
+  versionHash: string;
+}
+
+export type DeterministicWritebackRejectionCode =
+  | "semantic-source-change"
+  | "repeated-runtime-render"
+  | "shared-component-scope"
+  | "dynamic-source-expression"
+  | "ambiguous-source-anchor";
+
+export interface DeterministicWritebackRejection {
+  code: DeterministicWritebackRejectionCode;
+  reason: string;
+}
+
+export interface BuildReactSemanticHandoffInput {
+  operation: ReactSemanticOperation;
+  desiredChange: string;
+  sourceAnchors: readonly ReactSourceAnchor[];
+  runtimeRelationship: ReactRuntimeRelationship;
+  versionHashes?: readonly ReactSourceVersionHash[];
+  deterministicRejection?: DeterministicWritebackRejection;
+}
+
+export interface ReactSemanticExecutionContract {
+  requiresHumanWriteConsent: true;
+  requiresReadBeforeWrite: true;
+  requiresExpectedVersionHash: true;
+  allowsBlindOverwrite: false;
+  allowsGenericAstStructureTransform: false;
+  preservePreviewUntilHmrConfirmation: true;
+  onVersionConflict: "re-read-and-replan";
+}
+
+export interface ReactSemanticHandoff {
+  version: 1;
+  executionMode: "coding-agent";
+  operation: ReactSemanticOperation;
+  desiredChange: string;
+  sourceAnchors: ExactReactSourceAnchor[];
+  runtimeRelationship: {
+    kind: ReactRuntimeRelationshipKind;
+    subjectAnchorIds: string[];
+    targetAnchorId?: string;
+    screenId?: string;
+    sourceScreenId?: string;
+    targetScreenId?: string;
+    description?: string;
+  };
+  versionHashes: ReactSourceVersionHash[];
+  deterministicWritebackRejection: DeterministicWritebackRejection;
+  executionContract: ReactSemanticExecutionContract;
+  instructions: string[];
+}
+
+export type ReactSemanticHandoffBuildFailureCode =
+  | "missing-source-provenance"
+  | "unsafe-source-path"
+  | "invalid-source-location"
+  | "duplicate-anchor-id"
+  | "invalid-runtime-relationship"
+  | "context-limit-exceeded";
+
+export type ReactSemanticHandoffBuildResult =
+  | { ok: true; handoff: ReactSemanticHandoff }
+  | {
+      ok: false;
+      rejection: {
+        code: ReactSemanticHandoffBuildFailureCode;
+        reason: string;
+      };
+    };
+
+const MAX_SOURCE_ANCHORS = 8;
+const MAX_VERSION_HASHES = 12;
+const MAX_DESIRED_CHANGE_LENGTH = 2_000;
+const MAX_REASON_LENGTH = 800;
+const MAX_DESCRIPTION_LENGTH = 800;
+const MAX_COMPONENT_LENGTH = 160;
+const MAX_ID_LENGTH = 120;
+const MAX_SCREEN_ID_LENGTH = 160;
+
+export interface BuildRuntimeReactStructureMoveHandoffInput {
+  subjectAnchor: ReactSourceAnchor;
+  targetAnchor: ReactSourceAnchor;
+  placement: "before" | "after" | "inside";
+  sourceScreenId: string;
+  targetScreenId: string;
+}
+
+export type RuntimeReactLayerState = "locked" | "hidden";
+
+export interface BuildRuntimeReactLayerStateHandoffInput {
+  subjectAnchor: ReactSourceAnchor;
+  screenId: string;
+  state: RuntimeReactLayerState;
+  enabled: boolean;
+}
+
+export type RuntimeStructureMoveExecutionMode =
+  | "source-edit"
+  | "screen-bridge"
+  | "semantic-handoff";
+
+export function resolveRuntimeStructureMoveExecutionMode(input: {
+  subjectRuntimeOnly: boolean;
+  targetRuntimeOnly: boolean;
+  sourceScreenId: string;
+  targetScreenId: string;
+}): RuntimeStructureMoveExecutionMode {
+  if (!input.subjectRuntimeOnly && !input.targetRuntimeOnly)
+    return "source-edit";
+  if (
+    input.subjectRuntimeOnly &&
+    input.targetRuntimeOnly &&
+    input.sourceScreenId === input.targetScreenId
+  ) {
+    return "screen-bridge";
+  }
+  return "semantic-handoff";
+}
+
+function bounded(
+  value: string | undefined,
+  maxLength: number,
+): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  return trimmed.slice(0, maxLength);
+}
+
+function safeRelativePath(value: string | undefined): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed || trimmed.includes("\0")) return null;
+  if (/^(?:[a-z]+:|\\\\|\/)/i.test(trimmed)) return null;
+  const normalized = trimmed.replace(/\\/g, "/").replace(/^\.\//, "");
+  const parts = normalized.split("/");
+  if (
+    !normalized ||
+    parts.some((part) => part === "" || part === "." || part === "..")
+  ) {
+    return null;
+  }
+  return normalized;
+}
+
+/**
+ * Bound an optional live-preview anchor for prompt serialization. Absolute
+ * Fiber paths are replaced by the bridge-safe relPath when available, or
+ * omitted when no safe project-relative path has been resolved yet.
+ */
+export function redactReactSourceAnchor(
+  anchor: ReactSourceAnchor | undefined,
+): ReactSourceAnchor | undefined {
+  if (!anchor) return undefined;
+  const relPath = safeRelativePath(anchor.relPath);
+  const sourceFile = safeRelativePath(anchor.sourceFile);
+  const canonicalPath = relPath ?? sourceFile;
+  return {
+    ...(bounded(anchor.id, MAX_ID_LENGTH)
+      ? { id: bounded(anchor.id, MAX_ID_LENGTH) }
+      : {}),
+    ...(canonicalPath
+      ? {
+          relPath: canonicalPath,
+          sourceFile: sourceFile ?? canonicalPath,
+        }
+      : {}),
+    ...(Number.isInteger(anchor.line) && (anchor.line ?? 0) > 0
+      ? { line: anchor.line }
+      : {}),
+    ...(Number.isInteger(anchor.column) && (anchor.column ?? 0) > 0
+      ? { column: anchor.column }
+      : {}),
+    ...(bounded(anchor.component, MAX_COMPONENT_LENGTH)
+      ? { component: bounded(anchor.component, MAX_COMPONENT_LENGTH) }
+      : {}),
+    ...(Number.isInteger(anchor.runtimeMultiplicity) &&
+    (anchor.runtimeMultiplicity ?? 0) > 0
+      ? { runtimeMultiplicity: anchor.runtimeMultiplicity }
+      : {}),
+    ...(bounded(anchor.reason, MAX_REASON_LENGTH)
+      ? { reason: bounded(anchor.reason, MAX_REASON_LENGTH) }
+      : {}),
+    ...(anchor.scope ? { scope: anchor.scope } : {}),
+  };
+}
+
+function anchorFailure(
+  code: ReactSemanticHandoffBuildFailureCode,
+  reason: string,
+): ReactSemanticHandoffBuildResult {
+  return { ok: false, rejection: { code, reason } };
+}
+
+function exactAnchor(
+  anchor: ReactSourceAnchor,
+  index: number,
+): ExactReactSourceAnchor | ReactSemanticHandoffBuildResult {
+  const relPath = safeRelativePath(anchor.relPath);
+  const sourceFile = safeRelativePath(anchor.sourceFile);
+  const canonicalPath = relPath ?? sourceFile;
+  if (!canonicalPath) {
+    if (anchor.relPath || anchor.sourceFile) {
+      return anchorFailure(
+        "unsafe-source-path",
+        `Source anchor ${index + 1} does not include a safe project-relative path.`,
+      );
+    }
+    return anchorFailure(
+      "missing-source-provenance",
+      `Source anchor ${index + 1} is missing file provenance.`,
+    );
+  }
+  if (
+    !Number.isInteger(anchor.line) ||
+    !Number.isInteger(anchor.column) ||
+    (anchor.line ?? 0) < 1 ||
+    (anchor.column ?? 0) < 1
+  ) {
+    return anchorFailure(
+      "invalid-source-location",
+      `Source anchor ${index + 1} requires positive line and column coordinates.`,
+    );
+  }
+  const id = bounded(anchor.id, MAX_ID_LENGTH) ?? `source-${index + 1}`;
+  return {
+    id,
+    relPath: canonicalPath,
+    // Never forward an absolute jsxDEV/Fiber path. The verified root-relative
+    // path is exact for the bridge and safe to include in an agent prompt.
+    sourceFile: sourceFile ?? canonicalPath,
+    line: anchor.line!,
+    column: anchor.column!,
+    ...(bounded(anchor.component, MAX_COMPONENT_LENGTH)
+      ? { component: bounded(anchor.component, MAX_COMPONENT_LENGTH) }
+      : {}),
+    runtimeMultiplicity:
+      Number.isInteger(anchor.runtimeMultiplicity) &&
+      (anchor.runtimeMultiplicity ?? 0) > 0
+        ? anchor.runtimeMultiplicity!
+        : 1,
+    ...(bounded(anchor.reason, MAX_REASON_LENGTH)
+      ? { reason: bounded(anchor.reason, MAX_REASON_LENGTH) }
+      : {}),
+    scope: anchor.scope ?? "unknown",
+  };
+}
+
+function inferredDeterministicRejection(
+  anchors: readonly ExactReactSourceAnchor[],
+): DeterministicWritebackRejection {
+  if (
+    anchors.some((anchor) => anchor.scope === "shared-component-definition")
+  ) {
+    return {
+      code: "shared-component-scope",
+      reason:
+        "The runtime node resolves to a shared component definition, so the coding agent must inspect call sites and confirm the intended instance scope.",
+    };
+  }
+  if (
+    anchors.some(
+      (anchor) =>
+        anchor.scope === "repeated-render" || anchor.runtimeMultiplicity > 1,
+    )
+  ) {
+    return {
+      code: "repeated-runtime-render",
+      reason:
+        "More than one runtime node resolves to the same source anchor, so a deterministic per-instance source edit would be unsafe.",
+    };
+  }
+  return {
+    code: "semantic-source-change",
+    reason:
+      "This operation changes React program structure and requires the coding agent to inspect component and control-flow semantics.",
+  };
+}
+
+/**
+ * Build a bounded, path-redacted context packet for the coding agent.
+ * Validation failures never echo an unsafe path back to the caller.
+ */
+export function buildReactSemanticHandoff(
+  input: BuildReactSemanticHandoffInput,
+): ReactSemanticHandoffBuildResult {
+  if (
+    input.sourceAnchors.length === 0 ||
+    input.sourceAnchors.length > MAX_SOURCE_ANCHORS ||
+    (input.versionHashes?.length ?? 0) > MAX_VERSION_HASHES
+  ) {
+    return anchorFailure(
+      "context-limit-exceeded",
+      `Semantic handoff requires 1-${MAX_SOURCE_ANCHORS} anchors and at most ${MAX_VERSION_HASHES} version hashes.`,
+    );
+  }
+
+  const sourceAnchors: ExactReactSourceAnchor[] = [];
+  for (const [index, inputAnchor] of input.sourceAnchors.entries()) {
+    const anchor = exactAnchor(inputAnchor, index);
+    if ("ok" in anchor) return anchor;
+    sourceAnchors.push(anchor);
+  }
+  const anchorIds = new Set(sourceAnchors.map((anchor) => anchor.id));
+  if (anchorIds.size !== sourceAnchors.length) {
+    return anchorFailure(
+      "duplicate-anchor-id",
+      "Every source anchor in a semantic handoff must have a unique id.",
+    );
+  }
+
+  const subjectAnchorIds = input.runtimeRelationship.subjectAnchorIds.map(
+    (id) => bounded(id, MAX_ID_LENGTH) ?? "",
+  );
+  const targetAnchorId = bounded(
+    input.runtimeRelationship.targetAnchorId,
+    MAX_ID_LENGTH,
+  );
+  if (
+    subjectAnchorIds.length === 0 ||
+    subjectAnchorIds.some((id) => !id || !anchorIds.has(id)) ||
+    (targetAnchorId !== undefined && !anchorIds.has(targetAnchorId))
+  ) {
+    return anchorFailure(
+      "invalid-runtime-relationship",
+      "Runtime relationships must reference ids present in the bounded source anchor list.",
+    );
+  }
+
+  const versionHashes: ReactSourceVersionHash[] = [];
+  for (const entry of input.versionHashes ?? []) {
+    const relPath = safeRelativePath(entry.relPath);
+    if (!relPath) {
+      return anchorFailure(
+        "unsafe-source-path",
+        "A version hash entry does not include a safe project-relative path.",
+      );
+    }
+    versionHashes.push({
+      relPath,
+      versionHash: entry.versionHash.trim().slice(0, 256),
+    });
+  }
+
+  const inferredRejection = inferredDeterministicRejection(sourceAnchors);
+  const requestedRejection = input.deterministicRejection;
+  const deterministicWritebackRejection = requestedRejection
+    ? {
+        code: requestedRejection.code,
+        reason:
+          bounded(requestedRejection.reason, MAX_REASON_LENGTH) ??
+          inferredRejection.reason,
+      }
+    : inferredRejection;
+
+  return {
+    ok: true,
+    handoff: {
+      version: 1,
+      executionMode: "coding-agent",
+      operation: input.operation,
+      desiredChange:
+        bounded(input.desiredChange, MAX_DESIRED_CHANGE_LENGTH) ??
+        "Apply the described live canvas change to the React source.",
+      sourceAnchors,
+      runtimeRelationship: {
+        kind: input.runtimeRelationship.kind,
+        subjectAnchorIds,
+        ...(targetAnchorId ? { targetAnchorId } : {}),
+        ...(bounded(input.runtimeRelationship.screenId, MAX_SCREEN_ID_LENGTH)
+          ? {
+              screenId: bounded(
+                input.runtimeRelationship.screenId,
+                MAX_SCREEN_ID_LENGTH,
+              ),
+            }
+          : {}),
+        ...(bounded(
+          input.runtimeRelationship.sourceScreenId,
+          MAX_SCREEN_ID_LENGTH,
+        )
+          ? {
+              sourceScreenId: bounded(
+                input.runtimeRelationship.sourceScreenId,
+                MAX_SCREEN_ID_LENGTH,
+              ),
+            }
+          : {}),
+        ...(bounded(
+          input.runtimeRelationship.targetScreenId,
+          MAX_SCREEN_ID_LENGTH,
+        )
+          ? {
+              targetScreenId: bounded(
+                input.runtimeRelationship.targetScreenId,
+                MAX_SCREEN_ID_LENGTH,
+              ),
+            }
+          : {}),
+        ...(bounded(
+          input.runtimeRelationship.description,
+          MAX_DESCRIPTION_LENGTH,
+        )
+          ? {
+              description: bounded(
+                input.runtimeRelationship.description,
+                MAX_DESCRIPTION_LENGTH,
+              ),
+            }
+          : {}),
+      },
+      versionHashes,
+      deterministicWritebackRejection,
+      executionContract: {
+        requiresHumanWriteConsent: true,
+        requiresReadBeforeWrite: true,
+        requiresExpectedVersionHash: true,
+        allowsBlindOverwrite: false,
+        allowsGenericAstStructureTransform: false,
+        preservePreviewUntilHmrConfirmation: true,
+        onVersionConflict: "re-read-and-replan",
+      },
+      instructions: [
+        "Read every target file and verify each source anchor against the surrounding React control flow before editing.",
+        "Use semantic source edits; do not apply a generic AST reparent, group, or wrapper transform.",
+        "Obtain human write consent and write through the local bridge with expectedVersionHash from the corresponding read and requireExpectedVersionHash: true.",
+        "If a version hash conflicts, re-read the source and re-plan instead of overwriting it.",
+        "Keep the live preview pending until HMR renders and confirms the intended runtime relationship.",
+      ],
+    },
+  };
+}
+
+/** Build the safe coding-agent packet for a runtime Layers-panel move that a
+ * screen-scoped StructureMove bridge cannot execute. Both runtime endpoints
+ * must already have exact compiler provenance; the generic builder rejects
+ * either missing/unsafe anchor rather than guessing from a selector. */
+export function buildRuntimeReactStructureMoveHandoff(
+  input: BuildRuntimeReactStructureMoveHandoffInput,
+): ReactSemanticHandoffBuildResult {
+  const sourceScreenId = bounded(input.sourceScreenId, MAX_SCREEN_ID_LENGTH);
+  const targetScreenId = bounded(input.targetScreenId, MAX_SCREEN_ID_LENGTH);
+  if (!sourceScreenId || !targetScreenId) {
+    return anchorFailure(
+      "invalid-runtime-relationship",
+      "Cross-screen runtime structure moves require exact source and target screen ids.",
+    );
+  }
+  const subjectAnchor = { ...input.subjectAnchor, id: "subject" };
+  const targetAnchor = { ...input.targetAnchor, id: "target" };
+  const operation = input.placement === "inside" ? "reparent" : "move";
+  return buildReactSemanticHandoff({
+    operation,
+    desiredChange:
+      input.placement === "inside"
+        ? `Move the runtime React subject from screen "${sourceScreenId}" inside the exact target anchor in screen "${targetScreenId}" while preserving the intended visual order and behavior.`
+        : `Move the runtime React subject from screen "${sourceScreenId}" ${input.placement} the exact target anchor in screen "${targetScreenId}" while preserving the intended visual order and behavior.`,
+    sourceAnchors: [subjectAnchor, targetAnchor],
+    runtimeRelationship: {
+      kind: input.placement,
+      subjectAnchorIds: ["subject"],
+      targetAnchorId: "target",
+      // Keep the legacy singular field pointed at the destination while also
+      // carrying both endpoints explicitly for cross-screen execution.
+      screenId: targetScreenId,
+      sourceScreenId,
+      targetScreenId,
+      description: `Runtime React ${operation} from screen "${sourceScreenId}" to screen "${targetScreenId}" with placement "${input.placement}". Verify both exact source anchors and their surrounding control flow before editing either file.`,
+    },
+    versionHashes: [],
+  });
+}
+
+/** Build the safe coding-agent packet for a runtime-only layer state toggle.
+ * The exact JSX host element receives durable source metadata which survives
+ * HMR and is preserved by the runtime Layers snapshot. This is deliberately a
+ * semantic handoff: compiler provenance identifies the opening element, but no
+ * generic AST transform is authorized to mutate the source. */
+export function buildRuntimeReactLayerStateHandoff(
+  input: BuildRuntimeReactLayerStateHandoffInput,
+): ReactSemanticHandoffBuildResult {
+  const screenId = bounded(input.screenId, MAX_SCREEN_ID_LENGTH);
+  if (!screenId) {
+    return anchorFailure(
+      "invalid-runtime-relationship",
+      "Runtime layer state changes require an exact owning screen id.",
+    );
+  }
+
+  const attributeName = `data-agent-native-${input.state}`;
+  const subjectAnchor = { ...input.subjectAnchor, id: "subject" };
+  const desiredChange = input.enabled
+    ? `Set ${attributeName}="true" on the exact JSX host element for this runtime layer. Keep it as durable source metadata; do not replace it with a transient DOM mutation, CSS-only workaround, or wrapper.`
+    : `Remove the ${attributeName} attribute from the exact JSX host element for this runtime layer. Do not replace it with a transient DOM mutation, CSS-only workaround, or wrapper.`;
+
+  return buildReactSemanticHandoff({
+    operation: "set-layer-state",
+    desiredChange,
+    sourceAnchors: [subjectAnchor],
+    runtimeRelationship: {
+      kind: "metadata",
+      subjectAnchorIds: ["subject"],
+      screenId,
+      sourceScreenId: screenId,
+      targetScreenId: screenId,
+      description: `${input.enabled ? "Set" : "Clear"} runtime React layer state "${input.state}" using the durable ${attributeName} JSX attribute in screen "${screenId}".`,
+    },
+    versionHashes: [],
+  });
+}
diff --git a/templates/design/app/pages/design-editor/runtime-layer-state-handoff.spec.ts b/templates/design/app/pages/design-editor/runtime-layer-state-handoff.spec.ts
new file mode 100644
index 0000000000..67d5d1a0d9
--- /dev/null
+++ b/templates/design/app/pages/design-editor/runtime-layer-state-handoff.spec.ts
@@ -0,0 +1,62 @@
+import { readFileSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+const editorSource = readFileSync(
+  new URL("../DesignEditor.tsx", import.meta.url),
+  "utf8",
+);
+
+function sourceSection(start: string, end: string): string {
+  const startIndex = editorSource.indexOf(start);
+  const endIndex = editorSource.indexOf(end, startIndex + start.length);
+  expect(startIndex).toBeGreaterThanOrEqual(0);
+  expect(endIndex).toBeGreaterThan(startIndex);
+  return editorSource.slice(startIndex, endIndex);
+}
+
+describe("DesignEditor runtime layer state handoff", () => {
+  it.each([
+    [
+      "locked",
+      "const handleToggleLayerLocked",
+      "const handleToggleLayerHidden",
+    ],
+    [
+      "hidden",
+      "const handleToggleLayerHidden",
+      "const handleToggleHiddenForSelection",
+    ],
+  ] as const)(
+    "routes runtime-only %s toggles through the semantic handoff before applying the optimistic state",
+    (state, start, end) => {
+      const section = sourceSection(start, end);
+      const handoffCall = `sendRuntimeLayerStateSemanticHandoff(layerId, "${state}", ${state})`;
+
+      expect(section).toContain("if (owner?.runtimeOnly)");
+      expect(section).toContain(handoffCall);
+      expect(section).toContain("layerStateOverridesRef.current.set(layerId");
+      expect(section.indexOf(handoffCall)).toBeLessThan(
+        section.indexOf("layerStateOverridesRef.current.set(layerId"),
+      );
+      expect(section).not.toMatch(
+        /if \(owner\?\.runtimeOnly\) \{\s*return;\s*\}/,
+      );
+    },
+  );
+
+  it("serializes the exact-anchor, consented CAS/HMR contract into the agent prompt", () => {
+    const section = sourceSection(
+      "const sendRuntimeLayerStateSemanticHandoff",
+      "// Wrap the current multi-layer selection",
+    );
+
+    expect(section).toContain("buildRuntimeReactLayerStateHandoff");
+    expect(section).toContain("reactSourceAnchorForPendingEdit");
+    expect(section).toContain("expectedVersionHash");
+    expect(section).toContain("requireExpectedVersionHash: true");
+    expect(section).toContain("human write consent");
+    expect(section).toContain("HMR confirms the source metadata");
+    expect(section).toContain("Never apply a generic AST transform");
+  });
+});
diff --git a/templates/design/app/pages/design-editor/screen-auto-layout.test.ts b/templates/design/app/pages/design-editor/screen-auto-layout.test.ts
new file mode 100644
index 0000000000..cf50472aa8
--- /dev/null
+++ b/templates/design/app/pages/design-editor/screen-auto-layout.test.ts
@@ -0,0 +1,95 @@
+import { buildCodeLayerProjection } from "@shared/code-layer";
+import { describe, expect, it } from "vitest";
+
+import {
+  enableInlineScreenAutoLayout,
+  getRuntimeScreenAutoLayoutSubjectIds,
+  resolveInlineScreenAutoLayoutRoot,
+} from "./screen-auto-layout";
+
+describe("screen auto layout", () => {
+  it("enables auto layout on an authored body without disturbing Alpine directives", () => {
+    const content = `<!doctype html>
+      <html>
+        <body x-data="{ open: true }" style="width:320px;height:200px">
+          <section x-show="open" style="position:absolute;left:12px;top:16px;width:80px;height:40px">Alpha</section>
+          <section style="position:absolute;left:112px;top:16px;width:80px;height:40px">Beta</section>
+        </body>
+      </html>`;
+
+    const result = enableInlineScreenAutoLayout({
+      content,
+      width: 320,
+      height: 200,
+    });
+
+    expect(result.status).toBe("applied");
+    expect(result.content).toContain('x-data="{ open: true }"');
+    expect(result.content).toContain('x-show="open"');
+    const projection = buildCodeLayerProjection(result.content);
+    const body = projection.nodes.find((node) => node.tag === "body");
+    expect(body?.style.display).toBe("flex");
+    expect(body?.style["flex-direction"]).toBe("row");
+    expect(body?.style.gap).toBe("20px");
+    expect(body?.style.padding).toBe("12px");
+    const nodes = new Map(projection.nodes.map((node) => [node.id, node]));
+    for (const childId of body?.children ?? []) {
+      const child = nodes.get(childId);
+      expect(child?.style.position).toBeUndefined();
+      expect(child?.style.left).toBeUndefined();
+      expect(child?.style.top).toBeUndefined();
+    }
+  });
+
+  it("uses one fragment root but rejects multiple roots instead of inventing a wrapper", () => {
+    const single = buildCodeLayerProjection(
+      `<main><section>Alpha</section></main>`,
+    );
+    expect(resolveInlineScreenAutoLayoutRoot(single)?.tag).toBe("main");
+
+    const multiple = buildCodeLayerProjection(
+      `<header>Header</header><main>Main</main>`,
+    );
+    expect(resolveInlineScreenAutoLayoutRoot(multiple)).toBeNull();
+    expect(
+      enableInlineScreenAutoLayout({
+        content: `<header>Header</header><main>Main</main>`,
+      }).status,
+    ).toBe("unsupported");
+  });
+
+  it("enables auto layout on an empty authored body", () => {
+    const result = enableInlineScreenAutoLayout({
+      content: `<!doctype html><html><body></body></html>`,
+    });
+    expect(result.status).toBe("applied");
+    expect(result.content).toContain("display: flex");
+    expect(result.content).toContain("flex-direction: row");
+  });
+
+  it("finds the shallowest sourced React roots below an unsourced mount node", () => {
+    const projection = buildCodeLayerProjection(`<!doctype html><html><body>
+      <div id="root">
+        <header data-agent-native-node-id="runtime-header" data-source-file="src/App.tsx" data-source-line="8" data-source-column="3">
+          <span data-agent-native-node-id="runtime-title" data-source-file="src/App.tsx" data-source-line="9" data-source-column="5">Title</span>
+        </header>
+        <main data-agent-native-node-id="runtime-main" data-source-file="src/App.tsx" data-source-line="12" data-source-column="3">Main</main>
+      </div>
+      <div id="portal"><div data-agent-native-node-id="runtime-dialog" data-source-file="src/Dialog.tsx" data-source-line="4" data-source-column="3">Dialog</div></div>
+    </body></html>`);
+
+    const nodes = new Map(projection.nodes.map((node) => [node.id, node]));
+    expect(
+      getRuntimeScreenAutoLayoutSubjectIds(projection).map(
+        (id) => nodes.get(id)?.dataAttributes["data-agent-native-node-id"],
+      ),
+    ).toEqual(["runtime-header", "runtime-main"]);
+  });
+
+  it("refuses runtime roots without exact compiler provenance", () => {
+    const projection = buildCodeLayerProjection(
+      `<html><body><div id="root"><main data-source-file="src/App.tsx" data-source-line="8">Main</main></div></body></html>`,
+    );
+    expect(getRuntimeScreenAutoLayoutSubjectIds(projection)).toEqual([]);
+  });
+});
diff --git a/templates/design/app/pages/design-editor/screen-auto-layout.ts b/templates/design/app/pages/design-editor/screen-auto-layout.ts
new file mode 100644
index 0000000000..108d7fc907
--- /dev/null
+++ b/templates/design/app/pages/design-editor/screen-auto-layout.ts
@@ -0,0 +1,169 @@
+import {
+  applyVisualEdit,
+  buildCodeLayerProjection,
+  type CodeLayerNode,
+  type CodeLayerProjection,
+} from "@shared/code-layer";
+
+import {
+  inferAutoLayoutFromChildren,
+  type AlignableRect,
+} from "./layout-operations";
+
+export type EnableInlineScreenAutoLayoutResult =
+  | {
+      status: "applied" | "unchanged";
+      content: string;
+      targetNodeId: string;
+      direction: "row" | "column";
+      gap: number;
+      padding: number;
+    }
+  | {
+      status: "unsupported" | "failed";
+      content: string;
+      message?: string;
+    };
+
+function nodeById(projection: CodeLayerProjection): Map<string, CodeLayerNode> {
+  return new Map(projection.nodes.map((node) => [node.id, node]));
+}
+
+/**
+ * A screen frame owns the authored document body. Fragment-only design files
+ * have no editable body in source, so a single visual root is the only safe
+ * equivalent. Multiple fragment roots would require inventing a wrapper and
+ * changing source structure, which is deliberately left to a semantic edit.
+ */
+export function resolveInlineScreenAutoLayoutRoot(
+  projection: CodeLayerProjection,
+): CodeLayerNode | null {
+  const body = projection.nodes.find((node) => node.tag === "body");
+  if (body) return body;
+
+  const nodes = nodeById(projection);
+  const roots = projection.rootNodeIds
+    .map((id) => nodes.get(id))
+    .filter((node): node is CodeLayerNode =>
+      Boolean(node && node.tag !== "html" && node.tag !== "head"),
+    );
+  return roots.length === 1 ? roots[0]! : null;
+}
+
+function finiteStyleNumber(value: string | undefined, fallback = 0): number {
+  const parsed = Number.parseFloat(value ?? "");
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function rectForNode(
+  node: CodeLayerNode,
+  fallback: { width?: number; height?: number } = {},
+): AlignableRect {
+  return {
+    id: node.id,
+    x: finiteStyleNumber(node.style.left),
+    y: finiteStyleNumber(node.style.top),
+    width: finiteStyleNumber(node.style.width, fallback.width ?? 0),
+    height: finiteStyleNumber(node.style.height, fallback.height ?? 0),
+  };
+}
+
+/** Deterministically enable auto layout on an inline HTML/Alpine screen root. */
+export function enableInlineScreenAutoLayout(args: {
+  content: string;
+  width?: number;
+  height?: number;
+}): EnableInlineScreenAutoLayoutResult {
+  const projection = buildCodeLayerProjection(args.content);
+  const target = resolveInlineScreenAutoLayoutRoot(projection);
+  if (!target) {
+    return { status: "unsupported", content: args.content };
+  }
+
+  const nodes = nodeById(projection);
+  const targetRect = rectForNode(target, {
+    width: args.width,
+    height: args.height,
+  });
+  const childRects = target.children
+    .map((childId) => nodes.get(childId))
+    .filter((node): node is CodeLayerNode => Boolean(node))
+    .map((node) => rectForNode(node));
+  const inferred = inferAutoLayoutFromChildren(targetRect, childRects);
+  const autoLayoutPatch = applyVisualEdit(args.content, {
+    kind: "autoLayout",
+    targetId: target.id,
+    enabled: true,
+    direction: inferred.direction,
+    gap: `${inferred.gap}px`,
+  });
+  if (autoLayoutPatch.result.status !== "applied") {
+    return {
+      status: "failed",
+      content: args.content,
+      message: autoLayoutPatch.result.message,
+    };
+  }
+
+  let content = autoLayoutPatch.content;
+  if (inferred.padding > 0) {
+    const paddingPatch = applyVisualEdit(content, {
+      kind: "style",
+      target: { nodeId: target.id },
+      property: "padding",
+      value: `${inferred.padding}px`,
+    });
+    if (paddingPatch.result.status === "applied") {
+      content = paddingPatch.content;
+    }
+  }
+
+  return {
+    status: content === args.content ? "unchanged" : "applied",
+    content,
+    targetNodeId: target.id,
+    ...inferred,
+  };
+}
+
+function hasExactReactProvenance(node: CodeLayerNode): boolean {
+  const sourceFile = node.dataAttributes["data-source-file"]?.trim();
+  const line = Number(node.dataAttributes["data-source-line"]);
+  const column = Number(node.dataAttributes["data-source-column"]);
+  return Boolean(
+    sourceFile &&
+    Number.isSafeInteger(line) &&
+    line > 0 &&
+    Number.isSafeInteger(column) &&
+    column > 0,
+  );
+}
+
+/**
+ * Resolve the shallowest compiler-provenanced React roots beneath the live
+ * screen body. Unsourced mount nodes such as `#root` are traversed, while
+ * later body branches (for example portals) are ignored once the primary app
+ * branch yields editable roots.
+ */
+export function getRuntimeScreenAutoLayoutSubjectIds(
+  projection: CodeLayerProjection,
+): string[] {
+  const nodes = nodeById(projection);
+  const collect = (nodeId: string, ancestors: Set<string>): string[] => {
+    if (ancestors.has(nodeId)) return [];
+    const node = nodes.get(nodeId);
+    if (!node) return [];
+    if (hasExactReactProvenance(node)) return [node.id];
+    const nextAncestors = new Set(ancestors);
+    nextAncestors.add(nodeId);
+    return node.children.flatMap((childId) => collect(childId, nextAncestors));
+  };
+
+  const body = projection.nodes.find((node) => node.tag === "body");
+  const branchIds = body?.children ?? projection.rootNodeIds;
+  for (const branchId of branchIds) {
+    const subjects = collect(branchId, new Set());
+    if (subjects.length > 0) return Array.from(new Set(subjects));
+  }
+  return [];
+}
diff --git a/templates/design/app/pages/design-editor/selection-state.spec.ts b/templates/design/app/pages/design-editor/selection-state.spec.ts
new file mode 100644
index 0000000000..c302879769
--- /dev/null
+++ b/templates/design/app/pages/design-editor/selection-state.spec.ts
@@ -0,0 +1,267 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getOverviewScreenContentKey,
+  hasSelectableCodeLayerParent,
+  isDocumentShellCodeLayerNode,
+  pendingEditTargetsSelectedElement,
+  resolveEscapePopSelectionAction,
+  shouldEscapeToOverview,
+} from "./selection-state";
+
+describe("getOverviewScreenContentKey", () => {
+  it("keeps inline overview identity stable across active switch, content edits, and revision bumps", () => {
+    const before = getOverviewScreenContentKey({
+      screenId: "screen-a",
+      screenIsActive: true,
+      contentRenderRevision: 2,
+      updatedAt: "before",
+      content: "<main>before</main>",
+      useRuntimeReplacement: true,
+    });
+    const after = getOverviewScreenContentKey({
+      screenId: "screen-a",
+      screenIsActive: false,
+      contentRenderRevision: 99,
+      updatedAt: "after",
+      content: "<main>after</main>",
+      useRuntimeReplacement: true,
+    });
+
+    expect(before).toBe("screen-a:inline-overview");
+    expect(after).toBe(before);
+  });
+
+  it("retains the remount fallback for overview sources without runtime replacement", () => {
+    const before = getOverviewScreenContentKey({
+      screenId: "screen-a",
+      screenIsActive: false,
+      contentRenderRevision: 0,
+      updatedAt: "before",
+      content: "before",
+      useRuntimeReplacement: false,
+    });
+    const after = getOverviewScreenContentKey({
+      screenId: "screen-a",
+      screenIsActive: false,
+      contentRenderRevision: 0,
+      updatedAt: "after",
+      content: "after",
+      useRuntimeReplacement: false,
+    });
+    expect(after).not.toBe(before);
+  });
+});
+
+describe("resolveEscapePopSelectionAction", () => {
+  it("pops to the parent layer when the selected layer has a code-layer parent", () => {
+    expect(
+      resolveEscapePopSelectionAction({
+        hasSelectedLayer: true,
+        hasLayerParent: true,
+        viewMode: "single",
+      }),
+    ).toEqual({ kind: "pop-to-parent-layer" });
+
+    expect(
+      resolveEscapePopSelectionAction({
+        hasSelectedLayer: true,
+        hasLayerParent: true,
+        viewMode: "overview",
+      }),
+    ).toEqual({ kind: "pop-to-parent-layer" });
+  });
+
+  it("pops a top-level (parentless) selected layer to its screen/frame in overview mode", () => {
+    expect(
+      resolveEscapePopSelectionAction({
+        hasSelectedLayer: true,
+        hasLayerParent: false,
+        viewMode: "overview",
+      }),
+    ).toEqual({ kind: "pop-to-screen-frame" });
+  });
+
+  it("deselects a top-level selected layer in single-screen mode (no separate frame to pop to)", () => {
+    expect(
+      resolveEscapePopSelectionAction({
+        hasSelectedLayer: true,
+        hasLayerParent: false,
+        viewMode: "single",
+      }),
+    ).toEqual({ kind: "deselect" });
+  });
+
+  it("deselects when nothing is selected, regardless of view mode", () => {
+    expect(
+      resolveEscapePopSelectionAction({
+        hasSelectedLayer: false,
+        hasLayerParent: false,
+        viewMode: "single",
+      }),
+    ).toEqual({ kind: "deselect" });
+    expect(
+      resolveEscapePopSelectionAction({
+        hasSelectedLayer: false,
+        hasLayerParent: false,
+        viewMode: "overview",
+      }),
+    ).toEqual({ kind: "deselect" });
+  });
+});
+
+describe("isDocumentShellCodeLayerNode", () => {
+  it("treats <body>/<html> nodes named purely from their tag as document shell nodes", () => {
+    expect(
+      isDocumentShellCodeLayerNode({ tag: "body", layerNameSource: "tag" }),
+    ).toBe(true);
+    expect(
+      isDocumentShellCodeLayerNode({ tag: "html", layerNameSource: "tag" }),
+    ).toBe(true);
+  });
+
+  it("does not treat a body/html node with a more specific layer name as a shell node", () => {
+    // e.g. a <body data-agent-native-layer-name="Screen root"> — an explicit
+    // rename means it should stay selectable like any other layer.
+    expect(
+      isDocumentShellCodeLayerNode({
+        tag: "body",
+        layerNameSource: "attribute",
+      }),
+    ).toBe(false);
+  });
+
+  it("does not treat non-shell tags as document shell nodes", () => {
+    expect(
+      isDocumentShellCodeLayerNode({ tag: "div", layerNameSource: "tag" }),
+    ).toBe(false);
+  });
+});
+
+describe("hasSelectableCodeLayerParent", () => {
+  it("is false when there is no parent node at all", () => {
+    expect(hasSelectableCodeLayerParent({ parentNode: undefined })).toBe(false);
+    expect(hasSelectableCodeLayerParent({ parentNode: null })).toBe(false);
+  });
+
+  it("is false when the parent resolves to a collapsed document-shell node (BUG-ESCAPE-SHELL fail-before case)", () => {
+    // Before the fix: a top-level layer's parentId still resolves to <body>
+    // in the flat ownership map, and callers used a bare
+    // Boolean(parentNode) check — which is true here — treating <body> as a
+    // selectable parent layer. That is exactly the case that let Escape and
+    // Shift+Enter walk into <body>/<html>.
+    expect(
+      hasSelectableCodeLayerParent({
+        parentNode: { tag: "body", layerNameSource: "tag" },
+      }),
+    ).toBe(false);
+    expect(
+      hasSelectableCodeLayerParent({
+        parentNode: { tag: "html", layerNameSource: "tag" },
+      }),
+    ).toBe(false);
+  });
+
+  it("is true for a real, non-shell parent layer", () => {
+    expect(
+      hasSelectableCodeLayerParent({
+        parentNode: { tag: "div", layerNameSource: "semantic" },
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("pendingEditTargetsSelectedElement", () => {
+  it("matches by sourceId when both edit and selection carry one", () => {
+    expect(
+      pendingEditTargetsSelectedElement({
+        editSourceId: "node-1",
+        editSelector: ".stale-selector",
+        selectedSourceId: "node-1",
+        selectedSelector: ".different-selector",
+      }),
+    ).toBe(true);
+  });
+
+  it("does not match a different sourceId even if selectors coincidentally match", () => {
+    expect(
+      pendingEditTargetsSelectedElement({
+        editSourceId: "node-1",
+        editSelector: ".same",
+        selectedSourceId: "node-2",
+        selectedSelector: ".same",
+      }),
+    ).toBe(false);
+  });
+
+  it("falls back to selector matching when the edit carries no sourceId", () => {
+    expect(
+      pendingEditTargetsSelectedElement({
+        editSourceId: null,
+        editSelector: ".card",
+        selectedSourceId: undefined,
+        selectedSelector: ".card",
+      }),
+    ).toBe(true);
+  });
+
+  it("does not match when neither sourceId nor selector line up", () => {
+    expect(
+      pendingEditTargetsSelectedElement({
+        editSourceId: null,
+        editSelector: ".card",
+        selectedSourceId: "node-3",
+        selectedSelector: ".other",
+      }),
+    ).toBe(false);
+  });
+
+  it("does not match against no current selection", () => {
+    expect(
+      pendingEditTargetsSelectedElement({
+        editSourceId: "node-1",
+        editSelector: ".card",
+        selectedSourceId: null,
+        selectedSelector: null,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("shouldEscapeToOverview", () => {
+  const base = {
+    activeTool: "move" as const,
+    drawMode: false,
+    mode: "edit" as const,
+    pinMode: false,
+    selectedElement: null,
+    viewMode: "single" as const,
+  };
+
+  it("is true only in single mode, edit mode, move tool, with nothing selected/drawing/pinning", () => {
+    expect(shouldEscapeToOverview(base)).toBe(true);
+  });
+
+  it("is false in overview mode", () => {
+    expect(shouldEscapeToOverview({ ...base, viewMode: "overview" })).toBe(
+      false,
+    );
+  });
+
+  it("is false when something is selected", () => {
+    expect(
+      shouldEscapeToOverview({
+        ...base,
+        selectedElement: {
+          sourceId: "n1",
+          selector: ".card",
+        } as unknown as (typeof base)["selectedElement"],
+      }),
+    ).toBe(false);
+  });
+
+  it("is false while drawing or pinning", () => {
+    expect(shouldEscapeToOverview({ ...base, drawMode: true })).toBe(false);
+    expect(shouldEscapeToOverview({ ...base, pinMode: true })).toBe(false);
+  });
+});
diff --git a/templates/design/app/pages/design-editor/selection-state.ts b/templates/design/app/pages/design-editor/selection-state.ts
index 84f00b1cc0..76a066b54a 100644
--- a/templates/design/app/pages/design-editor/selection-state.ts
+++ b/templates/design/app/pages/design-editor/selection-state.ts
@@ -46,6 +46,33 @@ export function getOverviewScreenRuntimeReplacementKey({
   return [screenId, updatedAt ?? "", getContentSignature(content)].join(":");
 }
 
+/** Keep inline overview iframe identity stable across active-screen switches
+ * and content/history updates. Inline overview screens have the bridge-backed
+ * full-document replacement channel, so content changes belong in
+ * `runtimeReplacementKey`, never in the iframe's srcdoc identity key. Other
+ * source types retain the legacy remount fallback because they may not expose
+ * an in-place document replacement bridge. */
+export function getOverviewScreenContentKey({
+  screenId,
+  screenIsActive,
+  contentRenderRevision,
+  updatedAt,
+  content,
+  useRuntimeReplacement,
+}: {
+  screenId: string;
+  screenIsActive: boolean;
+  contentRenderRevision: number;
+  updatedAt?: string | null;
+  content: string;
+  useRuntimeReplacement: boolean;
+}): string {
+  if (useRuntimeReplacement) return `${screenId}:inline-overview`;
+  return screenIsActive
+    ? [screenId, contentRenderRevision].join(":")
+    : [screenId, updatedAt ?? "", getContentSignature(content), 0].join(":");
+}
+
 export function shouldUseOverviewRuntimeReplacement({
   sourceType,
   externalSnapshotHtml,
@@ -84,6 +111,38 @@ export function sameStringIds(a: string[], b: string[]) {
   return a.length === b.length && a.every((value, index) => value === b[index]);
 }
 
+/**
+ * Undo/redo inspector-panel resync — decides whether a pending live edit
+ * being reverted/replayed (by handleUndo's pendingStyleUndo/
+ * pendingNonStyleUndo branches, or handleRedo's pendingTextRedo/
+ * pendingLiveRedo branches) targets the SAME element as the current
+ * `selectedElement`. Undo/redo aren't guaranteed to be undoing the
+ * currently-selected element (the user may have re-selected something else
+ * since the edit was made), so the panel should only be patched with the
+ * revert/redo payload when this returns true — otherwise a background
+ * undo would incorrectly clobber whatever the user has selected right now.
+ * Matches by sourceId when BOTH sides carry one (the stable, authoritative
+ * identity across re-renders) — a sourceId mismatch there means a different
+ * element even if their selectors coincidentally collide (e.g. repeated
+ * list items sharing one CSS selector). Falls back to the CSS selector only
+ * when a sourceId comparison isn't possible on at least one side.
+ *
+ * Exported for unit testing.
+ */
+export function pendingEditTargetsSelectedElement(args: {
+  editSourceId?: string | null;
+  editSelector: string;
+  selectedSourceId?: string | null;
+  selectedSelector?: string | null;
+}): boolean {
+  if (args.editSourceId && args.selectedSourceId) {
+    return args.selectedSourceId === args.editSourceId;
+  }
+  return Boolean(
+    args.selectedSelector && args.selectedSelector === args.editSelector,
+  );
+}
+
 export function isScreenRootElementInfo(info: ElementInfo | null | undefined) {
   const tagName = info?.tagName?.toUpperCase();
   return tagName === "BODY" || tagName === "HTML";
@@ -104,13 +163,29 @@ export function shouldIgnoreOverviewLayerCreationEcho(args: {
   pendingScreenId: string | null | undefined;
   screenId: string;
   info?: ElementInfo | null;
+  resolvedLayerId?: string | null;
   event: "select" | "clear";
 }) {
   if (!args.pendingLayerId) return false;
   if (args.pendingScreenId && args.pendingScreenId !== args.screenId) {
     return false;
   }
-  return args.event === "clear" || isScreenRootElementInfo(args.info);
+  if (args.event === "clear" || isScreenRootElementInfo(args.info)) {
+    return true;
+  }
+  // Layers-panel selection is applied optimistically in the host, then the
+  // selected selector is mirrored into the overview iframe. The bridge echoes
+  // that exact layer back as an ordinary element-select a frame later. Without
+  // recognizing the matching id here, a Cmd/Ctrl toggle or Shift range briefly
+  // renders the correct multi-selection and is then collapsed to the echoed
+  // primary layer. Only ignore the exact pending layer; a real canvas click on
+  // any other element must still replace the panel selection immediately.
+  const echoedLayerId =
+    args.info?.sourceId ?? args.info?.id ?? args.info?.pendingNodeId;
+  return (
+    args.resolvedLayerId === args.pendingLayerId ||
+    echoedLayerId === args.pendingLayerId
+  );
 }
 
 export function getSelectedScreenIdsForEditorState(args: {
@@ -291,6 +366,99 @@ export function shouldEscapeToOverview(args: {
   );
 }
 
+/**
+ * A node's `parentId` in the FLAT code-layer ownership map
+ * (`codeLayerOwnerByNodeId` / `codeLayerOwnerByNodeIdRef` in DesignEditor.tsx)
+ * still points at `<html>`/`<body>` even though the VISUAL layers tree
+ * collapses those document-shell nodes away (see shared/code-layer.ts's
+ * `isCollapsibleDocumentShellNode` / `compactCodeLayerTreeNodes`) — the flat
+ * map is built straight from `projection.nodes`, which is never filtered.
+ * Mirrors `isCollapsibleDocumentShellNode`'s own check (tag is html/body AND
+ * the layer name came from the tag itself, i.e. nothing more specific named
+ * it) against the flat `CodeLayerNode`'s own fields directly, since the flat
+ * node already carries `tag`/`layerNameSource` without needing a separate
+ * lookup map.
+ *
+ * Both the Escape pop-one-level walk (`resolveEscapePopSelectionAction`) and
+ * the shared Shift+Enter / "\\" select-parent walk (`handleSelectParentLayer`
+ * in DesignEditor.tsx) must treat a parent that resolves to a document-shell
+ * node as NO parent at all — otherwise popping from a top-level layer selects
+ * the raw `<body>`/`<html>` DOM nodes instead of stopping at the screen/frame
+ * level (or fully deselecting), which produces a permanently broken 0x0
+ * inspector with no way back to a deselected state.
+ *
+ * Exported for unit testing.
+ */
+export function isDocumentShellCodeLayerNode(node: {
+  tag: string;
+  layerNameSource: string;
+}): boolean {
+  return (
+    (node.tag === "html" || node.tag === "body") &&
+    node.layerNameSource === "tag"
+  );
+}
+
+/**
+ * True only when `parentNode` exists AND is not a document-shell node — see
+ * `isDocumentShellCodeLayerNode`. Callers walking the flat code-layer
+ * ownership map (Escape pop-one-level, Shift+Enter select-parent) must use
+ * this instead of a bare `Boolean(parentNode)` truthiness check, or a
+ * top-level layer's collapsed `<body>`/`<html>` ancestor gets treated as a
+ * selectable parent layer.
+ *
+ * Exported for unit testing.
+ */
+export function hasSelectableCodeLayerParent(args: {
+  parentNode: { tag: string; layerNameSource: string } | null | undefined;
+}): boolean {
+  return (
+    args.parentNode != null && !isDocumentShellCodeLayerNode(args.parentNode)
+  );
+}
+
+export type EscapePopSelectionAction =
+  | { kind: "pop-to-parent-layer" }
+  | { kind: "pop-to-screen-frame" }
+  | { kind: "deselect" };
+
+/**
+ * Figma parity — Escape on a plain canvas selection pops one level at a
+ * time (child layer -> parent layer -> containing screen/frame -> fully
+ * deselected) instead of deselecting everything on the first press.
+ *
+ * - A selected layer that has a code-layer parent (`hasLayerParent`) pops to
+ *   that parent, reusing the same ancestor-walk `handleSelectParentLayer`
+ *   (Shift+Enter / "\\") already uses via `codeLayerOwnerByNodeIdRef`.
+ * - A selected TOP-level layer (no code-layer parent) in overview mode pops
+ *   to selecting its containing screen/frame — the same selection kind
+ *   (`overviewSelectedScreenIds`) clicking a frame directly in overview
+ *   already produces.
+ * - Anything else — nothing selected, or a top-level layer in single-screen
+ *   mode where there's no separate "frame" to pop to (the screen already
+ *   fills the view, so top-level already reads as "the frame boundary") —
+ *   falls straight through to a full deselect, matching the previous
+ *   unconditional Escape behavior.
+ *
+ * Callers must have already handled every higher-priority Escape consumer
+ * (an in-progress marquee/drag, an active breakpoint edit target,
+ * `shouldEscapeToOverview`'s zoom-out-to-overview case) before calling this
+ * — it only decides the remaining plain-canvas-selection case.
+ *
+ * Exported for unit testing.
+ */
+export function resolveEscapePopSelectionAction(args: {
+  hasSelectedLayer: boolean;
+  hasLayerParent: boolean;
+  viewMode: "single" | "overview";
+}): EscapePopSelectionAction {
+  if (args.hasSelectedLayer) {
+    if (args.hasLayerParent) return { kind: "pop-to-parent-layer" };
+    if (args.viewMode === "overview") return { kind: "pop-to-screen-frame" };
+  }
+  return { kind: "deselect" };
+}
+
 /**
  * B5-1: an empty-canvas click (a marquee/hit-test that resolved to zero
  * elements) must deselect ANY current selection kind — a selected
@@ -315,6 +483,38 @@ export function shouldClearBridgeSelectionOnEmptyMarquee(args: {
   return args.resolvedCount === 0 && !args.additive;
 }
 
+/**
+ * PICK-RACE: MultiScreenCanvas's `onPick` prop is `(id: string) => void` — no
+ * modifier/event info — even though a shift-click there already toggled a
+ * full multi-id array internally (handleFrameClick's own `selectedIds`
+ * state) before calling `onPick` with just the resulting PRIMARY id. That
+ * full array only reaches DesignEditor a render later, via the
+ * `onScreenSelectionChange` effect (MultiScreenCanvas reports its
+ * `selectedIds` from a `useEffect` that commits after this synchronous
+ * `onPick` call already ran).
+ *
+ * Forcing `selectedLayerIdsState` down to `[pickedId]` in
+ * `handleOverviewScreenPick` is wrong for BOTH shift-click cases: adding a
+ * screen would drop every other already-selected screen, and removing one
+ * would replace the whole array with just the new primary — there is no way
+ * to reconstruct the correct multi-id array from a single id. So: while
+ * Shift is held, this returns the CURRENT selection unchanged instead of a
+ * wrong singleton, and lets `overviewSelectedScreenIds` (which the
+ * `selectedLayerIds` derivation already prefers whenever non-empty) be the
+ * sole source of truth once that effect settles. When Shift isn't held this
+ * is a plain single-screen pick, matching the previous unconditional
+ * behavior.
+ *
+ * Exported for unit testing.
+ */
+export function computeOverviewScreenPickSelectionIds(args: {
+  pickedId: string;
+  shiftKeyHeld: boolean;
+  currentSelectedLayerIds: string[];
+}): string[] {
+  return args.shiftKeyHeld ? args.currentSelectedLayerIds : [args.pickedId];
+}
+
 /**
  * Build the set of all node ids (both projection ids and data-agent-native-node-id
  * attribute values) that exist in the given projection. Used by handleGroupSelection
diff --git a/templates/design/app/pages/design-editor/structure-drop-persistence.spec.ts b/templates/design/app/pages/design-editor/structure-drop-persistence.spec.ts
new file mode 100644
index 0000000000..c232222d59
--- /dev/null
+++ b/templates/design/app/pages/design-editor/structure-drop-persistence.spec.ts
@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+const editorSource = readFileSync(
+  new URL("../DesignEditor.tsx", import.meta.url),
+  "utf8",
+);
+
+describe("flow-to-absolute structure drop persistence", () => {
+  it("persists absolute-container positioning even when the source node began in flow", () => {
+    const absoluteDropBranches = editorSource.match(
+      /movedNodeAttrId && details\?\.dropMode === "absolute-container"/g,
+    );
+    expect(absoluteDropBranches).toHaveLength(2);
+
+    // Both active-screen and overview-screen handlers must apply the absolute
+    // style before consulting the old source node's positioning. This is what
+    // makes flow -> root/absolute-container survive reload instead of reverting
+    // after the bridge's optimistic DOM move.
+    for (const handlerName of [
+      "const handleVisualStructureChange",
+      "const handleScreenVisualStructureChange",
+    ]) {
+      const start = editorSource.indexOf(handlerName);
+      const next = editorSource.indexOf(
+        "const handle",
+        start + handlerName.length,
+      );
+      const section = editorSource.slice(start, next < 0 ? undefined : next);
+      const absoluteDropIndex = section.indexOf(
+        'details?.dropMode === "absolute-container"',
+      );
+      const oldPositionIndex = section.indexOf(
+        "isAbsoluteCodeLayerNode(targetNode)",
+      );
+      expect(absoluteDropIndex).toBeGreaterThanOrEqual(0);
+      expect(oldPositionIndex).toBeGreaterThan(absoluteDropIndex);
+      expect(section).toContain("setAbsolutePositioningForNodeInHtml(");
+      expect(section).toContain("removeAbsolutePositioningFromNodeInHtml(");
+      expect(section).toContain('details?.dropMode === "flow-insert"');
+      expect(section).toContain("details.forceFlowPositionOverride");
+      expect(section).toContain("setFlowPositioningOverrideForNodeInHtml(");
+    }
+  });
+
+  it("persists an important static override only for the explicit stylesheet fallback signal", () => {
+    const helperStart = editorSource.indexOf(
+      "function setFlowPositioningOverrideForNodeInHtml",
+    );
+    const helperEnd = editorSource.indexOf(
+      "function setAbsolutePositioningForNodeInHtml",
+      helperStart,
+    );
+    const helper = editorSource.slice(helperStart, helperEnd);
+    expect(helperStart).toBeGreaterThanOrEqual(0);
+    expect(helper).toContain(
+      'element.style.setProperty("position", "static", "important")',
+    );
+    expect(helper).toContain("ABS_POSITION_PROPS");
+  });
+
+  it("keeps the source update on the existing local history/optimistic-preview path", () => {
+    const start = editorSource.indexOf("const handleVisualStructureChange");
+    const end = editorSource.indexOf(
+      "const handleScreenVisualStructureChange",
+      start,
+    );
+    const section = editorSource.slice(start, end);
+
+    expect(section).toContain("applyLocalContentUpdate(");
+    expect(section).toContain("{ skipPreview: true }");
+    expect(section).not.toContain("recordHistory: false");
+  });
+});
diff --git a/templates/design/changelog/2026-07-09-added-underline-strikethrough-and-text-case-uppercase-lowerc.md b/templates/design/changelog/2026-07-09-added-underline-strikethrough-and-text-case-uppercase-lowerc.md
new file mode 100644
index 0000000000..870cc60367
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-added-underline-strikethrough-and-text-case-uppercase-lowerc.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+Typography properties now include underline, strikethrough, and text case controls.
diff --git a/templates/design/changelog/2026-07-09-annotate-now-draws-across-the-all-screens-canvas-without-swi.md b/templates/design/changelog/2026-07-09-annotate-now-draws-across-the-all-screens-canvas-without-swi.md
new file mode 100644
index 0000000000..4c684e92a8
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-annotate-now-draws-across-the-all-screens-canvas-without-swi.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Annotate now draws across the All Screens canvas without switching views or reloading screen previews.
diff --git a/templates/design/changelog/2026-07-09-auto-layout-children-can-now-be-dragged-into-freeform-screen.md b/templates/design/changelog/2026-07-09-auto-layout-children-can-now-be-dragged-into-freeform-screen.md
new file mode 100644
index 0000000000..815d8c314b
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-auto-layout-children-can-now-be-dragged-into-freeform-screen.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Auto-layout children can now be dragged into freeform screens, other layouts, and absolute frames without jumping or losing their position.
diff --git a/templates/design/changelog/2026-07-09-board-shapes-now-stay-visible-and-nest-correctly-across-the-.md b/templates/design/changelog/2026-07-09-board-shapes-now-stay-visible-and-nest-correctly-across-the-.md
new file mode 100644
index 0000000000..a4ca75faf6
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-board-shapes-now-stay-visible-and-nest-correctly-across-the-.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Board shapes now stay visible and nest correctly across the All screens canvas without iframe flashes.
diff --git a/templates/design/changelog/2026-07-09-component-source-navigation-now-opens-reliably-from-the-insp.md b/templates/design/changelog/2026-07-09-component-source-navigation-now-opens-reliably-from-the-insp.md
new file mode 100644
index 0000000000..8ba1afe7d6
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-component-source-navigation-now-opens-reliably-from-the-insp.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Component source navigation now opens reliably from the inspector and component interactions.
diff --git a/templates/design/changelog/2026-07-09-cross-screen-local-react-layer-moves-now-hand-off-exact-sour.md b/templates/design/changelog/2026-07-09-cross-screen-local-react-layer-moves-now-hand-off-exact-sour.md
new file mode 100644
index 0000000000..5e942cb34a
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-cross-screen-local-react-layer-moves-now-hand-off-exact-sour.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Cross-screen local React layer moves now hand off exact source anchors safely instead of silently refusing the drop.
diff --git a/templates/design/changelog/2026-07-09-cross-screen-moves-undo-and-redo-now-keep-both-screens-stabl.md b/templates/design/changelog/2026-07-09-cross-screen-moves-undo-and-redo-now-keep-both-screens-stabl.md
new file mode 100644
index 0000000000..f99011a437
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-cross-screen-moves-undo-and-redo-now-keep-both-screens-stabl.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Cross-screen moves, undo, and redo now keep both screens stable without preview flashes or lost selection
diff --git a/templates/design/changelog/2026-07-09-detach-a-component-instance-into-plain-editable-eleme.md b/templates/design/changelog/2026-07-09-detach-a-component-instance-into-plain-editable-eleme.md
new file mode 100644
index 0000000000..1652f9894e
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-detach-a-component-instance-into-plain-editable-eleme.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+Component instances can now be detached (⌥⌘B) into plain, independently-editable elements.
diff --git a/templates/design/changelog/2026-07-09-dragging-layers-into-auto-layout-now-respects-ignore-auto-la.md b/templates/design/changelog/2026-07-09-dragging-layers-into-auto-layout-now-respects-ignore-auto-la.md
new file mode 100644
index 0000000000..1df4db231a
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-dragging-layers-into-auto-layout-now-respects-ignore-auto-la.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Dragging layers into auto layout now respects Ignore auto layout and stays visually stable during reparenting
diff --git a/templates/design/changelog/2026-07-09-drawing-annotations-sent-to-the-agent-now-include-a-rendered.md b/templates/design/changelog/2026-07-09-drawing-annotations-sent-to-the-agent-now-include-a-rendered.md
new file mode 100644
index 0000000000..bce9c13a75
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-drawing-annotations-sent-to-the-agent-now-include-a-rendered.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Drawing annotations sent to the agent now include a rendered screenshot with the drawing composited on top, not just coordinates
diff --git a/templates/design/changelog/2026-07-09-editor-sidebars-now-use-figma-matched-default-widths-for-a-r.md b/templates/design/changelog/2026-07-09-editor-sidebars-now-use-figma-matched-default-widths-for-a-r.md
new file mode 100644
index 0000000000..831d4ace15
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-editor-sidebars-now-use-figma-matched-default-widths-for-a-r.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Editor sidebars now use Figma-matched default widths for a roomier, more familiar canvas.
diff --git a/templates/design/changelog/2026-07-09-empty-frames-and-rectangles-now-expose-full-auto-layout-cont.md b/templates/design/changelog/2026-07-09-empty-frames-and-rectangles-now-expose-full-auto-layout-cont.md
new file mode 100644
index 0000000000..271809ecac
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-empty-frames-and-rectangles-now-expose-full-auto-layout-cont.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Empty frames and rectangles now expose full Auto layout controls, and promoted containers show the correct Layers icon.
diff --git a/templates/design/changelog/2026-07-09-export-any-design-screen-as-a-real-vector-svg-for-figma-with.md b/templates/design/changelog/2026-07-09-export-any-design-screen-as-a-real-vector-svg-for-figma-with.md
new file mode 100644
index 0000000000..39b11363be
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-export-any-design-screen-as-a-real-vector-svg-for-figma-with.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+Export any design screen as a real vector SVG for Figma, with copy-to-clipboard and drag-import support
diff --git a/templates/design/changelog/2026-07-09-grid-auto-layout-now-uses-true-responsive-rows-and-columns-w.md b/templates/design/changelog/2026-07-09-grid-auto-layout-now-uses-true-responsive-rows-and-columns-w.md
new file mode 100644
index 0000000000..6dec1bcf04
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-grid-auto-layout-now-uses-true-responsive-rows-and-columns-w.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Grid auto layout now uses true responsive rows and columns with track sizing, independent gaps, and fluid canvas reordering.
diff --git a/templates/design/changelog/2026-07-09-hidden-and-locked-screens-now-behave-consistently-between-la.md b/templates/design/changelog/2026-07-09-hidden-and-locked-screens-now-behave-consistently-between-la.md
new file mode 100644
index 0000000000..3f106f6e16
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-hidden-and-locked-screens-now-behave-consistently-between-la.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Hidden and locked screens now behave consistently between Layers and the overview canvas.
diff --git a/templates/design/changelog/2026-07-09-image-fills-now-preserve-valid-urls-and-layered-fit-settings.md b/templates/design/changelog/2026-07-09-image-fills-now-preserve-valid-urls-and-layered-fit-settings.md
new file mode 100644
index 0000000000..220cbc22d0
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-image-fills-now-preserve-valid-urls-and-layered-fit-settings.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Image fills now preserve valid URLs and layered fit settings across page and layer edits.
diff --git a/templates/design/changelog/2026-07-09-import-figma-frames-as-pixel-accurate-design-screens-via-a-s.md b/templates/design/changelog/2026-07-09-import-figma-frames-as-pixel-accurate-design-screens-via-a-s.md
new file mode 100644
index 0000000000..946afa6aa9
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-import-figma-frames-as-pixel-accurate-design-screens-via-a-s.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+Import Figma frames as pixel-accurate Design screens via a shared file/branch link
diff --git a/templates/design/changelog/2026-07-09-inspect-code-now-hides-internal-styling-metadata-and-wraps-l.md b/templates/design/changelog/2026-07-09-inspect-code-now-hides-internal-styling-metadata-and-wraps-l.md
new file mode 100644
index 0000000000..26f6e7d070
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-inspect-code-now-hides-internal-styling-metadata-and-wraps-l.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Inspect Code now hides internal styling metadata and wraps long attribute lists for easier reading.
diff --git a/templates/design/changelog/2026-07-09-inspector-blur-and-shadow-effects-now-preserve-other-effects.md b/templates/design/changelog/2026-07-09-inspector-blur-and-shadow-effects-now-preserve-other-effects.md
new file mode 100644
index 0000000000..b5b2551205
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-inspector-blur-and-shadow-effects-now-preserve-other-effects.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Inspector effects preserve sibling filters and fractional values, linking padding no longer overwrites asymmetric sides, and mixed layout or constraint selections now display honestly.
diff --git a/templates/design/changelog/2026-07-09-jump-to-a-components-other-instances-from-the-inspecto.md b/templates/design/changelog/2026-07-09-jump-to-a-components-other-instances-from-the-inspecto.md
new file mode 100644
index 0000000000..5813e2a4ff
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-jump-to-a-components-other-instances-from-the-inspecto.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+The Component inspector panel and canvas context menu can now jump to a component's earliest instance ("Go to main component").
diff --git a/templates/design/changelog/2026-07-09-keyboard-shortcuts-are-now-discoverable-in-a-figma-style-bot.md b/templates/design/changelog/2026-07-09-keyboard-shortcuts-are-now-discoverable-in-a-figma-style-bot.md
new file mode 100644
index 0000000000..c9755529e1
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-keyboard-shortcuts-are-now-discoverable-in-a-figma-style-bot.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+Keyboard shortcuts are now discoverable in a Figma-style bottom panel from the app menu or Ctrl+Shift+?.
diff --git a/templates/design/changelog/2026-07-09-layer-selection-now-keeps-cmd-or-ctrl-toggles-and-shift-rang.md b/templates/design/changelog/2026-07-09-layer-selection-now-keeps-cmd-or-ctrl-toggles-and-shift-rang.md
new file mode 100644
index 0000000000..7c48089f2c
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-layer-selection-now-keeps-cmd-or-ctrl-toggles-and-shift-rang.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Layer selection now keeps Cmd or Ctrl toggles and Shift ranges intact in All screens view
diff --git a/templates/design/changelog/2026-07-09-layers-dropped-into-auto-layout-now-participate-correctly-in.md b/templates/design/changelog/2026-07-09-layers-dropped-into-auto-layout-now-participate-correctly-in.md
new file mode 100644
index 0000000000..7fdb801bdf
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-layers-dropped-into-auto-layout-now-participate-correctly-in.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Layers dropped into Auto layout now participate correctly in ordering, spacing, and alignment.
diff --git a/templates/design/changelog/2026-07-09-local-live-edit-screens-now-enter-and-leave-full-view-withou.md b/templates/design/changelog/2026-07-09-local-live-edit-screens-now-enter-and-leave-full-view-withou.md
new file mode 100644
index 0000000000..bb2baf7916
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-local-live-edit-screens-now-enter-and-leave-full-view-withou.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Local live-edit screens now enter and leave Full view without blank, URL-only, or duplicate-loading flashes.
diff --git a/templates/design/changelog/2026-07-09-local-preview-urls-now-live-in-the-inspector-instead-of-taki.md b/templates/design/changelog/2026-07-09-local-preview-urls-now-live-in-the-inspector-instead-of-taki.md
new file mode 100644
index 0000000000..138b174c21
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-local-preview-urls-now-live-in-the-inspector-instead-of-taki.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Local preview URLs now live in the inspector instead of taking space above the canvas
diff --git a/templates/design/changelog/2026-07-09-local-react-layers-can-now-be-hidden-and-locked-from-layers-.md b/templates/design/changelog/2026-07-09-local-react-layers-can-now-be-hidden-and-locked-from-layers-.md
new file mode 100644
index 0000000000..08df43d1ab
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-local-react-layers-can-now-be-hidden-and-locked-from-layers-.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Local React layers can now be hidden and locked from Layers with source-backed persistence.
diff --git a/templates/design/changelog/2026-07-09-local-react-layers-now-keep-exact-source-provenance-and-supp.md b/templates/design/changelog/2026-07-09-local-react-layers-now-keep-exact-source-provenance-and-supp.md
new file mode 100644
index 0000000000..fcf84d4051
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-local-react-layers-now-keep-exact-source-provenance-and-supp.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Local React layers now keep exact source provenance and support safe same-screen reorder, reparent, group, ungroup, and Auto layout editing through the coding agent.
diff --git a/templates/design/changelog/2026-07-09-local-react-visual-editing-now-loads-reliably-and-shows-live.md b/templates/design/changelog/2026-07-09-local-react-visual-editing-now-loads-reliably-and-shows-live.md
new file mode 100644
index 0000000000..e66fa6191c
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-local-react-visual-editing-now-loads-reliably-and-shows-live.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Local React visual editing now loads reliably and shows live component layers with exact development source locations.
diff --git a/templates/design/changelog/2026-07-09-paste-from-figma-cmd-v-now-imports-exact-editable-nodes-when.md b/templates/design/changelog/2026-07-09-paste-from-figma-cmd-v-now-imports-exact-editable-nodes-when.md
new file mode 100644
index 0000000000..976b281038
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-paste-from-figma-cmd-v-now-imports-exact-editable-nodes-when.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Paste from Figma (Cmd+V) now imports exact, editable nodes when possible, with a clear fallback and hint when it can't
diff --git a/templates/design/changelog/2026-07-09-pressing-escape-after-selecting-a-screen-now-reveals-page-pr.md b/templates/design/changelog/2026-07-09-pressing-escape-after-selecting-a-screen-now-reveals-page-pr.md
new file mode 100644
index 0000000000..1c7e274d05
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-pressing-escape-after-selecting-a-screen-now-reveals-page-pr.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Pressing Escape after selecting a screen now reveals Page properties instead of immediately reselecting the active screen.
diff --git a/templates/design/changelog/2026-07-09-right-click-overlapping-or-nested-objects-to-choose-the-exac.md b/templates/design/changelog/2026-07-09-right-click-overlapping-or-nested-objects-to-choose-the-exac.md
new file mode 100644
index 0000000000..753f01b13b
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-right-click-overlapping-or-nested-objects-to-choose-the-exac.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+Right-click overlapping or nested objects to choose the exact visible unlocked layer from a Figma-style Select layer submenu
diff --git a/templates/design/changelog/2026-07-09-scale-edge-stretch-and-center-constraints-now-preserve-layer.md b/templates/design/changelog/2026-07-09-scale-edge-stretch-and-center-constraints-now-preserve-layer.md
new file mode 100644
index 0000000000..f48697d6f3
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-scale-edge-stretch-and-center-constraints-now-preserve-layer.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Scale, edge, stretch, and center constraints now preserve layer geometry when nested or auto-layout frames resize
diff --git a/templates/design/changelog/2026-07-09-screen-rows-can-now-be-reordered-in-layers-with-matching-can.md b/templates/design/changelog/2026-07-09-screen-rows-can-now-be-reordered-in-layers-with-matching-can.md
new file mode 100644
index 0000000000..77b1157044
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-screen-rows-can-now-be-reordered-in-layers-with-matching-can.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Screen rows can now be reordered in Layers with matching canvas stack order, undo, and persistence.
diff --git a/templates/design/changelog/2026-07-09-screen-selection-stays-responsive-in-designs-with-hundreds-o.md b/templates/design/changelog/2026-07-09-screen-selection-stays-responsive-in-designs-with-hundreds-o.md
new file mode 100644
index 0000000000..f3ebaf905e
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-screen-selection-stays-responsive-in-designs-with-hundreds-o.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Screen selection stays responsive in designs with hundreds of screens and thousands of layers.
diff --git a/templates/design/changelog/2026-07-09-shift-a-now-enables-auto-layout-on-a-selected-screen-with-fl.md b/templates/design/changelog/2026-07-09-shift-a-now-enables-auto-layout-on-a-selected-screen-with-fl.md
new file mode 100644
index 0000000000..b17eb5e451
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-shift-a-now-enables-auto-layout-on-a-selected-screen-with-fl.md
@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-09
+---
+
+Shift+A now enables Auto layout on a selected screen with flash-free undo, redo, and persistence.
diff --git a/templates/design/changelog/2026-07-09-swap-a-component-instance-for-another-from-the-libra.md b/templates/design/changelog/2026-07-09-swap-a-component-instance-for-another-from-the-libra.md
new file mode 100644
index 0000000000..c79b601df9
--- /dev/null
+++ b/templates/design/changelog/2026-07-09-swap-a-component-instance-for-another-from-the-libra.md
@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-09
+---
+
+Component instances can now be swapped for a different component from the design, keeping matching prop overrides.
diff --git a/templates/design/changelog/2026-07-10-drawing-annotations-now-stay-available-to-retry-when-the.md b/templates/design/changelog/2026-07-10-drawing-annotations-now-stay-available-to-retry-when-the.md
new file mode 100644
index 0000000000..3766a63fd6
--- /dev/null
+++ b/templates/design/changelog/2026-07-10-drawing-annotations-now-stay-available-to-retry-when-the.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-10
+---
+
+Drawing annotations now stay available to retry when the agent chat cannot accept them, and repeated Send actions no longer duplicate the request.
diff --git a/templates/design/e2e/canvas-tools.spec.ts b/templates/design/e2e/canvas-tools.spec.ts
index c646314ef8..8c89585dd3 100644
--- a/templates/design/e2e/canvas-tools.spec.ts
+++ b/templates/design/e2e/canvas-tools.spec.ts
@@ -8,10 +8,12 @@ import {
 
 import { FIXTURE_HTML } from "./global-setup";
 import {
+  dragCanvasByText,
   designFrame,
   enterDirectMode,
   gotoEditor,
   installBridge,
+  selectByText,
 } from "./helpers";
 
 let designId: string;
@@ -146,6 +148,98 @@ function homeLayerRow(page: Page): Locator {
     .first();
 }
 
+function topLevelScreenLayerRow(page: Page, name: string): Locator {
+  return page
+    .getByRole("tree", { name: "Layers" })
+    .locator('[role="treeitem"][aria-level="1"]')
+    .filter({ has: page.locator(`span[title="${name}"]`) })
+    .first();
+}
+
+async function topLevelScreenLayerNames(page: Page): Promise<string[]> {
+  return page
+    .getByRole("tree", { name: "Layers" })
+    .locator(
+      '[role="treeitem"][aria-level="1"] [data-layer-row-button] span[title]',
+    )
+    .evaluateAll((nodes) =>
+      nodes.map((node) => node.getAttribute("title") ?? ""),
+    );
+}
+
+async function dispatchLayerRowDrag(
+  page: Page,
+  sourceName: string,
+  targetName: string,
+  targetY: "top" | "bottom",
+): Promise<void> {
+  const source = topLevelScreenLayerRow(page, sourceName);
+  const target = topLevelScreenLayerRow(page, targetName);
+  await expect(source).toBeVisible();
+  await expect(target).toBeVisible();
+  await page.evaluate(
+    ({ sourceName, targetName, targetY }) => {
+      const find = (name: string) => {
+        const row = Array.from(
+          document.querySelectorAll<HTMLElement>(
+            '[role="treeitem"][aria-level="1"]',
+          ),
+        ).find((candidate) =>
+          Array.from(candidate.querySelectorAll("span[title]")).some(
+            (label) => label.getAttribute("title") === name,
+          ),
+        );
+        if (!row) throw new Error(`missing screen layer row ${name}`);
+        return row;
+      };
+      const source = find(sourceName);
+      const target = find(targetName);
+      const dataTransfer = new DataTransfer();
+      const sourceRect = source.getBoundingClientRect();
+      const targetRect = target.getBoundingClientRect();
+      const targetClientY =
+        targetY === "top" ? targetRect.top + 2 : targetRect.bottom - 2;
+      source.dispatchEvent(
+        new DragEvent("dragstart", {
+          bubbles: true,
+          cancelable: true,
+          clientX: sourceRect.left + 24,
+          clientY: sourceRect.top + sourceRect.height / 2,
+          dataTransfer,
+        }),
+      );
+      target.dispatchEvent(
+        new DragEvent("dragover", {
+          bubbles: true,
+          cancelable: true,
+          clientX: targetRect.left + 24,
+          clientY: targetClientY,
+          dataTransfer,
+        }),
+      );
+      target.dispatchEvent(
+        new DragEvent("drop", {
+          bubbles: true,
+          cancelable: true,
+          clientX: targetRect.left + 24,
+          clientY: targetClientY,
+          dataTransfer,
+        }),
+      );
+      source.dispatchEvent(
+        new DragEvent("dragend", {
+          bubbles: true,
+          cancelable: true,
+          clientX: targetRect.left + 24,
+          clientY: targetClientY,
+          dataTransfer,
+        }),
+      );
+    },
+    { sourceName, targetName, targetY },
+  );
+}
+
 function screenShell(page: Page, name = "Home"): Locator {
   return page.locator("[data-screen-shell]").filter({ hasText: name }).first();
 }
@@ -164,6 +258,169 @@ async function dragBetween(
   await page.waitForTimeout(150);
 }
 
+interface IframePaintProbeSnapshot {
+  identity: string | null;
+  loadCount: number;
+  animationFrames: number;
+  blankFrames: Array<{ reason: string; at: number }>;
+  iframeAttributeMutations: string[];
+  sourceEmptyMutations: number;
+}
+
+/**
+ * Watch the actual host paint boundary around one preview iframe.
+ *
+ * A MutationObserver alone over-reports `body.innerHTML` swaps: removals and
+ * insertions happen in one JS task and Chromium cannot paint between them.
+ * This probe therefore samples at requestAnimationFrame as well. Any missing,
+ * hidden, zero-sized, or source-empty document observed there represents a
+ * real frame Chromium could have presented to the user.
+ */
+async function installIframePaintProbe(
+  iframe: Locator,
+  identity: string,
+): Promise<void> {
+  await iframe.evaluate((element, token) => {
+    type Probe = IframePaintProbeSnapshot & {
+      frame: HTMLIFrameElement;
+      observer: MutationObserver;
+      raf: number;
+    };
+    const host = window as typeof window & {
+      __e2eIframePaintProbes?: Record<string, Probe>;
+    };
+    const probes = (host.__e2eIframePaintProbes ??= {});
+    const previous = probes[token];
+    if (previous) {
+      cancelAnimationFrame(previous.raf);
+      previous.observer.disconnect();
+    }
+
+    const frame = element as HTMLIFrameElement;
+    frame.dataset.e2eIframeIdentity = token;
+    const probe: Probe = {
+      frame,
+      identity: token,
+      loadCount: 0,
+      animationFrames: 0,
+      blankFrames: [],
+      iframeAttributeMutations: [],
+      sourceEmptyMutations: 0,
+      observer: null as unknown as MutationObserver,
+      raf: 0,
+    };
+    probes[token] = probe;
+
+    frame.addEventListener("load", () => {
+      probe.loadCount += 1;
+    });
+
+    const hasSourceContent = () => {
+      const body = frame.contentDocument?.body;
+      if (!body) return false;
+      return Array.from(body.querySelectorAll("*")).some((node) => {
+        if (node.closest("[data-agent-native-edit-overlay]")) return false;
+        return !["SCRIPT", "STYLE", "LINK", "META"].includes(node.tagName);
+      });
+    };
+
+    probe.observer = new MutationObserver((records) => {
+      for (const record of records) {
+        if (
+          record.type === "attributes" &&
+          record.target === frame &&
+          record.attributeName
+        ) {
+          probe.iframeAttributeMutations.push(record.attributeName);
+        }
+      }
+      if (frame.isConnected && !hasSourceContent()) {
+        probe.sourceEmptyMutations += 1;
+      }
+    });
+    probe.observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class", "style", "src", "srcdoc"],
+      childList: true,
+      subtree: true,
+    });
+
+    const samplePaint = (at: number) => {
+      probe.animationFrames += 1;
+      let reason = "";
+      if (!frame.isConnected) {
+        reason = "iframe-disconnected";
+      } else {
+        const style = getComputedStyle(frame);
+        const rect = frame.getBoundingClientRect();
+        if (style.display === "none") reason = "iframe-display-none";
+        else if (style.visibility === "hidden") reason = "iframe-hidden";
+        else if (Number(style.opacity) === 0) reason = "iframe-transparent";
+        else if (rect.width <= 0 || rect.height <= 0)
+          reason = "iframe-zero-size";
+        else if (!frame.contentDocument?.body) reason = "document-no-body";
+        else if (!hasSourceContent()) reason = "document-source-empty";
+      }
+      if (reason) probe.blankFrames.push({ reason, at });
+      probe.raf = requestAnimationFrame(samplePaint);
+    };
+    probe.raf = requestAnimationFrame(samplePaint);
+  }, identity);
+}
+
+async function readIframePaintProbe(
+  page: Page,
+  identity: string,
+): Promise<IframePaintProbeSnapshot | null> {
+  return page.evaluate((token) => {
+    const probe = (
+      window as typeof window & {
+        __e2eIframePaintProbes?: Record<
+          string,
+          IframePaintProbeSnapshot & { frame: HTMLIFrameElement }
+        >;
+      }
+    ).__e2eIframePaintProbes?.[token];
+    if (!probe) return null;
+    return {
+      identity: probe.frame.dataset.e2eIframeIdentity ?? null,
+      loadCount: probe.loadCount,
+      animationFrames: probe.animationFrames,
+      blankFrames: probe.blankFrames.slice(),
+      iframeAttributeMutations: probe.iframeAttributeMutations.slice(),
+      sourceEmptyMutations: probe.sourceEmptyMutations,
+    };
+  }, identity);
+}
+
+async function expectIframePaintStable(
+  page: Page,
+  identity: string,
+): Promise<void> {
+  await expect
+    .poll(async () => {
+      const probe = await readIframePaintProbe(page, identity);
+      return probe
+        ? {
+            identity: probe.identity,
+            loadCount: probe.loadCount,
+            blankFrames: probe.blankFrames,
+            documentNavigationMutations: probe.iframeAttributeMutations.filter(
+              (attribute) => attribute === "src" || attribute === "srcdoc",
+            ),
+            sourceEmptyMutations: probe.sourceEmptyMutations,
+          }
+        : null;
+    })
+    .toEqual({
+      identity,
+      loadCount: 0,
+      blankFrames: [],
+      documentNavigationMutations: [],
+      sourceEmptyMutations: 0,
+    });
+}
+
 async function createDraftPrimitive(
   page: Page,
   toolName: string,
@@ -205,6 +462,21 @@ async function fileContent(page: Page, filename: string): Promise<string> {
   return file.content;
 }
 
+async function fileBodyLayout(
+  page: Page,
+  filename: string,
+): Promise<{ display: string; direction: string; gap: string }> {
+  const content = await fileContent(page, filename);
+  return page.evaluate((html) => {
+    const doc = new DOMParser().parseFromString(html, "text/html");
+    return {
+      display: doc.body.style.display,
+      direction: doc.body.style.flexDirection,
+      gap: doc.body.style.gap,
+    };
+  }, content);
+}
+
 async function designData(page: Page): Promise<Record<string, any>> {
   const result = await getAction(page.request, "get-design", { id: designId });
   if (typeof result.data !== "string") return {};
@@ -275,11 +547,92 @@ async function primitiveLeftPositions(
   );
 }
 
+async function primitiveParentNodeId(
+  page: Page,
+  filename: string,
+  nodeId: string,
+): Promise<string | null> {
+  const content = await fileContent(page, filename);
+  return page.evaluate(
+    ({ html, id }) => {
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      const node = doc.querySelector<HTMLElement>(
+        `[data-agent-native-node-id="${CSS.escape(id)}"]`,
+      );
+      return (
+        node?.parentElement?.getAttribute("data-agent-native-node-id") ?? null
+      );
+    },
+    { html: content, id: nodeId },
+  );
+}
+
+async function primitiveInlinePosition(
+  page: Page,
+  filename: string,
+  nodeId: string,
+): Promise<{ left: number; top: number } | null> {
+  const content = await fileContent(page, filename);
+  return page.evaluate(
+    ({ html, id }) => {
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      const node = doc.querySelector<HTMLElement>(
+        `[data-agent-native-node-id="${CSS.escape(id)}"]`,
+      );
+      if (!node) return null;
+      return {
+        left: Number.parseFloat(node.style.left),
+        top: Number.parseFloat(node.style.top),
+      };
+    },
+    { html: content, id: nodeId },
+  );
+}
+
+async function negativeBoardRectangleViewport(page: Page): Promise<{
+  iframeWidth: number;
+  iframeHeight: number;
+  rectX: number;
+  rectY: number;
+  rectRight: number;
+  rectBottom: number;
+  offsetStyle: string;
+} | null> {
+  const iframe = page
+    .locator("[data-board-surface-layer] iframe[data-design-preview-iframe]")
+    .first();
+  if ((await iframe.count()) === 0) return null;
+  return iframe.evaluate((element) => {
+    const frame = element as HTMLIFrameElement;
+    const doc = frame.contentDocument;
+    if (!doc) return null;
+    const rectangle = Array.from(
+      doc.querySelectorAll<HTMLElement>('[data-an-primitive="rectangle"]'),
+    ).find((candidate) => Number.parseFloat(candidate.style.left) < 0);
+    if (!rectangle) return null;
+    const rect = rectangle.getBoundingClientRect();
+    return {
+      iframeWidth: frame.clientWidth,
+      iframeHeight: frame.clientHeight,
+      rectX: rect.x,
+      rectY: rect.y,
+      rectRight: rect.right,
+      rectBottom: rect.bottom,
+      offsetStyle:
+        doc.querySelector<HTMLStyleElement>(
+          "style[data-agent-native-content-offset]",
+        )?.textContent ?? "",
+    };
+  });
+}
+
 async function dragInEmptyCanvasLeftOf(
   page: Page,
   shellName: string,
   options?: { width?: number; height?: number; topOffset?: number },
 ): Promise<void> {
+  const requiredGutter = (options?.width ?? 96) + 40;
+  const screenBoxes = await ensureOverviewLeftGutter(page, requiredGutter);
   const card = screenShell(page, shellName).locator("[data-screen-card]");
   const cardBox = await card.boundingBox();
   if (!cardBox) throw new Error(`no ${shellName} screen card box`);
@@ -287,15 +640,63 @@ async function dragInEmptyCanvasLeftOf(
   const width = options?.width ?? 96;
   const height = options?.height ?? 96;
   const start = {
-    x: cardBox.x - 12,
+    x: Math.min(...screenBoxes.map((box) => box.x)) - width - 24,
     y: cardBox.y + (options?.topOffset ?? 120),
   };
   await dragBetween(page, start, {
-    x: start.x - width,
+    x: start.x + width,
     y: start.y + height,
   });
 }
 
+async function ensureOverviewLeftGutter(
+  page: Page,
+  requiredGutter: number,
+): Promise<Array<{ x: number; right: number }>> {
+  const world = page.locator("[data-multi-screen-canvas-world]");
+  const surface = world.locator("..");
+  const surfaceBox = await surface.boundingBox();
+  if (!surfaceBox) throw new Error("no overview canvas surface");
+
+  const readScreenBoxes = () =>
+    page.locator("[data-screen-card]").evaluateAll((cards) =>
+      cards.map((screen) => {
+        const rect = screen.getBoundingClientRect();
+        return { x: rect.x, right: rect.right };
+      }),
+    );
+  let screenBoxes = await readScreenBoxes();
+  if (screenBoxes.length === 0) throw new Error("no overview screen cards");
+
+  let missing =
+    requiredGutter -
+    (Math.min(...screenBoxes.map((box) => box.x)) - surfaceBox.x);
+  let attempts = 0;
+  while (missing > 0 && attempts < 3) {
+    attempts += 1;
+    const shift = Math.min(missing + 24, surfaceBox.width - 48);
+    const start = {
+      x: surfaceBox.x + 16,
+      y: surfaceBox.y + surfaceBox.height / 2,
+    };
+    await page.keyboard.down("Space");
+    await page.mouse.move(start.x, start.y);
+    await page.mouse.down();
+    await page.mouse.move(start.x + shift, start.y, { steps: 12 });
+    await page.mouse.up();
+    await page.keyboard.up("Space");
+    await page.waitForTimeout(100);
+    screenBoxes = await readScreenBoxes();
+    missing =
+      requiredGutter -
+      (Math.min(...screenBoxes.map((box) => box.x)) - surfaceBox.x);
+  }
+  if (missing > 0) {
+    throw new Error(`could not open ${requiredGutter}px of left canvas gutter`);
+  }
+  return screenBoxes;
+}
+
 async function textPrimitiveSummaries(
   page: Page,
   filename: string,
@@ -657,6 +1058,22 @@ async function primitiveViewportBox(
   return box;
 }
 
+async function boardPrimitiveViewportBox(
+  page: Page,
+  nodeId: string,
+): Promise<{ x: number; y: number; width: number; height: number }> {
+  const iframe = page
+    .locator("[data-board-surface-layer] iframe[data-design-preview-iframe]")
+    .first();
+  await expect(iframe).toBeVisible();
+  const box = await iframe
+    .contentFrame()
+    .locator(`[data-agent-native-node-id="${nodeId}"]`)
+    .boundingBox();
+  if (!box) throw new Error(`board primitive not found: ${nodeId}`);
+  return box;
+}
+
 function expectCloseToFrameSize(
   viewport: { width: number; height: number },
   frame: { width: number; height: number },
@@ -708,6 +1125,345 @@ test("toolbar modes toggle the editor mode buttons", async ({ page }) => {
   );
 });
 
+test("keyboard shortcuts dock opens without remounting the overview iframe", async ({
+  page,
+}) => {
+  const railBox = await page
+    .getByRole("navigation", { name: "Design workspace" })
+    .boundingBox();
+  const layersBox = await page
+    .getByRole("complementary", { name: "Layers" })
+    .boundingBox();
+  expect(railBox?.width).toBe(57);
+  expect(layersBox).not.toBeNull();
+  expect(Math.round(layersBox!.x + layersBox!.width)).toBe(337);
+
+  const iframe = screenShell(page, "Home")
+    .locator("iframe[data-design-preview-iframe]")
+    .first();
+  await expect(iframe).toBeVisible();
+  await iframe.evaluate((element) => {
+    const frame = element as HTMLIFrameElement & { __shortcutLoads?: number };
+    frame.dataset.shortcutIdentity = "stable-shortcut-frame";
+    frame.__shortcutLoads = 0;
+    frame.addEventListener("load", () => {
+      frame.__shortcutLoads = (frame.__shortcutLoads ?? 0) + 1;
+    });
+  });
+
+  await page.evaluate(() => {
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "?",
+        code: "Slash",
+        ctrlKey: true,
+        shiftKey: true,
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+  });
+
+  const panel = page.locator("[data-keyboard-shortcuts-panel]");
+  await expect(panel).toBeVisible();
+  await expect(panel.getByRole("tab", { name: "Essential" })).toBeFocused();
+  const panelBox = await panel.boundingBox();
+  expect(panelBox?.height).toBeGreaterThanOrEqual(240);
+  expect(panelBox?.height).toBeLessThanOrEqual(242);
+  expect(panelBox?.x).toBe(0);
+  const essentialTabBox = await panel
+    .getByRole("tab", { name: "Essential" })
+    .boundingBox();
+  expect(essentialTabBox?.x).toBeGreaterThanOrEqual(124);
+  expect(essentialTabBox?.x).toBeLessThanOrEqual(126);
+  const tabRowBox = await panel
+    .locator("[data-shortcuts-tab-row]")
+    .boundingBox();
+  expect(tabRowBox?.height).toBe(38);
+  expect(tabRowBox?.y).toBe(panelBox!.y + 1);
+  const essentialPanelBox = await panel
+    .locator('[data-shortcuts-tabpanel="essential"]')
+    .boundingBox();
+  expect(essentialPanelBox?.y).toBe(tabRowBox!.y + 38);
+  const essentialColumnBox = await panel
+    .locator(
+      '[data-shortcuts-tabpanel="essential"] [data-shortcuts-content-column]',
+    )
+    .boundingBox();
+  expect(essentialColumnBox?.width).toBe(400);
+  expect(
+    Math.abs(
+      essentialColumnBox!.x +
+        essentialColumnBox!.width / 2 -
+        (panelBox!.x + panelBox!.width / 2),
+    ),
+  ).toBeLessThanOrEqual(1);
+  await expect(panel.getByRole("tab")).toHaveCount(13);
+  await expect(panel.locator("[data-essential-shortcuts-heading]")).toHaveText(
+    "Essential keyboard shortcuts",
+  );
+  await expect(panel.locator("[data-essential-shortcut-card]")).toHaveCount(3);
+
+  expect(panelBox).not.toBeNull();
+  await expect
+    .poll(async () => {
+      const toolbarBox = await page
+        .locator("[data-design-bottom-toolbar]")
+        .boundingBox();
+      return toolbarBox
+        ? toolbarBox.y + toolbarBox.height
+        : Number.POSITIVE_INFINITY;
+    })
+    .toBeLessThanOrEqual(panelBox!.y);
+
+  await panel.getByRole("tab", { name: "Edit" }).click();
+  await expect(
+    panel.locator('[data-code-shortcut-id="workbench.save"]'),
+  ).toBeVisible();
+  await panel.getByRole("tab", { name: "Tools" }).click();
+  const toolsTable = panel.locator('[data-shortcut-grid="tools"]');
+  const toolsTableBox = await toolsTable.boundingBox();
+  expect(toolsTableBox?.width).toBeLessThanOrEqual(400);
+  expect(toolsTableBox?.x).toBeGreaterThan(panelBox!.x + 200);
+
+  await page.keyboard.press("Escape");
+  await expect(panel).toHaveCount(0);
+  await expect
+    .poll(() =>
+      iframe.evaluate((element) => {
+        const frame = element as HTMLIFrameElement & {
+          __shortcutLoads?: number;
+        };
+        return {
+          identity: frame.dataset.shortcutIdentity,
+          loads: frame.__shortcutLoads,
+        };
+      }),
+    )
+    .toEqual({ identity: "stable-shortcut-frame", loads: 0 });
+
+  await page.getByRole("button", { name: "More" }).click();
+  await page.getByRole("menuitem", { name: /Keyboard shortcuts/ }).click();
+  await expect(panel).toBeVisible();
+  await expect(panel.getByRole("tab", { name: "Essential" })).toBeFocused();
+  await page.locator("[data-keyboard-shortcuts-close]").click();
+  await expect(panel).toHaveCount(0);
+  await expect(page.getByRole("button", { name: "More" })).toBeFocused();
+});
+
+test("overview Annotate draws around screens with stable iframes and stroke undo redo", async ({
+  page,
+}) => {
+  const shell = screenShell(page, "Home");
+  const iframe = shell.locator("iframe[data-design-preview-iframe]").first();
+  await expect(iframe).toBeVisible();
+  await installIframePaintProbe(iframe, "stable-overview-paint");
+  await iframe.evaluate((element) => {
+    const frame = element as HTMLIFrameElement & { __annotateLoads?: number };
+    frame.dataset.annotateIdentity = "stable-overview-frame";
+    frame.__annotateLoads = 0;
+    frame.addEventListener("load", () => {
+      frame.__annotateLoads = (frame.__annotateLoads ?? 0) + 1;
+    });
+  });
+  const readIframeIdentity = () =>
+    iframe.evaluate((element) => {
+      const frame = element as HTMLIFrameElement & {
+        __annotateLoads?: number;
+      };
+      return {
+        identity: frame.dataset.annotateIdentity,
+        loads: frame.__annotateLoads,
+      };
+    });
+
+  await toolButton(page, "Annotate").click();
+  await expect(toolButton(page, "Annotate")).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  await expect(shell).toBeVisible();
+  await expect(page.locator("[data-draw-overlay]")).toBeVisible();
+  await expect.poll(readIframeIdentity).toEqual({
+    identity: "stable-overview-frame",
+    loads: 0,
+  });
+  await expectIframePaintStable(page, "stable-overview-paint");
+
+  const drawCanvas = page.locator("[data-draw-canvas]");
+  const canvasBox = await drawCanvas.boundingBox();
+  const shellBox = await shell.boundingBox();
+  if (!canvasBox || !shellBox) throw new Error("missing overview draw bounds");
+  const x = Math.max(canvasBox.x + 24, shellBox.x - 48);
+  const y = Math.max(canvasBox.y + 80, shellBox.y + 60);
+  await page.mouse.move(x, y);
+  await page.mouse.down();
+  await page.mouse.move(x + 28, y + 18, { steps: 6 });
+  await page.mouse.up();
+
+  const undo = page.locator('[data-testid="draw-undo"]');
+  const redo = page.locator('[data-testid="draw-redo"]');
+  await expect(undo).toBeEnabled();
+  await undo.click();
+  await expect(undo).toBeDisabled();
+  await expect(redo).toBeEnabled();
+  await redo.click();
+  await expect(undo).toBeEnabled();
+  await expect(redo).toBeDisabled();
+
+  await expect.poll(readIframeIdentity).toEqual({
+    identity: "stable-overview-frame",
+    loads: 0,
+  });
+  await expectIframePaintStable(page, "stable-overview-paint");
+  await page.keyboard.press("Escape");
+  await expect(page.locator("[data-draw-overlay]")).toHaveCount(0);
+  await expect(shell).toBeVisible();
+  await expect.poll(readIframeIdentity).toEqual({
+    identity: "stable-overview-frame",
+    loads: 0,
+  });
+  await expectIframePaintStable(page, "stable-overview-paint");
+});
+
+test("overview pan and cursor-anchored zoom retain a continuously painted iframe", async ({
+  page,
+}) => {
+  const iframe = screenShell(page, "Home")
+    .locator("iframe[data-design-preview-iframe]")
+    .first();
+  await expect(iframe).toBeVisible();
+  await installIframePaintProbe(iframe, "overview-navigation-stable");
+
+  const world = page.locator("[data-multi-screen-canvas-world]");
+  const surface = world.locator("..");
+  const surfaceBox = await surface.boundingBox();
+  if (!surfaceBox) throw new Error("missing overview canvas surface");
+  const initialTransform = await world.evaluate(
+    (element) => (element as HTMLElement).style.transform,
+  );
+
+  await page.keyboard.press("h");
+  await expect(toolButton(page, "Hand")).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  const start = {
+    x: surfaceBox.x + Math.min(40, surfaceBox.width / 4),
+    y: surfaceBox.y + Math.min(40, surfaceBox.height / 4),
+  };
+  await dragBetween(page, start, { x: start.x + 80, y: start.y + 56 });
+  await expect
+    .poll(() =>
+      world.evaluate((element) => (element as HTMLElement).style.transform),
+    )
+    .not.toBe(initialTransform);
+  await expectIframePaintStable(page, "overview-navigation-stable");
+
+  const beforeZoom = await world.evaluate(
+    (element) => (element as HTMLElement).style.transform,
+  );
+  await page.mouse.move(
+    surfaceBox.x + surfaceBox.width / 2,
+    surfaceBox.y + surfaceBox.height / 2,
+  );
+  await page.keyboard.down(process.platform === "darwin" ? "Meta" : "Control");
+  await page.mouse.wheel(0, -240);
+  await page.keyboard.up(process.platform === "darwin" ? "Meta" : "Control");
+  await expect
+    .poll(() =>
+      world.evaluate((element) => (element as HTMLElement).style.transform),
+    )
+    .not.toBe(beforeZoom);
+  await page.waitForTimeout(250);
+  await expectIframePaintStable(page, "overview-navigation-stable");
+});
+
+test("selection, same-screen move, text and style edits, undo redo, and zoom never paint a blank focused frame", async ({
+  page,
+}) => {
+  await enterDirectMode(page);
+  const iframe = page.locator("iframe[data-design-preview-iframe]").last();
+  await expect(iframe).toBeVisible();
+  await installIframePaintProbe(iframe, "focused-edit-stable");
+
+  // Inspector style commits must live-patch the same document; their async
+  // save/refetch echo used to be a common delayed white-flash source.
+  await selectByText(page, "E2E Hero Heading");
+  const sizeInput = page.locator('input[aria-label="Size" i]').first();
+  await expect(sizeInput).toBeVisible();
+  await sizeInput.fill("48");
+  await sizeInput.press("Enter");
+  await expect
+    .poll(() =>
+      designFrame(page)
+        .getByText("E2E Hero Heading", { exact: true })
+        .evaluate((element) => (element as HTMLElement).style.fontSize),
+    )
+    .toBe("48px");
+  // Let the durable save/refetch round trip land before checking paint data.
+  await page.waitForTimeout(900);
+  await expectIframePaintStable(page, "focused-edit-stable");
+
+  // Inline text editing commits through its own bridge path and should retain
+  // the same iframe through the subsequent history replay.
+  await dblClickText(page, "E2E Hero Heading");
+  await waitForTextEditing(page);
+  await page.keyboard.press(
+    process.platform === "darwin" ? "Meta+A" : "Control+A",
+  );
+  await page.keyboard.type("Flash-free heading");
+  await page.keyboard.press("Escape");
+  await expect(
+    designFrame(page).getByText("Flash-free heading", { exact: true }),
+  ).toBeVisible();
+
+  const undoShortcut = process.platform === "darwin" ? "Meta+Z" : "Control+Z";
+  const redoShortcut =
+    process.platform === "darwin" ? "Meta+Shift+Z" : "Control+Shift+Z";
+  await page.keyboard.press(undoShortcut);
+  await expect(
+    designFrame(page).getByText("E2E Hero Heading", { exact: true }),
+  ).toBeVisible();
+  await page.keyboard.press(redoShortcut);
+  await expect(
+    designFrame(page).getByText("Flash-free heading", { exact: true }),
+  ).toBeVisible();
+
+  // An in-flow structural move exercises overlay churn and the optimistic
+  // source-persistence round trip. Keep it after the text/inspector checks:
+  // its async selection acknowledgement intentionally reselects the moved
+  // element, just like Figma, so it should not race an unrelated next edit.
+  await selectByText(page, "Alpha Button");
+  await expect(selectedLayerRow(page)).toContainText("Alpha Button");
+  const beta = designFrame(page).getByText("Beta Button", { exact: true });
+  const alpha = designFrame(page).getByText("Alpha Button", { exact: true });
+  const alphaBox = await alpha.boundingBox();
+  const betaBox = await beta.boundingBox();
+  if (!alphaBox || !betaBox) throw new Error("missing auto-layout buttons");
+  await dragCanvasByText(
+    page,
+    "Alpha Button",
+    betaBox.x + betaBox.width - (alphaBox.x + alphaBox.width / 2) + 12,
+    0,
+  );
+  await page.waitForTimeout(900);
+  await expectIframePaintStable(page, "focused-edit-stable");
+
+  // Zoom updates editor chrome through postMessage; neither direction may
+  // rebuild srcdoc or make the preview transparent for a compositor frame.
+  await page.keyboard.press(
+    process.platform === "darwin" ? "Meta+Equal" : "Control+Equal",
+  );
+  await page.keyboard.press(
+    process.platform === "darwin" ? "Meta+Minus" : "Control+Minus",
+  );
+  await page.waitForTimeout(250);
+  const snapshot = await readIframePaintProbe(page, "focused-edit-stable");
+  expect(snapshot?.animationFrames ?? 0).toBeGreaterThan(5);
+  await expectIframePaintStable(page, "focused-edit-stable");
+});
+
 test("Hand and Scale shortcuts project the active move-group tool", async ({
   page,
 }) => {
@@ -923,6 +1679,11 @@ test("board text focuses immediately and uses editing chrome states", async ({
     )
     .toBe(true);
 
+  const boardFile = (await designFiles(page)).find(
+    (file) => file.filename === "__board__.html",
+  );
+  if (!boardFile) throw new Error("board file was not created");
+
   const aboutCardBox = await screenShell(page, "About")
     .locator("[data-screen-card]")
     .boundingBox();
@@ -933,8 +1694,9 @@ test("board text focuses immediately and uses editing chrome states", async ({
     "aria-pressed",
     "true",
   );
+  const screenBoxes = await ensureOverviewLeftGutter(page, 280);
   await page.mouse.click(
-    aboutCardBox.x + aboutCardBox.width + 80,
+    Math.min(...screenBoxes.map((box) => box.x)) - 240,
     aboutCardBox.y + 120,
   );
 
@@ -942,6 +1704,9 @@ test("board text focuses immediately and uses editing chrome states", async ({
     page,
     (summary) => summary.editing && summary.active && summary.text === "",
   );
+  // The board iframe intentionally has no screen-frame identity: board
+  // primitives persist through __board__.html, but the board itself must not
+  // enter the screen selection/zoom model.
   expect(emptyChrome.screenId).toBeNull();
   expect(emptyChrome.overlayVisible).toBe(false);
   expect(emptyChrome.visibleCornerHandles).toBe(0);
@@ -1092,6 +1857,16 @@ test("dragging a rectangle between screens moves it across files", async ({
   const movedId = homeIdsAfterCreate.find((id) => !homeIdsBefore.includes(id));
   if (!movedId) throw new Error("new rectangle id was not found");
   const movedBox = await primitiveViewportBox(homeShell, movedId);
+  const homeIframe = homeShell.locator("iframe[data-design-preview-iframe]");
+  const aboutIframe = aboutShell.locator("iframe[data-design-preview-iframe]");
+  await expect(homeIframe).toHaveCount(1);
+  await expect(aboutIframe).toHaveCount(1);
+  await installIframePaintProbe(homeIframe, "home-stable");
+  await installIframePaintProbe(aboutIframe, "about-stable");
+  const expectStableIframeIdentity = async () => {
+    await expectIframePaintStable(page, "home-stable");
+    await expectIframePaintStable(page, "about-stable");
+  };
 
   await dragBetween(
     page,
@@ -1129,6 +1904,568 @@ test("dragging a rectangle between screens moves it across files", async ({
       homeHasMoved: false,
       homeCount: homeIdsBefore.length,
     });
+  await expect(selectedLayerRow(page)).toContainText("Rectangle");
+  await expectStableIframeIdentity();
+
+  await pressPrimaryShortcut(page, "z");
+  await expect
+    .poll(async () => {
+      const homeIds = await primitiveNodeIds(page, "index.html", "rectangle");
+      const aboutIds = await primitiveNodeIds(page, "about.html", "rectangle");
+      return {
+        homeHasMoved: homeIds.includes(movedId),
+        aboutHasMoved: aboutIds.includes(movedId),
+      };
+    })
+    .toEqual({ homeHasMoved: true, aboutHasMoved: false });
+  await expect(selectedLayerRow(page)).toContainText("Rectangle");
+  await expectStableIframeIdentity();
+
+  await pressPrimaryShortcut(page, "z", { shift: true });
+  await expect
+    .poll(async () => {
+      const homeIds = await primitiveNodeIds(page, "index.html", "rectangle");
+      const aboutIds = await primitiveNodeIds(page, "about.html", "rectangle");
+      return {
+        homeHasMoved: homeIds.includes(movedId),
+        aboutHasMoved: aboutIds.includes(movedId),
+      };
+    })
+    .toEqual({ homeHasMoved: false, aboutHasMoved: true });
+  await expect(selectedLayerRow(page)).toContainText("Rectangle");
+  await expectStableIframeIdentity();
+});
+
+test("dragging within an auto-layout row reorders at the visual insertion point and persists", async ({
+  page,
+}) => {
+  const alpha = designFrame(page).getByText("Alpha Button", { exact: true });
+  const beta = designFrame(page).getByText("Beta Button", { exact: true });
+  const alphaBox = await alpha.boundingBox();
+  const betaBox = await beta.boundingBox();
+  if (!alphaBox || !betaBox) throw new Error("missing auto-layout buttons");
+
+  const fired = await dragCanvasByText(
+    page,
+    "Alpha Button",
+    betaBox.x + betaBox.width - (alphaBox.x + alphaBox.width / 2) + 12,
+    0,
+  );
+  expect(fired).toContain("visual-structure-change");
+
+  const betaMarker = 'data-agent-native-layer-name="Beta Button"';
+  const alphaMarker = 'data-agent-native-layer-name="Alpha Button"';
+  await expect
+    .poll(async () => {
+      const content = await fileContent(page, "index.html");
+      return content.indexOf(betaMarker) < content.indexOf(alphaMarker);
+    })
+    .toBe(true);
+
+  await gotoEditor(page, designId);
+  await expect
+    .poll(async () => {
+      const content = await fileContent(page, "index.html");
+      return content.indexOf(betaMarker) < content.indexOf(alphaMarker);
+    })
+    .toBe(true);
+});
+
+test("Shift+A enables auto layout on one overview screen with flash-free undo, redo, and persistence", async ({
+  page,
+}) => {
+  const homeRow = topLevelScreenLayerRow(page, "Home");
+  await expect(homeRow).toBeVisible();
+  await homeRow.locator("[data-layer-row-button]").click();
+  await expect(homeRow).toHaveAttribute("aria-selected", "true");
+
+  const iframe = screenShell(page, "Home")
+    .locator("iframe[data-design-preview-iframe]")
+    .first();
+  await expect(iframe).toBeVisible();
+  const liveDocumentMarker = `shift-a-${Date.now()}`;
+  await iframe.evaluate((element, marker) => {
+    ((element as HTMLIFrameElement).contentWindow as any)[
+      "__shiftAAutoLayoutMarker"
+    ] = marker;
+  }, liveDocumentMarker);
+  const readLiveState = () =>
+    iframe.evaluate((element) => {
+      const frame = element as HTMLIFrameElement;
+      return {
+        marker: (frame.contentWindow as any)?.__shiftAAutoLayoutMarker ?? null,
+        display: frame.contentDocument?.body.style.display ?? "",
+      };
+    });
+
+  await page.keyboard.press("Shift+A");
+  await expect
+    .poll(() => fileBodyLayout(page, "index.html"))
+    .toMatchObject({
+      display: "flex",
+    });
+  await expect.poll(readLiveState).toEqual({
+    marker: liveDocumentMarker,
+    display: "flex",
+  });
+
+  const undoShortcut = process.platform === "darwin" ? "Meta+Z" : "Control+Z";
+  const redoShortcut =
+    process.platform === "darwin" ? "Meta+Shift+Z" : "Control+Shift+Z";
+  await page.keyboard.press(undoShortcut);
+  await expect
+    .poll(() => fileBodyLayout(page, "index.html"))
+    .toMatchObject({
+      display: "",
+    });
+  await expect.poll(readLiveState).toEqual({
+    marker: liveDocumentMarker,
+    display: "",
+  });
+
+  await page.keyboard.press(redoShortcut);
+  await expect
+    .poll(() => fileBodyLayout(page, "index.html"))
+    .toMatchObject({
+      display: "flex",
+    });
+  await expect.poll(readLiveState).toEqual({
+    marker: liveDocumentMarker,
+    display: "flex",
+  });
+
+  await gotoEditor(page, designId);
+  await expect
+    .poll(() => fileBodyLayout(page, "index.html"))
+    .toMatchObject({
+      display: "flex",
+    });
+  await expect
+    .poll(() =>
+      screenShell(page, "Home")
+        .locator("iframe[data-design-preview-iframe]")
+        .first()
+        .evaluate(
+          (element) =>
+            (element as HTMLIFrameElement).contentDocument?.body.style
+              .display ?? "",
+        ),
+    )
+    .toBe("flex");
+});
+
+test("Shift+A leaves a multi-screen overview selection unchanged", async ({
+  page,
+}) => {
+  await postAction(page.request, "create-file", {
+    designId,
+    filename: "about.html",
+    content: FIXTURE_HTML.replace("E2E Fixture", "E2E Second Fixture"),
+    fileType: "html",
+  });
+  await gotoEditor(page, designId);
+
+  const homeRow = topLevelScreenLayerRow(page, "Home");
+  const aboutRow = topLevelScreenLayerRow(page, "About");
+  await homeRow.locator("[data-layer-row-button]").click();
+  await page.keyboard.press(
+    process.platform === "darwin" ? "Meta+A" : "Control+A",
+  );
+  await expect(homeRow).toHaveAttribute("aria-selected", "true");
+  await expect(aboutRow).toHaveAttribute("aria-selected", "true");
+
+  await page.keyboard.press("Shift+A");
+  await page.waitForTimeout(300);
+  expect(await fileBodyLayout(page, "index.html")).toMatchObject({
+    display: "",
+  });
+  expect(await fileBodyLayout(page, "about.html")).toMatchObject({
+    display: "",
+  });
+});
+
+test("screen-row hide and lock state is enforced by the overview canvas", async ({
+  page,
+}) => {
+  const homeRow = homeLayerRow(page).locator(
+    'xpath=ancestor::*[@role="treeitem"][1]',
+  );
+  await expect(homeRow).toBeVisible();
+  await expect(screenShell(page)).toBeVisible();
+
+  await homeRow.hover();
+  await homeRow.locator('button[aria-label="Hide layer"]').click({
+    force: true,
+  });
+  await expect(screenShell(page)).toBeHidden();
+  await expect(
+    homeRow.locator('button[aria-label="Show layer"]'),
+  ).toBeVisible();
+
+  await homeRow.locator('button[aria-label="Show layer"]').click({
+    force: true,
+  });
+  const restoredShell = screenShell(page);
+  await expect(restoredShell).toBeVisible();
+  const geometryBeforeLock = await restoredShell.boundingBox();
+  if (!geometryBeforeLock) throw new Error("missing restored Home screen");
+
+  await homeRow.hover();
+  await homeRow.locator('button[aria-label="Lock layer"]').click({
+    force: true,
+  });
+  await expect(
+    homeRow.locator('button[aria-label="Unlock layer"]'),
+  ).toBeVisible();
+  await expect(page.locator("[data-frame-selection-box]")).toHaveCount(0);
+
+  await dragBetween(
+    page,
+    {
+      x: geometryBeforeLock.x + geometryBeforeLock.width * 0.35,
+      y: geometryBeforeLock.y + 12,
+    },
+    {
+      x: geometryBeforeLock.x + geometryBeforeLock.width * 0.35 + 120,
+      y: geometryBeforeLock.y + 92,
+    },
+  );
+  const geometryAfterLockedDrag = await restoredShell.boundingBox();
+  expect(geometryAfterLockedDrag).not.toBeNull();
+  expect(
+    Math.abs(geometryAfterLockedDrag!.x - geometryBeforeLock.x),
+  ).toBeLessThan(2);
+  expect(
+    Math.abs(geometryAfterLockedDrag!.y - geometryBeforeLock.y),
+  ).toBeLessThan(2);
+
+  await homeRow.locator('button[aria-label="Unlock layer"]').click({
+    force: true,
+  });
+  await page.mouse.click(
+    geometryAfterLockedDrag!.x + geometryAfterLockedDrag!.width * 0.35,
+    geometryAfterLockedDrag!.y + 12,
+  );
+  await expect(page.locator("[data-frame-selection-box]")).toBeVisible();
+});
+
+test("screen layer rows reorder the canonical canvas stack with undo, redo, and persistence", async ({
+  page,
+}) => {
+  await postAction(page.request, "create-file", {
+    designId,
+    filename: "about.html",
+    content: FIXTURE_HTML.replace("E2E Fixture", "E2E Second Fixture"),
+    fileType: "html",
+  });
+  await gotoEditor(page, designId);
+
+  await expect
+    .poll(async () => (await topLevelScreenLayerNames(page)).length)
+    .toBe(2);
+  const initialOrder = await topLevelScreenLayerNames(page);
+  const [initialTop, initialBottom] = initialOrder;
+  if (!initialTop || !initialBottom) throw new Error("missing screen rows");
+  const reordered = [initialBottom, initialTop];
+  const files = await designFiles(page);
+  const sourceId = files.find(
+    (file) =>
+      file.filename ===
+      (initialBottom === "Home" ? "index.html" : "about.html"),
+  )?.id;
+  const targetId = files.find(
+    (file) =>
+      file.filename === (initialTop === "Home" ? "index.html" : "about.html"),
+  )?.id;
+  if (!sourceId || !targetId) throw new Error("missing screen file ids");
+  const sourceIsPersistedAboveTarget = async () => {
+    const data = await designData(page);
+    return (
+      Number(data.canvasFrames?.[sourceId]?.z) >
+      Number(data.canvasFrames?.[targetId]?.z)
+    );
+  };
+
+  await dispatchLayerRowDrag(page, initialBottom, initialTop, "top");
+  await expect.poll(() => topLevelScreenLayerNames(page)).toEqual(reordered);
+  await expect.poll(sourceIsPersistedAboveTarget).toBe(true);
+
+  await page.keyboard.press(
+    process.platform === "darwin" ? "Meta+z" : "Control+z",
+  );
+  await expect.poll(() => topLevelScreenLayerNames(page)).toEqual(initialOrder);
+  await expect.poll(sourceIsPersistedAboveTarget).toBe(false);
+
+  await page.keyboard.press(
+    process.platform === "darwin" ? "Meta+Shift+z" : "Control+Shift+z",
+  );
+  await expect.poll(() => topLevelScreenLayerNames(page)).toEqual(reordered);
+  await expect.poll(sourceIsPersistedAboveTarget).toBe(true);
+
+  await gotoEditor(page, designId);
+  await expect.poll(() => topLevelScreenLayerNames(page)).toEqual(reordered);
+
+  const topRow = topLevelScreenLayerRow(page, reordered[0]!);
+  await topRow.hover();
+  await topRow
+    .locator('button[aria-label="Hide layer"]')
+    .click({ force: true });
+  await expect.poll(() => topLevelScreenLayerNames(page)).toEqual(reordered);
+  await topRow
+    .locator('button[aria-label="Show layer"]')
+    .click({ force: true });
+
+  const bottomRow = topLevelScreenLayerRow(page, reordered[1]!);
+  await bottomRow.hover();
+  await bottomRow.locator('button[aria-label="Lock layer"]').click({
+    force: true,
+  });
+  await expect.poll(() => topLevelScreenLayerNames(page)).toEqual(reordered);
+  await bottomRow.locator('button[aria-label="Unlock layer"]').click({
+    force: true,
+  });
+});
+
+test("dragging a screen primitive into a board rectangle nests and persists", async ({
+  page,
+}) => {
+  await postAction(page.request, "create-file", {
+    designId,
+    filename: "about.html",
+    content: FIXTURE_HTML.replace("E2E Fixture", "E2E Second Fixture"),
+    fileType: "html",
+  });
+  await gotoEditor(page, designId);
+  await expect(screenShell(page, "About")).toBeVisible();
+
+  const homeShell = screenShell(page, "Home");
+  const homeCardBox = await homeShell
+    .locator("[data-screen-card]")
+    .boundingBox();
+  if (!homeCardBox) throw new Error("missing Home screen card box");
+
+  // Sidebar/inspector width parity changes alter the fitted screen positions.
+  // Pick a board rectangle dynamically instead of assuming `Home.x - 20` is
+  // empty (that point can now be inside an adjacent screen such as About).
+  const canvasSurfaceBox = await page
+    .locator("[data-multi-screen-canvas-world]")
+    .locator("..")
+    .boundingBox();
+  const screenCardBoxes = await page
+    .locator("[data-screen-card]")
+    .evaluateAll((cards) =>
+      cards.map((card) => {
+        const rect = card.getBoundingClientRect();
+        return {
+          x: rect.x,
+          y: rect.y,
+          width: rect.width,
+          height: rect.height,
+        };
+      }),
+    );
+  if (!canvasSurfaceBox || screenCardBoxes.length === 0) {
+    throw new Error("missing overview canvas geometry");
+  }
+  const boardWidth = 180;
+  const boardHeight = 150;
+  const margin = 24;
+  const minX = Math.min(...screenCardBoxes.map((box) => box.x));
+  const minY = Math.min(...screenCardBoxes.map((box) => box.y));
+  const maxRight = Math.max(...screenCardBoxes.map((box) => box.x + box.width));
+  const maxBottom = Math.max(
+    ...screenCardBoxes.map((box) => box.y + box.height),
+  );
+  const candidates = [
+    { x: minX, y: maxBottom + margin },
+    { x: maxRight + margin, y: minY },
+    { x: minX, y: minY - margin - boardHeight },
+    { x: minX - margin - boardWidth, y: minY },
+  ];
+  const boardOrigin = candidates.find((candidate) => {
+    const insideSurface =
+      candidate.x >= canvasSurfaceBox.x + 4 &&
+      candidate.y >= canvasSurfaceBox.y + 4 &&
+      candidate.x + boardWidth <=
+        canvasSurfaceBox.x + canvasSurfaceBox.width - 4 &&
+      candidate.y + boardHeight <=
+        canvasSurfaceBox.y + canvasSurfaceBox.height - 4;
+    if (!insideSurface) return false;
+    return screenCardBoxes.every(
+      (box) =>
+        candidate.x + boardWidth <= box.x ||
+        candidate.x >= box.x + box.width ||
+        candidate.y + boardHeight <= box.y ||
+        candidate.y >= box.y + box.height,
+    );
+  });
+  if (!boardOrigin) {
+    throw new Error("no visible board area outside every screen card");
+  }
+
+  const boardIdsBefore = await primitiveNodeIds(
+    page,
+    "__board__.html",
+    "rectangle",
+  );
+  const boardStart = {
+    x: boardOrigin.x,
+    y: boardOrigin.y,
+  };
+  const boardEnd = {
+    x: boardStart.x + boardWidth,
+    y: boardStart.y + boardHeight,
+  };
+  await createDraftPrimitive(page, "Rectangle", "Rectangle", {
+    start: boardStart,
+    end: boardEnd,
+  });
+  await expect
+    .poll(() => primitiveNodeIds(page, "__board__.html", "rectangle"), {
+      timeout: 20_000,
+    })
+    .toHaveLength(boardIdsBefore.length + 1);
+  const boardIdsAfter = await primitiveNodeIds(
+    page,
+    "__board__.html",
+    "rectangle",
+  );
+  const targetId = boardIdsAfter.find((id) => !boardIdsBefore.includes(id));
+  if (!targetId) throw new Error("new board rectangle id was not found");
+
+  const homeIdsBefore = await primitiveNodeIds(page, "index.html", "rectangle");
+  await createDraftPrimitive(page, "Rectangle", "Rectangle", {
+    start: {
+      x: homeCardBox.x + homeCardBox.width * 0.1,
+      y: homeCardBox.y + homeCardBox.height * 0.08,
+    },
+    end: {
+      x: homeCardBox.x + homeCardBox.width * 0.2,
+      y: homeCardBox.y + homeCardBox.height * 0.16,
+    },
+  });
+  const homeIdsAfter = await primitiveNodeIds(page, "index.html", "rectangle");
+  const movedId = homeIdsAfter.find((id) => !homeIdsBefore.includes(id));
+  if (!movedId) throw new Error("new screen rectangle id was not found");
+  const movedBox = await primitiveViewportBox(homeShell, movedId);
+
+  await dragBetween(
+    page,
+    {
+      x: movedBox.x + movedBox.width / 2,
+      y: movedBox.y + movedBox.height / 2,
+    },
+    {
+      x: (boardStart.x + boardEnd.x) / 2,
+      y: (boardStart.y + boardEnd.y) / 2,
+    },
+  );
+
+  await expect
+    .poll(
+      async () => ({
+        sourceStillOwnsNode: (
+          await primitiveNodeIds(page, "index.html", "rectangle")
+        ).includes(movedId),
+        boardParentId: await primitiveParentNodeId(
+          page,
+          "__board__.html",
+          movedId,
+        ),
+      }),
+      { timeout: 20_000 },
+    )
+    .toEqual({ sourceStillOwnsNode: false, boardParentId: targetId });
+
+  await gotoEditor(page, designId);
+  await expect
+    .poll(() => primitiveParentNodeId(page, "__board__.html", movedId), {
+      timeout: 20_000,
+    })
+    .toBe(targetId);
+});
+
+test("same-board rectangle nesting into a finite-origin frame persists without poisoned coordinates", async ({
+  page,
+}) => {
+  const boardFile = (await designFiles(page)).find(
+    (file) => file.filename === "__board__.html",
+  );
+  if (!boardFile) throw new Error("board file was not created");
+  const targetId = "e2e-board-frame";
+  const movedId = "e2e-board-rectangle";
+  await postAction(page.request, "update-file", {
+    id: boardFile.id,
+    content: `<!doctype html><html><head><style>html,body{background:transparent}body{margin:0;position:relative;overflow:visible}</style></head><body>
+      <div data-agent-native-node-id="${targetId}" data-agent-native-layer-name="Frame" data-an-primitive="frame" style="position:absolute;left:-190px;top:120px;width:160px;height:180px;overflow:hidden;background:rgba(99,102,241,.12);border:1px solid rgb(99,102,241)"></div>
+      <div data-agent-native-node-id="${movedId}" data-agent-native-layer-name="Rectangle" data-an-primitive="rectangle" style="position:absolute;left:-150px;top:360px;width:60px;height:60px;background:rgb(34,197,94)"></div>
+    </body></html>`,
+  });
+  await gotoEditor(page, designId);
+
+  let movedBox = await boardPrimitiveViewportBox(page, movedId);
+  await page.mouse.click(
+    movedBox.x + movedBox.width / 2,
+    movedBox.y + movedBox.height / 2,
+  );
+  await expect(selectedLayerRow(page)).toContainText("Rectangle");
+  // Selection makes the board the active edit surface. Re-read both boxes
+  // after that state transition before beginning the structural drag.
+  const targetBox = await boardPrimitiveViewportBox(page, targetId);
+  movedBox = await boardPrimitiveViewportBox(page, movedId);
+
+  await dragBetween(
+    page,
+    {
+      x: movedBox.x + movedBox.width / 2,
+      y: movedBox.y + movedBox.height / 2,
+    },
+    {
+      x: targetBox.x + targetBox.width / 2,
+      y: targetBox.y + targetBox.height / 2,
+    },
+  );
+
+  await expect
+    .poll(
+      async () => ({
+        parentId: await primitiveParentNodeId(page, "__board__.html", movedId),
+        position: await primitiveInlinePosition(
+          page,
+          "__board__.html",
+          movedId,
+        ),
+      }),
+      { timeout: 20_000 },
+    )
+    .toEqual({
+      parentId: targetId,
+      position: {
+        left: expect.any(Number),
+        top: expect.any(Number),
+      },
+    });
+  const nestedPosition = await primitiveInlinePosition(
+    page,
+    "__board__.html",
+    movedId,
+  );
+  expect(nestedPosition).not.toBeNull();
+  expect(Math.abs(nestedPosition!.left)).toBeLessThan(240);
+  expect(Math.abs(nestedPosition!.top)).toBeLessThan(180);
+
+  await gotoEditor(page, designId);
+  await expect
+    .poll(() => primitiveParentNodeId(page, "__board__.html", movedId), {
+      timeout: 20_000,
+    })
+    .toBe(targetId);
+  const reloadedPosition = await primitiveInlinePosition(
+    page,
+    "__board__.html",
+    movedId,
+  );
+  expect(reloadedPosition).toEqual(nestedPosition);
 });
 
 test("frame insertion inside a screen creates a nested frame", async ({
@@ -1216,9 +2553,12 @@ test("frame drawn left of the first screen creates a new screen", async ({
   );
   if (!newScreen) throw new Error("new screen file was not created");
 
-  const frameData = await designData(page);
-  const newFrameGeometry = frameData.canvasFrames?.[newScreen.id];
-  expect(newFrameGeometry?.x).toBeLessThan(0);
+  await expect
+    .poll(
+      async () => (await designData(page)).canvasFrames?.[newScreen.id]?.x,
+      { timeout: 20_000 },
+    )
+    .toBeLessThan(0);
 });
 
 test("rectangle drawn left of the first screen persists on the board", async ({
@@ -1265,6 +2605,44 @@ test("rectangle drawn left of the first screen persists on the board", async ({
       return Math.min(...positions);
     })
     .toBeLessThan(0);
+
+  await expect
+    .poll(
+      async () => {
+        const summary = await negativeBoardRectangleViewport(page);
+        return Boolean(
+          summary &&
+          summary.iframeWidth <= 24_576 &&
+          summary.iframeHeight <= 24_576 &&
+          summary.rectX >= 0 &&
+          summary.rectY >= 0 &&
+          summary.rectRight <= summary.iframeWidth &&
+          summary.rectBottom <= summary.iframeHeight &&
+          summary.offsetStyle.includes("translate:"),
+        );
+      },
+      { timeout: 20_000 },
+    )
+    .toBe(true);
+
+  // The finite render origin is derived again after a cold load. The board
+  // node must remain inside the iframe viewport instead of reverting to the
+  // old fixed +/-65536 projection and becoming visually clipped.
+  await gotoEditor(page, designId);
+  await expect
+    .poll(
+      async () => {
+        const summary = await negativeBoardRectangleViewport(page);
+        return Boolean(
+          summary &&
+          summary.iframeWidth <= 24_576 &&
+          summary.rectX >= 0 &&
+          summary.rectRight <= summary.iframeWidth,
+        );
+      },
+      { timeout: 20_000 },
+    )
+    .toBe(true);
 });
 
 test("pen escape cancels the in-progress path and enter commits vector art", async ({
diff --git a/templates/design/e2e/code-native-deep-surfaces.spec.ts b/templates/design/e2e/code-native-deep-surfaces.spec.ts
index 541a7fab30..2b44eedfe4 100644
--- a/templates/design/e2e/code-native-deep-surfaces.spec.ts
+++ b/templates/design/e2e/code-native-deep-surfaces.spec.ts
@@ -125,7 +125,12 @@ async function waitForAction(
 }
 
 async function selectedElementBackgroundImage(page: Page): Promise<string> {
-  return designFrame(page)
+  return page
+    .locator(
+      `iframe[data-design-preview-iframe][data-screen-iframe-id="${fileId}"]`,
+    )
+    .first()
+    .contentFrame()
     .locator('[data-agent-native-node-id="e2e-alpha-button"]')
     .evaluate((el) => window.getComputedStyle(el).backgroundImage);
 }
@@ -207,7 +212,7 @@ test.beforeEach(async ({ page }) => {
 test("Inspect Code shows the opening tag and copyable selected HTML", async ({
   page,
 }) => {
-  await selectByText(page, "Alpha Button");
+  await selectByText(page, "Alpha Button", { screenId: fileId });
   await page.getByRole("button", { name: "Inspect code", exact: true }).click();
 
   await expect(page.getByText("Inspect code", { exact: true })).toBeVisible();
@@ -215,13 +220,16 @@ test("Inspect Code shows the opening tag and copyable selected HTML", async ({
     page
       .locator("code")
       .filter({
-        hasText: /<button[^>]*data-agent-native-node-id="e2e-alpha-button"/,
+        hasText: /^<button>\s+\.\.\.\s+<\/button>$/,
       })
       .first(),
   ).toBeVisible();
-  await expect(
-    page.locator("pre").filter({ hasText: "Alpha Button" }).first(),
-  ).toContainText('data-agent-native-layer-name="Alpha Button"');
+  const inspectCode = page
+    .locator("pre")
+    .filter({ hasText: "<button>" })
+    .first();
+  await expect(inspectCode).not.toContainText("data-agent-native-");
+  await expect(inspectCode).not.toContainText("style=");
   await expect(
     page.getByRole("button", { name: "Copy", exact: true }),
   ).toBeEnabled();
@@ -231,7 +239,7 @@ test("component boolean and text prop controls persist through reload", async ({
   page,
   request,
 }) => {
-  await selectByText(page, "Widget Surface");
+  await selectByText(page, "Widget Surface", { screenId: fileId });
   const componentSection = page.getByTestId("component-section");
   await expect(componentSection).toContainText("E2EWidget");
 
@@ -280,7 +288,7 @@ test("component boolean and text prop controls persist through reload", async ({
 
   await gotoEditor(page, designId);
   await page.getByRole("tab", { name: "Design", exact: true }).click();
-  await selectByText(page, "Widget Surface");
+  await selectByText(page, "Widget Surface", { screenId: fileId });
   await expect
     .poll(() =>
       designFrame(page)
@@ -334,10 +342,10 @@ test("shader preview is transient while apply-shader-fill persists", async ({
   page,
   request,
 }) => {
-  await selectByText(page, "Alpha Button");
+  await selectByText(page, "Alpha Button", { screenId: fileId });
   await expect.poll(() => selectedElementBackgroundImage(page)).toBe("none");
 
-  await page.getByRole("tab", { name: "Extensions", exact: true }).click();
+  await page.getByRole("button", { name: "Tools", exact: true }).click();
   await page.getByRole("button", { name: /Shader Fills/ }).click();
   await page.getByRole("button", { name: "Browse Shaders" }).click();
   await page.getByRole("button", { name: "Mesh Gradient" }).click();
@@ -370,7 +378,7 @@ test("shader preview is transient while apply-shader-fill persists", async ({
       currentContent: shaderCurrentContent,
     },
   });
-  expect(applied.ok).toBe(true);
+  expect(applied.ok, JSON.stringify(applied, null, 2)).toBe(true);
   expect(applied.persisted).toBe(true);
   expect(typeof applied.updatedAt).toBe("string");
   expect(applied.updatedAt).not.toBe(shaderSourceFile.updatedAt);
@@ -455,7 +463,13 @@ test("repeated motion writes replace the managed CSS block instead of duplicatin
   request,
 }) => {
   const motionPendingSentinel = "<!-- motion-current-content-sentinel -->";
-  const motionCurrentContent = (await fileContent(request)).replace(
+  const motionSourceFile = await fileRecord(request);
+  if (!motionSourceFile.updatedAt) {
+    throw new Error(
+      "Motion fixture file did not include an updatedAt revision",
+    );
+  }
+  const motionCurrentContent = motionSourceFile.content.replace(
     "</body>",
     `${motionPendingSentinel}\n  </body>`,
   );
@@ -463,6 +477,7 @@ test("repeated motion writes replace the managed CSS block instead of duplicatin
     designId,
     fileId,
     currentContent: motionCurrentContent,
+    revision: motionSourceFile.updatedAt,
     tracks: [
       {
         targetNodeId: "e2e-alpha-button",
@@ -478,11 +493,16 @@ test("repeated motion writes replace the managed CSS block instead of duplicatin
   });
   expect(first.persisted).toBe(true);
 
+  const secondMotionSourceFile = await fileRecord(request);
+  if (!secondMotionSourceFile.updatedAt) {
+    throw new Error("Saved motion file did not include an updatedAt revision");
+  }
   const second = await postAction(request, "apply-motion-edit", {
     designId,
     fileId,
     timelineId: first.timelineId,
-    currentContent: await fileContent(request),
+    currentContent: secondMotionSourceFile.content,
+    revision: secondMotionSourceFile.updatedAt,
     tracks: [
       {
         targetNodeId: "e2e-alpha-button",
@@ -513,12 +533,14 @@ test("repeated motion writes replace the managed CSS block instead of duplicatin
   await gotoEditor(page, designId);
   await expect
     .poll(() =>
-      designFrame(page).locator("style[data-agent-native-motion]").count(),
+      designFrame(page, fileId)
+        .locator("style[data-agent-native-motion]")
+        .count(),
     )
     .toBe(1);
   await expect
     .poll(() =>
-      designFrame(page)
+      designFrame(page, fileId)
         .locator("style[data-agent-native-motion]")
         .first()
         .textContent(),
diff --git a/templates/design/e2e/code-native-pr-surfaces.spec.ts b/templates/design/e2e/code-native-pr-surfaces.spec.ts
index 4f0d58666a..5e977f1b82 100644
--- a/templates/design/e2e/code-native-pr-surfaces.spec.ts
+++ b/templates/design/e2e/code-native-pr-surfaces.spec.ts
@@ -10,6 +10,7 @@ import { FIXTURE_HTML, seedComponentVariantMetadata } from "./global-setup";
 import { designFrame, gotoEditor, selectByText } from "./helpers";
 
 let designId: string;
+let fileId: string;
 let baseURLForActions: string;
 
 async function postAction(
@@ -46,12 +47,14 @@ test.beforeAll(async ({ request }, workerInfo) => {
     throw new Error(`create-design did not return an id: ${created}`);
   }
 
-  await postAction(request, "create-file", {
+  const file = await postAction(request, "create-file", {
     designId,
     filename: "index.html",
     content: FIXTURE_HTML,
     fileType: "html",
   });
+  fileId = file.id;
+  if (!fileId) throw new Error("create-file did not return an id");
   await postAction(request, "index-components", { designId });
   await seedComponentVariantMetadata(designId);
 });
@@ -132,7 +135,9 @@ async function editTokenValue(
 test("inline component prop dropdown persists on the selected component", async ({
   page,
 }) => {
-  const payload = await selectByText(page, "Variant CTA");
+  const payload = await selectByText(page, "Variant CTA", {
+    screenId: fileId,
+  });
   expect(payload?.selector ?? "").toContain("data-agent-native-node-id");
 
   const componentSection = page.getByTestId("component-section");
@@ -151,7 +156,7 @@ test("inline component prop dropdown persists on the selected component", async
 
   await gotoEditor(page, designId);
   await page.getByRole("tab", { name: "Design", exact: true }).click();
-  await selectByText(page, "Variant CTA");
+  await selectByText(page, "Variant CTA", { screenId: fileId });
   await expect(
     page.getByTestId("component-section").getByRole("combobox").first(),
   ).toContainText("secondary");
@@ -235,7 +240,7 @@ test("Review panel runs an audit and applies an inline a11y fix", async ({
 test("Motion dock autosaves track edits to CSS and reopens them", async ({
   page,
 }) => {
-  await selectByText(page, "Alpha Button");
+  await selectByText(page, "Alpha Button", { screenId: fileId });
 
   await expect(page.locator('[aria-label="Motion dock"]')).toHaveCount(0);
   const motionRailButton = page.getByRole("button", {
@@ -302,7 +307,7 @@ test("Motion dock autosaves track edits to CSS and reopens them", async ({
 
   const motionDock = page.locator('[aria-label="Motion dock"]').first();
   await motionDock
-    .getByRole("button", { name: "Add track", exact: true })
+    .getByRole("button", { name: "Add motion", exact: true })
     .last()
     .click();
   const motionResponse = await waitForAction(
@@ -310,7 +315,7 @@ test("Motion dock autosaves track edits to CSS and reopens them", async ({
     "apply-motion-edit",
     async () => {
       await page
-        .getByRole("menuitem", { name: "Fade (opacity)", exact: true })
+        .getByRole("menuitem", { name: "Opacity", exact: true })
         .click();
     },
   );
@@ -325,8 +330,8 @@ test("Motion dock autosaves track edits to CSS and reopens them", async ({
     motionDock.getByRole("button", { name: "Alpha Button" }),
   ).toBeVisible();
   await expect(page.getByText("opacity", { exact: true })).toBeVisible();
-  await expect(page.getByLabel("Keyframe at 0%")).toBeVisible();
-  await expect(page.getByLabel("Keyframe at 100%")).toBeVisible();
+  await expect(page.getByLabel("Keyframe at 0ms")).toBeVisible();
+  await expect(page.getByLabel("Keyframe at 2000ms")).toBeVisible();
 
   await gotoEditor(page, designId);
   await expect
@@ -386,8 +391,8 @@ test("Motion dock autosaves track edits to CSS and reopens them", async ({
     motionDock.getByRole("button", { name: "Alpha Button" }),
   ).toBeVisible();
   await expect(page.getByText("opacity", { exact: true })).toBeVisible();
-  await expect(page.getByLabel("Keyframe at 0%")).toBeVisible();
-  await expect(page.getByLabel("Keyframe at 100%")).toBeVisible();
+  await expect(page.getByLabel("Keyframe at 0ms")).toBeVisible();
+  await expect(page.getByLabel("Keyframe at 4000ms")).toBeVisible();
 
   await gotoEditor(page, designId);
   await expect
@@ -400,7 +405,7 @@ test("Motion dock autosaves track edits to CSS and reopens them", async ({
 test("shader fill preview opens when the paint surface is reachable", async ({
   page,
 }) => {
-  await selectByText(page, "Alpha Button");
+  await selectByText(page, "Alpha Button", { screenId: fileId });
 
   await page.getByRole("button", { name: "Tools", exact: true }).click();
   await page.getByRole("button", { name: /Shader Fills/ }).click();
diff --git a/templates/design/e2e/constraints-responsive.spec.ts b/templates/design/e2e/constraints-responsive.spec.ts
new file mode 100644
index 0000000000..6e87ebe470
--- /dev/null
+++ b/templates/design/e2e/constraints-responsive.spec.ts
@@ -0,0 +1,234 @@
+import {
+  expect,
+  test,
+  type APIRequestContext,
+  type Page,
+} from "@playwright/test";
+
+import { designFrame, enterDirectMode, gotoEditor } from "./helpers";
+
+const CONSTRAINTS_HTML = `<!doctype html>
+<html>
+  <head><meta charset="utf-8"><title>Constraint resize fixture</title></head>
+  <body x-data="{}" style="margin:0;min-height:100vh;padding:20px;font-family:Arial,sans-serif">
+    <div data-agent-native-node-id="outer-frame" style="position:relative;width:720px;height:620px;padding:30px;background:#eee">
+      <div data-agent-native-node-id="nested-frame" style="position:relative;width:400px;height:300px;background:#fff">
+        <div data-agent-native-node-id="left-top" style="position:absolute;left:20px;top:20px;width:60px;height:30px;background:#fecaca">Left Top</div>
+        <div data-agent-native-node-id="right-bottom" style="position:absolute;left:110px;top:60px;width:70px;height:35px;background:#fed7aa">Right Bottom</div>
+        <div data-agent-native-node-id="stretch" style="position:absolute;left:40px;top:110px;width:120px;height:40px;background:#fef08a">Stretch Both</div>
+        <div data-agent-native-node-id="center" style="position:absolute;left:180px;top:170px;width:80px;height:45px;background:#bbf7d0">Center Both</div>
+        <div data-agent-native-node-id="scale" style="position:absolute;left:80px;top:230px;width:100px;height:50px;background:#bfdbfe">Scale Both</div>
+      </div>
+      <div data-agent-native-node-id="auto-frame" style="position:relative;display:flex;width:400px;height:180px;margin-top:30px;gap:12px;background:#ddd6fe">
+        <div data-agent-native-node-id="flow-child">Flow child</div>
+        <div data-agent-native-node-id="auto-absolute" style="position:absolute;left:100px;top:60px;width:80px;height:40px;background:#f5d0fe">Auto Absolute</div>
+      </div>
+    </div>
+  </body>
+</html>`;
+
+async function postAction(
+  request: APIRequestContext,
+  name: string,
+  input: Record<string, unknown>,
+) {
+  const baseUrl = process.env.E2E_BASE_URL ?? "http://127.0.0.1:9333";
+  const response = await request.post(
+    `${baseUrl.replace(/\/$/, "")}/_agent-native/actions/${name}`,
+    { data: input },
+  );
+  if (!response.ok()) {
+    throw new Error(
+      `${name} failed: ${response.status()} ${await response.text()}`,
+    );
+  }
+  return response.json();
+}
+
+async function selectFixtureLayer(page: Page, nodeId: string) {
+  const layer = designFrame(page).locator(
+    `[data-agent-native-node-id="${nodeId}"]`,
+  );
+  await expect(layer).toBeVisible();
+  await layer.click({ force: true });
+  await expect(page.getByRole("button", { name: "Constraints" })).toBeVisible();
+}
+
+async function chooseConstraint(
+  page: Page,
+  axis: "Horizontal" | "Vertical",
+  option: string,
+) {
+  const trigger = page.getByRole("button", { name: "Constraints" });
+  if ((await trigger.getAttribute("aria-pressed")) !== "true") {
+    await trigger.click();
+  }
+  await page.getByRole("combobox", { name: axis }).click();
+  await page.getByRole("option", { name: option, exact: true }).click();
+}
+
+type Geometry = {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  right: number;
+  bottom: number;
+  centerX: number;
+  centerY: number;
+};
+
+async function relativeGeometry(page: Page, nodeId: string): Promise<Geometry> {
+  return designFrame(page)
+    .locator(`[data-agent-native-node-id="${nodeId}"]`)
+    .evaluate((element) => {
+      const child = element.getBoundingClientRect();
+      const parent = element.parentElement!.getBoundingClientRect();
+      const left = child.left - parent.left;
+      const top = child.top - parent.top;
+      return {
+        left,
+        top,
+        width: child.width,
+        height: child.height,
+        right: parent.right - child.right,
+        bottom: parent.bottom - child.bottom,
+        centerX: left + child.width / 2 - parent.width / 2,
+        centerY: top + child.height / 2 - parent.height / 2,
+      };
+    });
+}
+
+function expectClose(actual: number, expected: number, tolerance = 0.75) {
+  expect(Math.abs(actual - expected)).toBeLessThanOrEqual(tolerance);
+}
+
+test("constraints preserve Figma geometry through real nested and auto-layout parent resizes", async ({
+  page,
+  request,
+}) => {
+  const created = await postAction(request, "create-design", {
+    title: `Constraint resize ${Date.now()}`,
+    projectType: "prototype",
+  });
+  const designId = created.id ?? created.data?.id ?? created.design?.id;
+  if (!designId) throw new Error("create-design returned no id");
+
+  try {
+    await postAction(request, "create-file", {
+      designId,
+      filename: "index.html",
+      content: CONSTRAINTS_HTML,
+      fileType: "html",
+    });
+    await gotoEditor(page, designId);
+    await enterDirectMode(page);
+    await page.getByRole("tab", { name: "Design", exact: true }).click();
+
+    await selectFixtureLayer(page, "right-bottom");
+    await chooseConstraint(page, "Horizontal", "Right");
+    await chooseConstraint(page, "Vertical", "Bottom");
+
+    await selectFixtureLayer(page, "stretch");
+    await chooseConstraint(page, "Horizontal", "Left and right");
+    await chooseConstraint(page, "Vertical", "Top and bottom");
+
+    await selectFixtureLayer(page, "center");
+    await chooseConstraint(page, "Horizontal", "Center");
+    await chooseConstraint(page, "Vertical", "Center");
+
+    await selectFixtureLayer(page, "scale");
+    await chooseConstraint(page, "Horizontal", "Scale");
+    await chooseConstraint(page, "Vertical", "Scale");
+
+    await selectFixtureLayer(page, "auto-absolute");
+    await chooseConstraint(page, "Horizontal", "Scale");
+    await chooseConstraint(page, "Vertical", "Scale");
+
+    const ids = [
+      "left-top",
+      "right-bottom",
+      "stretch",
+      "center",
+      "scale",
+      "auto-absolute",
+    ] as const;
+    const before = Object.fromEntries(
+      await Promise.all(
+        ids.map(async (id) => [id, await relativeGeometry(page, id)]),
+      ),
+    ) as Record<(typeof ids)[number], Geometry>;
+
+    await designFrame(page)
+      .locator('[data-agent-native-node-id="nested-frame"]')
+      .evaluate((element) => {
+        const frame = element as HTMLElement;
+        frame.style.width = "600px";
+        frame.style.height = "450px";
+      });
+    await designFrame(page)
+      .locator('[data-agent-native-node-id="auto-frame"]')
+      .evaluate((element) => {
+        const frame = element as HTMLElement;
+        frame.style.width = "600px";
+        frame.style.height = "270px";
+      });
+
+    const after = Object.fromEntries(
+      await Promise.all(
+        ids.map(async (id) => [id, await relativeGeometry(page, id)]),
+      ),
+    ) as Record<(typeof ids)[number], Geometry>;
+
+    // Left/Top: position and fixed size stay constant.
+    for (const key of ["left", "top", "width", "height"] as const) {
+      expectClose(after["left-top"][key], before["left-top"][key]);
+    }
+    // Right/Bottom: opposite-edge gaps and fixed size stay constant.
+    for (const key of ["right", "bottom", "width", "height"] as const) {
+      expectClose(after["right-bottom"][key], before["right-bottom"][key]);
+    }
+    // Dual-edge pins stretch by the parent's exact resize delta.
+    expectClose(after.stretch.left, before.stretch.left);
+    expectClose(after.stretch.right, before.stretch.right);
+    expectClose(after.stretch.top, before.stretch.top);
+    expectClose(after.stretch.bottom, before.stretch.bottom);
+    expectClose(after.stretch.width, before.stretch.width + 200);
+    expectClose(after.stretch.height, before.stretch.height + 150);
+    // Center preserves its offset from the parent's center, never recenters.
+    expectClose(after.center.centerX, before.center.centerX);
+    expectClose(after.center.centerY, before.center.centerY);
+    expectClose(after.center.width, before.center.width);
+    expectClose(after.center.height, before.center.height);
+    // Scale preserves position and size ratios on both axes.
+    expectClose(after.scale.left / 600, before.scale.left / 400, 0.002);
+    expectClose(after.scale.top / 450, before.scale.top / 300, 0.002);
+    expectClose(after.scale.width / 600, before.scale.width / 400, 0.002);
+    expectClose(after.scale.height / 450, before.scale.height / 300, 0.002);
+    // Absolute children of auto-layout parents use the same proportional path.
+    expectClose(
+      after["auto-absolute"].left / 600,
+      before["auto-absolute"].left / 400,
+      0.002,
+    );
+    expectClose(
+      after["auto-absolute"].top / 270,
+      before["auto-absolute"].top / 180,
+      0.002,
+    );
+    expectClose(
+      after["auto-absolute"].width / 600,
+      before["auto-absolute"].width / 400,
+      0.002,
+    );
+    expectClose(
+      after["auto-absolute"].height / 270,
+      before["auto-absolute"].height / 180,
+      0.002,
+    );
+  } finally {
+    await postAction(request, "delete-design", { id: designId }).catch(
+      () => {},
+    );
+  }
+});
diff --git a/templates/design/e2e/editor.spec.ts b/templates/design/e2e/editor.spec.ts
index 5a63b25f4f..67a6d5ac49 100644
--- a/templates/design/e2e/editor.spec.ts
+++ b/templates/design/e2e/editor.spec.ts
@@ -42,15 +42,15 @@ test("editor renders the toolbar and the design iframe content", async ({
   expect(nodeCount).toBeGreaterThanOrEqual(5);
 });
 
-test("share dialog uses compact editor panel chrome", async ({
-  page,
-}, testInfo) => {
+test("share dialog uses editor panel chrome", async ({ page }, testInfo) => {
   await page
-    .getByRole("button", { name: /^share$/i })
+    .getByRole("button", { name: /^share(?: \(.+\))?$/i })
     .first()
     .click();
 
-  const shareOptions = page.getByRole("tablist", { name: "Share options" });
+  const shareOptions = page.locator(
+    '[role="tablist"][aria-label="Share options"]',
+  );
   await expect(shareOptions).toBeVisible();
 
   const tabListBox = await shareOptions.boundingBox();
@@ -58,13 +58,13 @@ test("share dialog uses compact editor panel chrome", async ({
     340,
   );
   expect(tabListBox?.height ?? Number.POSITIVE_INFINITY).toBeLessThanOrEqual(
-    28,
+    42,
   );
 
   const sendTab = page.getByRole("tab", { name: "Send to agent" });
   const sendTabBox = await sendTab.boundingBox();
   expect(sendTabBox?.height ?? Number.POSITIVE_INFINITY).toBeLessThanOrEqual(
-    26,
+    36,
   );
 
   await sendTab.click();
@@ -83,7 +83,7 @@ test("share dialog uses compact editor panel chrome", async ({
   );
 
   await page.getByRole("tab", { name: "Share link" }).click();
-  await page.getByRole("button", { name: "General access" }).click();
+  await page.getByRole("combobox", { name: "General access" }).click();
   await expect(
     page.getByRole("option", { name: /Organization/ }),
   ).toBeVisible();
@@ -107,27 +107,36 @@ test("share dialog uses compact editor panel chrome", async ({
   await cdpScreenshot(page, testInfo.outputPath("share-dialog-compact.png"));
 });
 
-test("screen overview resizes previews from the device selector", async ({
+test("screen overview adds and targets frames from the unified breakpoint control", async ({
   page,
 }) => {
-  const firstScreenCard = page.locator("[data-screen-card]").first();
-  await expect(firstScreenCard).toBeVisible();
-
-  await page.getByRole("button", { name: "Device preview" }).first().click();
-  await page.getByRole("menuitemradio", { name: "Desktop" }).click();
-  await expect(page.getByText("1280 x 800").first()).toBeVisible();
-  const desktopBox = await firstScreenCard.boundingBox();
-  if (!desktopBox) throw new Error("missing desktop screen card bounds");
-
-  await page.getByRole("button", { name: "Device preview" }).first().click();
-  await page.getByRole("menuitemradio", { name: "Mobile" }).click();
-  await expect(page.getByText("390 x 844").first()).toBeVisible();
-  await expect
-    .poll(async () => (await firstScreenCard.boundingBox())?.width ?? 0)
-    .toBeLessThan(desktopBox.width - 1);
+  const breakpointControl = page.locator("[data-breakpoint-device-control]");
+  await expect(
+    breakpointControl.getByRole("button", { name: "Base" }),
+  ).toHaveAttribute("aria-pressed", "true");
 
-  await page.getByRole("button", { name: "Device preview" }).first().click();
-  await page.getByRole("menuitemradio", { name: "Responsive" }).click();
+  await breakpointControl
+    .getByRole("button", { name: "Add breakpoint" })
+    .click();
+  await page.getByRole("button", { name: /Phone/ }).click();
+
+  const mobileTarget = breakpointControl.getByRole("button", { name: "390" });
+  await expect(mobileTarget).toBeVisible();
+  await expect(page.locator("[data-breakpoint-frame]")).toHaveCount(1);
+  await mobileTarget.click();
+  await expect(mobileTarget).toHaveAttribute("aria-pressed", "true");
+  await breakpointControl.getByRole("button", { name: "Base" }).click();
+  await expect(
+    breakpointControl.getByRole("button", { name: "Base" }),
+  ).toHaveAttribute("aria-pressed", "true");
+
+  // Leave the shared seed design pristine for later inspector/browser specs.
+  await mobileTarget.click();
+  await breakpointControl
+    .getByRole("button", { name: "Breakpoint options" })
+    .click();
+  await page.getByRole("menuitem", { name: "Remove breakpoint" }).click();
+  await expect(page.locator("[data-breakpoint-frame]")).toHaveCount(0);
 });
 
 test("screen overview keeps the name readable when frame header space is tight", async ({
diff --git a/templates/design/e2e/global-setup.ts b/templates/design/e2e/global-setup.ts
index 6ad70359d6..7134b86eae 100644
--- a/templates/design/e2e/global-setup.ts
+++ b/templates/design/e2e/global-setup.ts
@@ -22,12 +22,9 @@ const AUTH_DIR = process.env.E2E_AUTH_DIR
 const STATE_PATH = path.join(AUTH_DIR, "state.json");
 const SEED_PATH = path.join(AUTH_DIR, "seed.json");
 const BROWSER_CHANNEL = process.env.E2E_BROWSER_CHANNEL;
-const E2E_DATABASE_URL = `file:${path.join(
-  import.meta.dirname,
-  "..",
-  "data",
-  "e2e.db",
-)}`;
+const E2E_DATABASE_URL =
+  process.env.E2E_DATABASE_URL ??
+  `file:${path.join(import.meta.dirname, "..", "data", "e2e.db")}`;
 
 /**
  * Fixture HTML with distinct, text-identifiable elements. Plain inline styles
diff --git a/templates/design/e2e/helpers.ts b/templates/design/e2e/helpers.ts
index a0f120bc66..9c3cc5b662 100644
--- a/templates/design/e2e/helpers.ts
+++ b/templates/design/e2e/helpers.ts
@@ -116,8 +116,13 @@ export function appPath(path: string): string {
   return `${route.pathname}${route.search}${route.hash}`;
 }
 
-export function designFrame(page: Page): FrameLocator {
-  return page.locator(DESIGN_PREVIEW_IFRAME_SELECTOR).last().contentFrame();
+export function designFrame(page: Page, screenId?: string): FrameLocator {
+  const iframe = screenId
+    ? page.locator(
+        `${DESIGN_PREVIEW_IFRAME_SELECTOR}[data-screen-iframe-id="${screenId}"]`,
+      )
+    : page.locator(DESIGN_PREVIEW_IFRAME_SELECTOR).last();
+  return iframe.contentFrame();
 }
 
 async function selectableNodeByText(
@@ -203,6 +208,7 @@ async function waitForDesignBridgeReady(page: Page): Promise<void> {
             .locator("[data-screen-shell]")
             .first()
             .locator("[data-screen-card]")
+            .first()
             .boundingBox();
           return box && box.width > 0 && box.height > 0;
         },
@@ -213,7 +219,10 @@ async function waitForDesignBridgeReady(page: Page): Promise<void> {
   }
 }
 
-export async function enterDirectMode(page: Page): Promise<void> {
+export async function enterDirectMode(
+  page: Page,
+  options?: { screenId?: string },
+): Promise<void> {
   const fullView = page.getByRole("button", { name: "Full view", exact: true });
   const fullViewVisible = await fullView
     .first()
@@ -221,7 +230,15 @@ export async function enterDirectMode(page: Page): Promise<void> {
     .then(() => true)
     .catch(() => false);
   if (fullViewVisible) {
-    await fullView.last().click();
+    const targetFullView = options?.screenId
+      ? page
+          .locator(
+            `[data-screen-shell][data-frame-id="${options.screenId.replace(/"/g, '\\"')}"]`,
+          )
+          .getByRole("button", { name: "Full view", exact: true })
+      : fullView.last();
+    await expect(targetFullView).toHaveCount(1);
+    await targetFullView.click();
     await expect(fullView).toHaveCount(0);
   }
   await expect
@@ -285,8 +302,12 @@ export async function waitForBridge(
  * resulting `element-select` payload. Uses force:true to punch through the
  * shield overlay (which is what actually drives selection).
  */
-export async function selectByText(page: Page, text: string): Promise<any> {
-  await enterDirectMode(page);
+export async function selectByText(
+  page: Page,
+  text: string,
+  options?: { screenId?: string },
+): Promise<any> {
+  await enterDirectMode(page, options);
   await installBridge(page);
   await page.evaluate(() => ((window as any).__bridge = []));
   const target = await selectableNodeByText(page, text);
diff --git a/templates/design/e2e/inspector-styles.spec.ts b/templates/design/e2e/inspector-styles.spec.ts
index 6f9537074e..6681c525a1 100644
--- a/templates/design/e2e/inspector-styles.spec.ts
+++ b/templates/design/e2e/inspector-styles.spec.ts
@@ -12,9 +12,6 @@ import {
 
 let designId: string;
 
-const DATA_URI_1X1_PNG =
-  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+j1uoAAAAASUVORK5CYII=";
-
 test.beforeAll(async () => {
   designId = await readSeedDesignId();
 });
@@ -138,6 +135,27 @@ async function selectedElementStyle(
     );
 }
 
+async function resolvedColorChannels(
+  page: Page,
+  value: string,
+): Promise<{ rgb: [number, number, number]; alpha: number }> {
+  return page.evaluate((color) => {
+    const probe = document.createElement("span");
+    probe.style.color = color;
+    document.body.append(probe);
+    const resolved = getComputedStyle(probe).color;
+    probe.remove();
+    const channels = resolved.match(/\d+(?:\.\d+)?/g)?.map(Number) ?? [];
+    if (channels.length < 3) {
+      throw new Error(`Could not resolve color channels for ${color}`);
+    }
+    return {
+      rgb: [channels[0]!, channels[1]!, channels[2]!],
+      alpha: channels[3] ?? 1,
+    };
+  }, value);
+}
+
 test("page background supports gradient edits", async ({ page }) => {
   await page.keyboard.press("Escape");
   const pageSection = pagePropertiesSection(page);
@@ -156,7 +174,7 @@ test("page background supports gradient edits", async ({ page }) => {
     .toContain("25%");
 });
 
-test("page background exposes image controls and accepts a tiled data URL", async ({
+test("page background exposes image controls and accepts a tiled image URL", async ({
   page,
 }) => {
   await page.keyboard.press("Escape");
@@ -165,18 +183,29 @@ test("page background exposes image controls and accepts a tiled data URL", asyn
 
   await openColorPicker(pageSection);
   await choosePaintType(page, "Image");
-  await setScrubInput(page, "Image URL", DATA_URI_1X1_PNG);
+  await setScrubInput(page, "Image URL", "/icon-180.svg");
   await page.getByRole("combobox", { name: "Fill", exact: true }).click();
   await page.getByRole("option", { name: "Tile", exact: true }).click();
 
   await expect
     .poll(() => readInlineStyle(page, bodyElement(page), "background-image"))
-    .toContain("data:image/png;base64");
+    .toContain("/icon-180.svg");
   await expect
-    .poll(() => readInlineStyle(page, bodyElement(page), "background-repeat"))
+    .poll(() => readInlineStyle(page, bodyElement(page), "background-image"))
+    .toContain("linear-gradient");
+  await expect
+    .poll(async () =>
+      (await readInlineStyle(page, bodyElement(page), "background-repeat"))
+        .split(",")[0]
+        ?.trim(),
+    )
     .toBe("repeat");
   await expect
-    .poll(() => readInlineStyle(page, bodyElement(page), "background-position"))
+    .poll(async () =>
+      (await readInlineStyle(page, bodyElement(page), "background-position"))
+        .split(",")[0]
+        ?.trim(),
+    )
     .toBe("left top");
 });
 
@@ -200,6 +229,7 @@ test("text fills hide and restore without losing the original color", async ({
     "color",
   );
   expect(initialColor).not.toBe("");
+  const initialChannels = await resolvedColorChannels(page, initialColor);
 
   await expect(hideFillButton).toBeVisible();
   await expect(
@@ -208,8 +238,15 @@ test("text fills hide and restore without losing the original color", async ({
 
   await hideFillButton.click();
   await expect
-    .poll(() => selectedElementStyle(page, "E2E Hero Heading", "color"))
-    .toBe("transparent");
+    .poll(async () => {
+      const hiddenColor = await selectedElementStyle(
+        page,
+        "E2E Hero Heading",
+        "color",
+      );
+      return resolvedColorChannels(page, hiddenColor);
+    })
+    .toEqual({ rgb: initialChannels.rgb, alpha: 0 });
   await expect(showFillButton).toBeVisible();
 
   await showFillButton.click();
diff --git a/templates/design/e2e/large-canvas-performance.spec.ts b/templates/design/e2e/large-canvas-performance.spec.ts
new file mode 100644
index 0000000000..5ca8ec527b
--- /dev/null
+++ b/templates/design/e2e/large-canvas-performance.spec.ts
@@ -0,0 +1,347 @@
+import {
+  expect,
+  test,
+  type APIRequestContext,
+  type Page,
+} from "@playwright/test";
+
+import { appPath } from "./helpers";
+
+const SCREEN_COUNT = 120;
+const CARDS_PER_SCREEN = 24;
+const EXPECTED_AUTHORED_LAYERS = SCREEN_COUNT * (1 + CARDS_PER_SCREEN * 3);
+const LIVE_IFRAME_BUDGET = 32;
+
+interface BrowserPerfState {
+  longTasks: number[];
+  maxEventLoopDelayMs: number;
+  iframeAdded: number;
+  iframeRemoved: number;
+  iframeLoads: number;
+}
+
+function screenHtml(screenIndex: number): string {
+  const cards = Array.from({ length: CARDS_PER_SCREEN }, (_, cardIndex) => {
+    const id = `${screenIndex}-${cardIndex}`;
+    return `<article data-perf-layer="card-${id}" style="padding:12px;border:1px solid #334155;border-radius:10px;background:#111827">
+      <h2 data-perf-layer="title-${id}" style="margin:0;font:600 16px/1.3 system-ui;color:#f8fafc">Card ${cardIndex + 1}</h2>
+      <p data-perf-layer="copy-${id}" style="margin:6px 0 0;font:400 13px/1.4 system-ui;color:#94a3b8">Screen ${screenIndex + 1} deterministic performance content.</p>
+    </article>`;
+  }).join("");
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head>
+    <body style="margin:0;background:#020617;color:#f8fafc">
+      <main data-perf-layer="root-${screenIndex}" style="display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px;padding:20px">${cards}</main>
+    </body></html>`;
+}
+
+async function postAction(
+  request: APIRequestContext,
+  baseURL: string,
+  name: string,
+  input: Record<string, unknown>,
+): Promise<any> {
+  const response = await request.post(
+    `${baseURL}/_agent-native/actions/${name}`,
+    {
+      data: input,
+      headers: { "Content-Type": "application/json" },
+      timeout: 60_000,
+    },
+  );
+  if (!response.ok()) {
+    throw new Error(
+      `${name} failed: ${response.status()} ${await response.text()}`,
+    );
+  }
+  return response.json();
+}
+
+async function createLargeDesign(
+  page: Page,
+  baseURL: string,
+): Promise<{ designId: string; screenIds: string[] }> {
+  const created = await postAction(page.request, baseURL, "create-design", {
+    title: "E2E Large Canvas Performance",
+    projectType: "prototype",
+  });
+  const designId = String(
+    created?.id ?? created?.data?.id ?? created?.design?.id ?? "",
+  );
+  if (!designId) throw new Error("create-design did not return an id");
+
+  const screenIds: string[] = [];
+  const concurrency = 8;
+  for (let start = 0; start < SCREEN_COUNT; start += concurrency) {
+    const batch = Array.from(
+      { length: Math.min(concurrency, SCREEN_COUNT - start) },
+      (_, offset) => start + offset,
+    );
+    const results = await Promise.all(
+      batch.map((index) =>
+        postAction(page.request, baseURL, "create-file", {
+          designId,
+          filename: `screen-${String(index).padStart(3, "0")}.html`,
+          content: screenHtml(index),
+          fileType: "html",
+        }),
+      ),
+    );
+    results.forEach((result) => screenIds.push(String(result.id)));
+  }
+  return { designId, screenIds };
+}
+
+async function installPerfObservers(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    const state = {
+      longTasks: [] as number[],
+      maxEventLoopDelayMs: 0,
+      iframeAdded: 0,
+      iframeRemoved: 0,
+      iframeLoads: 0,
+    };
+    (window as any).__largeCanvasPerf = state;
+
+    let expectedTick = performance.now() + 16;
+    window.setInterval(() => {
+      const now = performance.now();
+      state.maxEventLoopDelayMs = Math.max(
+        state.maxEventLoopDelayMs,
+        Math.max(0, now - expectedTick),
+      );
+      expectedTick = now + 16;
+    }, 16);
+
+    if (
+      typeof PerformanceObserver !== "undefined" &&
+      PerformanceObserver.supportedEntryTypes.includes("longtask")
+    ) {
+      const observer = new PerformanceObserver((list) => {
+        list
+          .getEntries()
+          .forEach((entry) => state.longTasks.push(entry.duration));
+      });
+      observer.observe({ type: "longtask", buffered: true });
+    }
+
+    const iframeCountInNode = (node: Node): number => {
+      if (!(node instanceof Element)) return 0;
+      return (
+        (node.matches("iframe[data-design-preview-iframe]") ? 1 : 0) +
+        node.querySelectorAll("iframe[data-design-preview-iframe]").length
+      );
+    };
+    const mutationObserver = new MutationObserver((records) => {
+      records.forEach((record) => {
+        record.addedNodes.forEach((node) => {
+          state.iframeAdded += iframeCountInNode(node);
+        });
+        record.removedNodes.forEach((node) => {
+          state.iframeRemoved += iframeCountInNode(node);
+        });
+      });
+    });
+    mutationObserver.observe(document, { childList: true, subtree: true });
+    document.addEventListener(
+      "load",
+      (event) => {
+        if (
+          event.target instanceof HTMLIFrameElement &&
+          event.target.matches("iframe[data-design-preview-iframe]")
+        ) {
+          state.iframeLoads += 1;
+        }
+      },
+      true,
+    );
+  });
+}
+
+async function perfState(page: Page): Promise<BrowserPerfState> {
+  return page.evaluate(() => ({ ...(window as any).__largeCanvasPerf }));
+}
+
+async function resetIframeChurn(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    const state = (window as any).__largeCanvasPerf as BrowserPerfState;
+    state.iframeAdded = 0;
+    state.iframeRemoved = 0;
+    state.iframeLoads = 0;
+  });
+}
+
+async function screenSelectionLatency(page: Page, screenId: string) {
+  return page.evaluate(async (id) => {
+    const shell = document.querySelector<HTMLElement>(
+      `[data-screen-shell][data-frame-id="${CSS.escape(id)}"]`,
+    );
+    const clickTarget = shell?.querySelector<HTMLElement>("[data-frame-label]");
+    const rowButton = document.querySelector<HTMLElement>(
+      `[data-layer-row-button][data-layer-node-id="${CSS.escape(id)}"]`,
+    );
+    const row = rowButton?.closest<HTMLElement>('[role="treeitem"]');
+    if (!clickTarget || !row)
+      throw new Error(`missing screen selection DOM for ${id}`);
+    const startedAt = performance.now();
+    clickTarget.dispatchEvent(
+      new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+        view: window,
+      }),
+    );
+    while (performance.now() - startedAt < 2_000) {
+      if (row.getAttribute("aria-selected") === "true") {
+        return performance.now() - startedAt;
+      }
+      await new Promise<void>((resolve) =>
+        requestAnimationFrame(() => resolve()),
+      );
+    }
+    throw new Error(`screen selection did not settle for ${id}`);
+  }, screenId);
+}
+
+test("120-screen canvas stays usable, bounded, and responsive", async ({
+  page,
+}, workerInfo) => {
+  test.setTimeout(240_000);
+  const baseURL =
+    (workerInfo.project.use.baseURL as string | undefined) ??
+    "http://127.0.0.1:9333";
+  const { designId, screenIds } = await createLargeDesign(page, baseURL);
+
+  try {
+    await installPerfObservers(page);
+    const navigationStartedAt = Date.now();
+    await page.goto(appPath(`/design/${designId}`), {
+      waitUntil: "domcontentloaded",
+    });
+    await expect(page.locator("[data-multi-screen-canvas-world]")).toHaveCount(
+      1,
+    );
+    await expect(page.locator("[data-screen-shell]")).toHaveCount(SCREEN_COUNT);
+    await expect
+      .poll(() => page.locator("iframe[data-design-preview-iframe]").count(), {
+        timeout: 30_000,
+      })
+      .toBeGreaterThan(0);
+    const editorUsableMs = Date.now() - navigationStartedAt;
+
+    const iframeCount = await page
+      .locator("iframe[data-design-preview-iframe]")
+      .count();
+    const placeholderCount = await page
+      .locator('[data-screen-content][data-cull-tier="placeholder"]')
+      .count();
+    const authoredLayerCount = await page
+      .locator("[data-screen-shell]")
+      .evaluateAll((shells) =>
+        shells.reduce((count, shell) => {
+          const iframe = shell.querySelector<HTMLIFrameElement>(
+            "iframe[data-design-preview-iframe]",
+          );
+          return (
+            count +
+            (iframe?.contentDocument?.querySelectorAll("[data-perf-layer]")
+              .length ?? 0)
+          );
+        }, 0),
+      );
+    const usablePerf = await perfState(page);
+
+    await resetIframeChurn(page);
+    const surface = page
+      .locator("[data-multi-screen-canvas-world]")
+      .locator("..");
+    const surfaceBox = await surface.boundingBox();
+    if (!surfaceBox) throw new Error("missing overview canvas surface");
+    await page.mouse.move(
+      surfaceBox.x + surfaceBox.width / 2,
+      surfaceBox.y + surfaceBox.height / 2,
+    );
+    for (let index = 0; index < 10; index += 1) {
+      await page.mouse.wheel(24, 18);
+    }
+    await page.keyboard.down("Control");
+    for (let index = 0; index < 6; index += 1) {
+      await page.mouse.wheel(0, index % 2 === 0 ? -28 : 28);
+    }
+    await page.keyboard.up("Control");
+    await page.waitForTimeout(700);
+    const gesturePerf = await perfState(page);
+    const iframeCountAfterGesture = await page
+      .locator("iframe[data-design-preview-iframe]")
+      .count();
+
+    const selectionIds = [0, 15, 30, 45, 60, 75, 90, 105].map(
+      (index) => screenIds[index]!,
+    );
+    const selectionLatencies: number[] = [];
+    for (const screenId of selectionIds) {
+      selectionLatencies.push(await screenSelectionLatency(page, screenId));
+    }
+    selectionLatencies.sort((a, b) => a - b);
+    const selectionP95Ms =
+      selectionLatencies[Math.ceil(selectionLatencies.length * 0.95) - 1]!;
+    const finalPerf = await perfState(page);
+    const loadLongTasks = usablePerf.longTasks;
+    const gestureLongTasks = gesturePerf.longTasks.slice(
+      usablePerf.longTasks.length,
+    );
+    const selectionLongTasks = finalPerf.longTasks.slice(
+      gesturePerf.longTasks.length,
+    );
+    const totalDuration = (durations: readonly number[]) =>
+      durations.reduce((total, duration) => total + duration, 0);
+    const longestDuration = (durations: readonly number[]) =>
+      Math.max(0, ...durations);
+    const longestTaskMs = Math.max(0, ...finalPerf.longTasks);
+
+    console.info(
+      `[large-canvas-perf] ${JSON.stringify({
+        editorUsableMs,
+        iframeCount,
+        iframeCountAfterGesture,
+        placeholderCount,
+        authoredLayerCount,
+        gestureIframeAdded: gesturePerf.iframeAdded,
+        gestureIframeRemoved: gesturePerf.iframeRemoved,
+        gestureIframeLoads: gesturePerf.iframeLoads,
+        longestTaskMs: Math.round(longestTaskMs),
+        loadLongTaskMs: Math.round(totalDuration(loadLongTasks)),
+        gestureLongTaskMs: Math.round(totalDuration(gestureLongTasks)),
+        gestureLongestTaskMs: Math.round(longestDuration(gestureLongTasks)),
+        selectionLongTaskMs: Math.round(totalDuration(selectionLongTasks)),
+        maxEventLoopDelayMs: Math.round(finalPerf.maxEventLoopDelayMs),
+        selectionP95Ms: Math.round(selectionP95Ms),
+      })}`,
+    );
+
+    expect(editorUsableMs).toBeLessThan(20_000);
+    expect(iframeCount).toBeLessThanOrEqual(LIVE_IFRAME_BUDGET);
+    expect(iframeCountAfterGesture).toBeLessThanOrEqual(LIVE_IFRAME_BUDGET);
+    expect(placeholderCount).toBeGreaterThanOrEqual(
+      SCREEN_COUNT - LIVE_IFRAME_BUDGET,
+    );
+    // The 32 live screens alone expose 2,336 authored nodes, so this proves
+    // the browser is exercising a real thousands-of-layers DOM workload even
+    // while the remaining 88 screens stay correctly placeholder-culled.
+    expect(authoredLayerCount).toBeGreaterThanOrEqual(2_000);
+    expect(authoredLayerCount).toBeLessThanOrEqual(EXPECTED_AUTHORED_LAYERS);
+    expect(
+      gesturePerf.iframeAdded + gesturePerf.iframeRemoved,
+    ).toBeLessThanOrEqual(12);
+    expect(gesturePerf.iframeLoads).toBeLessThanOrEqual(6);
+    expect(longestTaskMs).toBeLessThan(1_500);
+    expect(totalDuration(loadLongTasks)).toBeLessThan(5_000);
+    expect(totalDuration(gestureLongTasks)).toBeLessThan(1_500);
+    expect(longestDuration(gestureLongTasks)).toBeLessThan(750);
+    expect(finalPerf.maxEventLoopDelayMs).toBeLessThan(2_000);
+    expect(selectionP95Ms).toBeLessThan(500);
+  } finally {
+    await postAction(page.request, baseURL, "delete-design", {
+      id: designId,
+    }).catch(() => {});
+  }
+});
diff --git a/templates/design/e2e/layers-reparent.spec.ts b/templates/design/e2e/layers-reparent.spec.ts
index 62d41514f1..2789d355ff 100644
--- a/templates/design/e2e/layers-reparent.spec.ts
+++ b/templates/design/e2e/layers-reparent.spec.ts
@@ -41,6 +41,32 @@ test.describe.serial("layers menu structure operations", () => {
       "aria-selected",
       "true",
     );
+
+    // Cmd/Ctrl toggles membership back off without disturbing the other row.
+    await additiveSelectLayerRow(page, "Beta Button");
+    await expect.poll(() => selectedRowCount(page)).toBe(1);
+    await expect(layerRow(page, "Alpha Button")).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    await expect(layerRow(page, "Beta Button")).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+
+    // Shift selects the visible range from the plain-click anchor. The
+    // mirrored iframe selection echo must not collapse the range to Beta.
+    await clickLayerRow(page, "Alpha Button");
+    await rangeSelectLayerRow(page, "Beta Button");
+    await expect.poll(() => selectedRowCount(page)).toBe(2);
+    await expect(layerRow(page, "Alpha Button")).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    await expect(layerRow(page, "Beta Button")).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
   });
 
   test("dragging a sibling row reorders it before its peer", async ({
@@ -337,6 +363,12 @@ async function additiveSelectLayerRow(page: Page, name: string): Promise<void> {
   await expect(button).toBeFocused();
 }
 
+async function rangeSelectLayerRow(page: Page, name: string): Promise<void> {
+  const button = layerRowButton(page, name);
+  await button.click({ modifiers: ["Shift"] });
+  await expect(button).toBeFocused();
+}
+
 async function clickLayerAction(page: Page, name: string, label: string) {
   const row = layerRow(page, name);
   await row.hover();
diff --git a/templates/design/e2e/public-visual-edit.spec.ts b/templates/design/e2e/public-visual-edit.spec.ts
index 21a1927f0a..0e134ab969 100644
--- a/templates/design/e2e/public-visual-edit.spec.ts
+++ b/templates/design/e2e/public-visual-edit.spec.ts
@@ -16,7 +16,9 @@ import {
   readSeedDesignId,
 } from "./helpers";
 
-const AUTH_STATE_PATH = path.join(import.meta.dirname, ".auth", "state.json");
+const AUTH_STATE_PATH = process.env.E2E_AUTH_DIR
+  ? path.join(path.resolve(process.env.E2E_AUTH_DIR), "state.json")
+  : path.join(import.meta.dirname, ".auth", "state.json");
 const BASE_URL =
   process.env.E2E_BASE_URL ??
   `http://127.0.0.1:${Number(process.env.E2E_PORT ?? 9333)}`;
@@ -68,7 +70,7 @@ test.describe.serial("public visual edit", () => {
 
       await signedOut.page.keyboard.press(SHORTCUT);
       await expect(
-        signedOut.page.locator('[role="dialog"]:visible'),
+        signedOut.page.getByRole("dialog").filter({ visible: true }),
       ).toHaveCount(0);
       await assertNoRuntimeErrors(signedOut);
     } finally {
@@ -96,6 +98,63 @@ test.describe.serial("public visual edit", () => {
       await expect(
         designFrame(signedOut.page).getByText("E2E Hero Heading"),
       ).toBeVisible();
+      const publicIframe = signedOut.page
+        .locator("iframe[data-design-preview-iframe]")
+        .last();
+      await expect(publicIframe).toBeVisible();
+      await publicIframe.evaluate((element) => {
+        const frame = element as HTMLIFrameElement & {
+          __publicReadOnlyLoadCount?: number;
+        };
+        frame.dataset.publicReadOnlyIdentity = "stable-public-preview";
+        frame.__publicReadOnlyLoadCount = 0;
+        frame.addEventListener("load", () => {
+          frame.__publicReadOnlyLoadCount =
+            (frame.__publicReadOnlyLoadCount ?? 0) + 1;
+        });
+      });
+      await designFrame(signedOut.page)
+        .locator("body")
+        .evaluate(() => {
+          (window as any).__publicReadOnlyDocumentMarker =
+            "stable-public-document";
+        });
+      const expectStablePublicPreview = async () => {
+        await expect
+          .poll(async () => {
+            const iframeState = await publicIframe.evaluate((element) => {
+              const frame = element as HTMLIFrameElement & {
+                __publicReadOnlyLoadCount?: number;
+              };
+              const style = getComputedStyle(frame);
+              const rect = frame.getBoundingClientRect();
+              return {
+                identity: frame.dataset.publicReadOnlyIdentity ?? null,
+                loads: frame.__publicReadOnlyLoadCount ?? -1,
+                visible:
+                  frame.isConnected &&
+                  style.display !== "none" &&
+                  style.visibility !== "hidden" &&
+                  Number(style.opacity) !== 0 &&
+                  rect.width > 0 &&
+                  rect.height > 0,
+              };
+            });
+            const documentMarker = await designFrame(signedOut.page)
+              .locator("body")
+              .evaluate(
+                () => (window as any).__publicReadOnlyDocumentMarker ?? null,
+              )
+              .catch(() => null);
+            return { ...iframeState, documentMarker };
+          })
+          .toEqual({
+            identity: "stable-public-preview",
+            documentMarker: "stable-public-document",
+            loads: 0,
+            visible: true,
+          });
+      };
       await expect(
         signedOut.page
           .getByRole("button")
@@ -136,11 +195,13 @@ test.describe.serial("public visual edit", () => {
       await expect(
         designFrame(signedOut.page).getByText("E2E Hero Heading"),
       ).toBeVisible();
+      await expectStablePublicPreview();
 
       await signedOut.page.keyboard.press(SHORTCUT);
       await expect(
-        signedOut.page.locator('[role="dialog"]:visible'),
+        signedOut.page.getByRole("dialog").filter({ visible: true }),
       ).toHaveCount(0);
+      await expectStablePublicPreview();
       await assertNoRuntimeErrors(signedOut);
     } finally {
       await signedOut.close();
@@ -187,7 +248,11 @@ async function setDesignVisibility(
         },
       },
     );
-    expect(response.ok()).toBeTruthy();
+    if (!response.ok()) {
+      throw new Error(
+        `set-resource-visibility(${visibility}) failed: ${response.status()} ${await response.text()}`,
+      );
+    }
     const body = (await response.json()) as {
       visibility?: string;
       ok?: boolean;
diff --git a/templates/design/e2e/select-layer-context-menu.spec.ts b/templates/design/e2e/select-layer-context-menu.spec.ts
new file mode 100644
index 0000000000..13a82ff633
--- /dev/null
+++ b/templates/design/e2e/select-layer-context-menu.spec.ts
@@ -0,0 +1,270 @@
+import {
+  expect,
+  test,
+  type APIRequestContext,
+  type FrameLocator,
+  type Page,
+} from "@playwright/test";
+
+import {
+  designFrame,
+  enterDirectMode,
+  gotoEditor,
+  installBridge,
+  waitForBridge,
+} from "./helpers";
+
+const STACK_HTML = `<!doctype html>
+<html>
+  <head><meta charset="utf-8"><title>Select layer fixture</title></head>
+  <body style="margin:0;min-height:100vh;padding:20px">
+    <div data-agent-native-node-id="stage" data-agent-native-layer-name="Stage frame" style="position:relative;width:440px;height:360px;background:#eee">
+      <div data-agent-native-node-id="back" data-agent-native-layer-name="Back sibling" style="position:absolute;left:40px;top:40px;width:280px;height:260px;background:#bfdbfe">Back sibling</div>
+      <div data-agent-native-node-id="nested-parent" data-agent-native-layer-name="Nested parent" style="position:absolute;z-index:1;left:80px;top:80px;width:220px;height:210px;background:#bbf7d0">
+        <div data-agent-native-node-id="nested-child" data-agent-native-layer-name="Nested child" style="position:absolute;left:20px;top:20px;width:150px;height:150px;background:#fef08a">Nested child</div>
+      </div>
+      <div data-agent-native-node-id="front" data-agent-native-layer-name="Front sibling" style="position:absolute;z-index:2;left:120px;top:120px;width:120px;height:120px;background:#fecaca">Front sibling</div>
+      <div data-agent-native-node-id="hidden-cover" data-agent-native-layer-name="Hidden cover" data-agent-native-hidden="true" style="position:absolute;z-index:3;left:130px;top:130px;width:90px;height:90px;background:#000">Hidden cover</div>
+      <div data-agent-native-node-id="locked-cover" data-agent-native-layer-name="Locked cover" data-agent-native-locked="true" style="position:absolute;z-index:4;left:140px;top:140px;width:70px;height:70px;background:#fff">Locked cover</div>
+    </div>
+  </body>
+</html>`;
+
+async function postAction(
+  request: APIRequestContext,
+  name: string,
+  input: Record<string, unknown>,
+) {
+  const baseUrl = process.env.E2E_BASE_URL ?? "http://127.0.0.1:9333";
+  const response = await request.post(
+    `${baseUrl.replace(/\/$/, "")}/_agent-native/actions/${name}`,
+    { data: input },
+  );
+  if (!response.ok()) {
+    throw new Error(
+      `${name} failed: ${response.status()} ${await response.text()}`,
+    );
+  }
+  return response.json();
+}
+
+async function getAction(
+  request: APIRequestContext,
+  name: string,
+  input: Record<string, unknown>,
+) {
+  const baseUrl = process.env.E2E_BASE_URL ?? "http://127.0.0.1:9333";
+  const params = new URLSearchParams(
+    Object.entries(input).map(([key, value]) => [key, String(value)]),
+  );
+  const response = await request.get(
+    `${baseUrl.replace(/\/$/, "")}/_agent-native/actions/${name}?${params}`,
+  );
+  if (!response.ok()) {
+    throw new Error(
+      `${name} failed: ${response.status()} ${await response.text()}`,
+    );
+  }
+  return response.json();
+}
+
+async function openLayerStack(
+  page: Page,
+  frame: FrameLocator = designFrame(page),
+) {
+  await installBridge(page);
+  await page.evaluate(() => ((window as any).__bridge = []));
+  const stage = frame.locator('[data-agent-native-node-id="stage"]');
+  const box = await stage.boundingBox();
+  if (!box) throw new Error("stage has no browser geometry");
+  const frameOffset = await stage.evaluate((element) => {
+    const rect = element.getBoundingClientRect();
+    return { x: rect.left + 165, y: rect.top + 165 };
+  });
+  // Dispatch on the real bridge shield inside Chromium. A top-level
+  // page.mouse right-click is consumed by Chromium's iframe context-menu
+  // boundary in headless mode before the srcdoc listener sees it; this still
+  // exercises the actual contextmenu event, elementsFromPoint stack, iframe
+  // postMessage bridge, host menu, and selection path end-to-end.
+  await stage.evaluate((_element, point) => {
+    document.dispatchEvent(
+      new MouseEvent("contextmenu", {
+        bubbles: true,
+        cancelable: true,
+        button: 2,
+        buttons: 2,
+        clientX: point.x,
+        clientY: point.y,
+      }),
+    );
+  }, frameOffset);
+  await waitForBridge(page, "element-contextmenu");
+  const trigger = page.getByText("Select layer", { exact: true });
+  await expect(trigger).toBeVisible();
+  await trigger.hover();
+  const submenu = page.getByRole("menu").last();
+  await expect(
+    submenu.getByText("Front sibling", { exact: true }),
+  ).toBeVisible();
+  return submenu;
+}
+
+async function selectedTreeLabel(page: Page) {
+  return (
+    (await page
+      .getByRole("treeitem", { selected: true })
+      .first()
+      .textContent()) ?? ""
+  );
+}
+
+test("Select layer lists the exact visible unlocked hit stack and dismisses without mutation", async ({
+  page,
+  request,
+}) => {
+  const created = await postAction(request, "create-design", {
+    title: `Select layer ${Date.now()}`,
+    projectType: "prototype",
+  });
+  const designId = created.id ?? created.data?.id ?? created.design?.id;
+  if (!designId) throw new Error("create-design returned no id");
+
+  try {
+    await postAction(request, "create-file", {
+      designId,
+      filename: "index.html",
+      content: STACK_HTML,
+      fileType: "html",
+    });
+    await gotoEditor(page, designId);
+    await enterDirectMode(page);
+    const baselineDesign = await getAction(request, "get-design", {
+      id: designId,
+    });
+    const baselineContent = baselineDesign.files?.find(
+      (file: { filename?: string }) => file.filename === "index.html",
+    )?.content;
+
+    const submenu = await openLayerStack(page);
+    const visibleLabels = [
+      "Front sibling",
+      "Nested child",
+      "Nested parent",
+      "Back sibling",
+      "Stage frame",
+    ];
+    for (const label of visibleLabels) {
+      await expect(submenu.getByText(label, { exact: true })).toBeVisible();
+    }
+    await expect(
+      submenu.getByText("Locked cover", { exact: true }),
+    ).toHaveCount(0);
+    await expect(
+      submenu.getByText("Hidden cover", { exact: true }),
+    ).toHaveCount(0);
+
+    const submenuItems = submenu
+      .getByRole("menuitem")
+      .filter({ has: page.locator("svg") });
+    const labelsInOrder = await submenuItems.allTextContents();
+    const orderedHits = labelsInOrder.filter((label) =>
+      visibleLabels.includes(label.trim()),
+    );
+    expect(orderedHits).toEqual(visibleLabels);
+
+    // Escape dismisses the submenu/menu and leaves the right-click top hit
+    // selected; it must not accidentally pick a different candidate.
+    await page.keyboard.press("Escape");
+    await expect(page.getByText("Select layer", { exact: true })).toBeHidden();
+    await expect.poll(() => selectedTreeLabel(page)).toContain("Front sibling");
+
+    const childMenu = await openLayerStack(page);
+    await childMenu.getByText("Nested child", { exact: true }).click();
+    await expect.poll(() => selectedTreeLabel(page)).toContain("Nested child");
+
+    const parentMenu = await openLayerStack(page);
+    await parentMenu.getByText("Nested parent", { exact: true }).click();
+    await expect.poll(() => selectedTreeLabel(page)).toContain("Nested parent");
+
+    const backMenu = await openLayerStack(page);
+    await backMenu.getByText("Back sibling", { exact: true }).click();
+    await expect.poll(() => selectedTreeLabel(page)).toContain("Back sibling");
+
+    const design = await getAction(request, "get-design", { id: designId });
+    const content = design.files?.find(
+      (file: { filename?: string }) => file.filename === "index.html",
+    )?.content;
+    expect(content).toBe(baselineContent);
+  } finally {
+    await postAction(request, "delete-design", { id: designId }).catch(
+      () => {},
+    );
+  }
+});
+
+test("Select layer on a non-active overview screen routes selection to that exact screen", async ({
+  page,
+  request,
+}) => {
+  const created = await postAction(request, "create-design", {
+    title: `Overview select layer ${Date.now()}`,
+    projectType: "prototype",
+  });
+  const designId = created.id ?? created.data?.id ?? created.design?.id;
+  if (!designId) throw new Error("create-design returned no id");
+
+  try {
+    const home = await postAction(request, "create-file", {
+      designId,
+      filename: "index.html",
+      content: STACK_HTML,
+      fileType: "html",
+    });
+    const about = await postAction(request, "create-file", {
+      designId,
+      filename: "about.html",
+      content: STACK_HTML,
+      fileType: "html",
+    });
+    const homeId = home.id ?? home.data?.id ?? home.file?.id;
+    const aboutId = about.id ?? about.data?.id ?? about.file?.id;
+    if (!homeId || !aboutId) throw new Error("create-file returned no id");
+
+    await gotoEditor(page, designId);
+    await expect(
+      page.getByRole("button", { name: "Full view" }).first(),
+    ).toBeVisible();
+    await expect
+      .poll(() => new URL(page.url()).searchParams.get("screen"))
+      .toBe(homeId);
+
+    const baseline = await getAction(request, "get-design", { id: designId });
+    const aboutBaseline = baseline.files?.find(
+      (file: { id?: string }) => file.id === aboutId,
+    )?.content;
+    const aboutShell = page
+      .locator("[data-screen-shell]")
+      .filter({ hasText: "About" });
+    await expect(aboutShell).toBeVisible();
+    const aboutFrame = aboutShell
+      .locator("iframe[data-design-preview-iframe]")
+      .contentFrame();
+
+    const menu = await openLayerStack(page, aboutFrame);
+    await menu.getByText("Nested child", { exact: true }).click();
+
+    await expect
+      .poll(() => new URL(page.url()).searchParams.get("screen"))
+      .toBe(aboutId);
+    await expect.poll(() => selectedTreeLabel(page)).toContain("Nested child");
+    const after = await getAction(request, "get-design", { id: designId });
+    expect(
+      after.files?.find((file: { id?: string }) => file.id === aboutId)
+        ?.content,
+    ).toBe(aboutBaseline);
+  } finally {
+    await postAction(request, "delete-design", { id: designId }).catch(
+      () => {},
+    );
+  }
+});
diff --git a/templates/design/server/lib/design-to-figma-svg.spec.ts b/templates/design/server/lib/design-to-figma-svg.spec.ts
new file mode 100644
index 0000000000..353e234ab8
--- /dev/null
+++ b/templates/design/server/lib/design-to-figma-svg.spec.ts
@@ -0,0 +1,821 @@
+/**
+ * design-to-figma-svg.spec.ts
+ *
+ * Covers the pure, browser-free scene -> SVG serializer with hand-built
+ * `FigmaSvgNode` fixtures, plus the raw-scene hydration layer
+ * (`buildFillLayersFromComputedStyle` / `hydrateRawFigmaSvgNode`), which is
+ * also pure — it only consumes plain computed-style strings, no DOM. The
+ * Playwright-based DOM WALK (`collectRawFigmaSvgScene`, wired into
+ * `renderDesignToFigmaSvg` and the `export-design-as-figma-svg` action) needs
+ * a real headless Chromium and is exercised in practice, not here — same
+ * split as `take-design-screenshot.spec.ts`'s `collectPageDiagnostics` (see
+ * that file's docblock).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  buildFigmaSvgDocument,
+  buildFillLayersFromComputedStyle,
+  buildLinearGradientDef,
+  buildRadialGradientDef,
+  buildShadowFilterDef,
+  escapeXmlAttr,
+  escapeXmlText,
+  type FigmaSvgNode,
+  gradientAngleToRotation,
+  hydrateRawFigmaSvgNode,
+  insetRadiiForStroke,
+  insetRectForStroke,
+  isUniformRadius,
+  isZeroRadii,
+  objectFitToPreserveAspectRatio,
+  parseComputedBoxShadow,
+  parseComputedLinearGradient,
+  parseComputedRadialGradient,
+  type RawFigmaSvgNode,
+  roundedRectPath,
+  safeFigmaSvgFilename,
+  splitTopLevelCommas,
+} from "./design-to-figma-svg.js";
+
+// ---------------------------------------------------------------------------
+// Formatting / escaping
+// ---------------------------------------------------------------------------
+
+describe("escapeXmlAttr / escapeXmlText", () => {
+  it("escapes attribute-unsafe characters", () => {
+    expect(escapeXmlAttr('a "quoted" <tag>&')).toBe(
+      "a &quot;quoted&quot; &lt;tag&gt;&amp;",
+    );
+  });
+
+  it("escapes text-unsafe characters but leaves quotes alone", () => {
+    expect(escapeXmlText('5 < 10 & "ok"')).toBe('5 &lt; 10 &amp; "ok"');
+  });
+});
+
+describe("isUniformRadius / isZeroRadii", () => {
+  it("detects uniform radii", () => {
+    expect(isUniformRadius({ tl: 8, tr: 8, br: 8, bl: 8 })).toBe(true);
+    expect(isUniformRadius({ tl: 8, tr: 4, br: 8, bl: 8 })).toBe(false);
+  });
+
+  it("detects all-zero radii", () => {
+    expect(isZeroRadii({ tl: 0, tr: 0, br: 0, bl: 0 })).toBe(true);
+    expect(isZeroRadii({ tl: 0, tr: 1, br: 0, bl: 0 })).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rounded-rect path (per-corner radii)
+// ---------------------------------------------------------------------------
+
+describe("roundedRectPath", () => {
+  it("emits line + arc segments for differing per-corner radii", () => {
+    const path = roundedRectPath(
+      { x: 0, y: 0, width: 100, height: 50 },
+      { tl: 10, tr: 0, br: 20, bl: 5 },
+    );
+    // tl=10 arc, tr=0 (no arc, sharp corner), br=20 arc, bl=5 arc.
+    expect(path).toBe(
+      "M 10 0 L 100 0 L 100 30 A 20 20 0 0 1 80 50 L 5 50 A 5 5 0 0 1 0 45 L 0 10 A 10 10 0 0 1 10 0 Z",
+    );
+  });
+
+  it("clamps radii that exceed half the smaller dimension", () => {
+    const path = roundedRectPath(
+      { x: 0, y: 0, width: 20, height: 10 },
+      { tl: 100, tr: 100, br: 100, bl: 100 },
+    );
+    // maxR = min(20,10)/2 = 5, so every corner clamps to 5.
+    expect(path).toContain("A 5 5 0 0 1");
+    expect(path).not.toContain("A 100 100");
+  });
+
+  it("omits the arc command entirely for a zero-radius corner", () => {
+    const path = roundedRectPath(
+      { x: 0, y: 0, width: 40, height: 40 },
+      { tl: 0, tr: 0, br: 0, bl: 0 },
+    );
+    expect(path).toBe("M 0 0 L 40 0 L 40 40 L 0 40 L 0 0 Z");
+    expect(path).not.toContain("A ");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Border stroke inset geometry
+// ---------------------------------------------------------------------------
+
+describe("insetRectForStroke / insetRadiiForStroke", () => {
+  it("insets the rect by half the stroke width on every side", () => {
+    const rect = insetRectForStroke(
+      { x: 10, y: 10, width: 100, height: 60 },
+      4,
+    );
+    expect(rect).toEqual({ x: 12, y: 12, width: 96, height: 56 });
+  });
+
+  it("clamps width/height at zero for a stroke wider than the box", () => {
+    const rect = insetRectForStroke({ x: 0, y: 0, width: 4, height: 4 }, 10);
+    expect(rect.width).toBe(0);
+    expect(rect.height).toBe(0);
+  });
+
+  it("shrinks each corner radius by half the stroke width, clamped at zero", () => {
+    const radii = insetRadiiForStroke({ tl: 10, tr: 2, br: 0, bl: 20 }, 4);
+    expect(radii).toEqual({ tl: 8, tr: 0, br: 0, bl: 18 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Gradient angle mapping
+// ---------------------------------------------------------------------------
+
+describe("gradientAngleToRotation", () => {
+  it("maps CSS 90deg (to right) to SVG's unrotated default vector", () => {
+    expect(gradientAngleToRotation(90)).toBe(0);
+  });
+
+  it("maps CSS 0deg (to top) to -90deg normalized to 270", () => {
+    expect(gradientAngleToRotation(0)).toBe(270);
+  });
+
+  it("maps CSS 180deg (to bottom) to 90", () => {
+    expect(gradientAngleToRotation(180)).toBe(90);
+  });
+
+  it("maps CSS 270deg (to left) to 180", () => {
+    expect(gradientAngleToRotation(270)).toBe(180);
+  });
+});
+
+describe("buildLinearGradientDef", () => {
+  it("emits exact stop offsets/colors and a rotation-based gradientTransform", () => {
+    const def = buildLinearGradientDef("lg-1", 45, [
+      { offset: 0, color: "rgb(255, 0, 0)" },
+      { offset: 0.5, color: "rgb(0, 255, 0)" },
+      { offset: 1, color: "rgb(0, 0, 255)" },
+    ]);
+    expect(def).toBe(
+      '<linearGradient id="lg-1" x1="0" y1="0" x2="1" y2="0" gradientTransform="rotate(315 0.5 0.5)">' +
+        '<stop offset="0%" stop-color="rgb(255, 0, 0)"/>' +
+        '<stop offset="50%" stop-color="rgb(0, 255, 0)"/>' +
+        '<stop offset="100%" stop-color="rgb(0, 0, 255)"/>' +
+        "</linearGradient>",
+    );
+  });
+});
+
+describe("buildRadialGradientDef", () => {
+  it("defaults to a centered circle spanning the bounding box", () => {
+    const def = buildRadialGradientDef("rg-1", [
+      { offset: 0, color: "#fff" },
+      { offset: 1, color: "#000" },
+    ]);
+    expect(def).toBe(
+      '<radialGradient id="rg-1" cx="0.5" cy="0.5" r="0.5">' +
+        '<stop offset="0%" stop-color="#fff"/>' +
+        '<stop offset="100%" stop-color="#000"/>' +
+        "</radialGradient>",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Computed-style parsers
+// ---------------------------------------------------------------------------
+
+describe("splitTopLevelCommas", () => {
+  it("does not split commas nested inside rgba()/rgb()", () => {
+    expect(
+      splitTopLevelCommas(
+        "rgba(0, 0, 0, 0.5) 0px 4px 8px 0px, rgb(255, 0, 0) 2px 2px 0px 0px",
+      ),
+    ).toEqual([
+      "rgba(0, 0, 0, 0.5) 0px 4px 8px 0px",
+      "rgb(255, 0, 0) 2px 2px 0px 0px",
+    ]);
+  });
+});
+
+describe("parseComputedBoxShadow", () => {
+  it("returns [] for none/empty", () => {
+    expect(parseComputedBoxShadow("none")).toEqual([]);
+    expect(parseComputedBoxShadow(null)).toEqual([]);
+    expect(parseComputedBoxShadow(undefined)).toEqual([]);
+  });
+
+  it("parses a single Chromium-normalized shadow", () => {
+    expect(
+      parseComputedBoxShadow("rgba(0, 0, 0, 0.25) 0px 4px 12px 0px"),
+    ).toEqual([
+      {
+        offsetX: 0,
+        offsetY: 4,
+        blur: 12,
+        spread: 0,
+        color: "rgba(0, 0, 0, 0.25)",
+        inset: false,
+      },
+    ]);
+  });
+
+  it("parses an inset shadow and flags it", () => {
+    const [shadow] = parseComputedBoxShadow(
+      "rgb(0, 0, 0) 2px 2px 0px 0px inset",
+    );
+    expect(shadow.inset).toBe(true);
+    expect(shadow.offsetX).toBe(2);
+    expect(shadow.spread).toBe(0);
+  });
+
+  it("parses multiple comma-separated shadows", () => {
+    const shadows = parseComputedBoxShadow(
+      "rgba(0, 0, 0, 0.25) 0px 4px 12px 0px, rgba(0, 0, 0, 0.1) 0px 1px 2px 1px",
+    );
+    expect(shadows).toHaveLength(2);
+    expect(shadows[1]).toEqual({
+      offsetX: 0,
+      offsetY: 1,
+      blur: 2,
+      spread: 1,
+      color: "rgba(0, 0, 0, 0.1)",
+      inset: false,
+    });
+  });
+});
+
+describe("parseComputedLinearGradient", () => {
+  it("parses an explicit angle and percentage stops", () => {
+    expect(
+      parseComputedLinearGradient(
+        "linear-gradient(45deg, rgb(255, 0, 0) 0%, rgb(0, 0, 255) 100%)",
+      ),
+    ).toEqual({
+      angleDeg: 45,
+      stops: [
+        { offset: 0, color: "rgb(255, 0, 0)" },
+        { offset: 1, color: "rgb(0, 0, 255)" },
+      ],
+    });
+  });
+
+  it("resolves a `to right` keyword direction to 90deg", () => {
+    const parsed = parseComputedLinearGradient(
+      "linear-gradient(to right, rgb(255, 0, 0) 0%, rgb(0, 0, 255) 100%)",
+    );
+    expect(parsed?.angleDeg).toBe(90);
+  });
+
+  it("defaults to 180deg (to bottom) when no direction is given", () => {
+    const parsed = parseComputedLinearGradient(
+      "linear-gradient(rgb(255, 0, 0) 0%, rgb(0, 0, 255) 100%)",
+    );
+    expect(parsed?.angleDeg).toBe(180);
+  });
+
+  it("returns null for a non-gradient string", () => {
+    expect(parseComputedLinearGradient("none")).toBeNull();
+  });
+});
+
+describe("parseComputedRadialGradient", () => {
+  it("extracts stops, ignoring shape/position", () => {
+    const parsed = parseComputedRadialGradient(
+      "radial-gradient(circle at center, rgb(255, 255, 255) 0%, rgb(0, 0, 0) 100%)",
+    );
+    expect(parsed?.stops).toEqual([
+      { offset: 0, color: "rgb(255, 255, 255)" },
+      { offset: 1, color: "rgb(0, 0, 0)" },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// object-fit
+// ---------------------------------------------------------------------------
+
+describe("objectFitToPreserveAspectRatio", () => {
+  it("maps cover to xMidYMid slice", () => {
+    expect(objectFitToPreserveAspectRatio("cover")).toBe("xMidYMid slice");
+  });
+  it("maps contain to xMidYMid meet", () => {
+    expect(objectFitToPreserveAspectRatio("contain")).toBe("xMidYMid meet");
+  });
+  it("maps stretch/none to none", () => {
+    expect(objectFitToPreserveAspectRatio("stretch")).toBe("none");
+    expect(objectFitToPreserveAspectRatio("none")).toBe("none");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Shadow filters
+// ---------------------------------------------------------------------------
+
+describe("buildShadowFilterDef", () => {
+  it("emits a feDropShadow chain when every shadow has zero spread", () => {
+    const def = buildShadowFilterDef("shadow-1", [
+      {
+        offsetX: 0,
+        offsetY: 4,
+        blur: 12,
+        spread: 0,
+        color: "rgba(0, 0, 0, 0.25)",
+      },
+    ]);
+    expect(def).toContain("<feDropShadow");
+    expect(def).toContain('dx="0" dy="4" stdDeviation="6"');
+    expect(def).toContain('flood-color="rgb(0, 0, 0)"');
+    expect(def).toContain('flood-opacity="0.25"');
+    expect(def).not.toContain("feMorphology");
+  });
+
+  it("emits a decomposed feMorphology chain when spread is non-zero", () => {
+    const def = buildShadowFilterDef("shadow-2", [
+      { offsetX: 2, offsetY: 2, blur: 4, spread: 3, color: "rgb(0, 0, 0)" },
+    ]);
+    expect(def).toContain(
+      '<feMorphology in="SourceAlpha" operator="dilate" radius="3"',
+    );
+    expect(def).toContain("<feGaussianBlur");
+    expect(def).toContain("<feMerge>");
+  });
+
+  it("returns an empty string when every shadow is inset (caller's responsibility to report)", () => {
+    const def = buildShadowFilterDef("shadow-3", [
+      {
+        offsetX: 0,
+        offsetY: 2,
+        blur: 2,
+        spread: 0,
+        color: "#000",
+        inset: true,
+      },
+    ]);
+    expect(def).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Full node -> SVG document rendering
+// ---------------------------------------------------------------------------
+
+describe("buildFigmaSvgDocument", () => {
+  it("renders a box with a solid fill and a uniform border as a plain <rect> pair with inset stroke geometry", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      name: "Card",
+      kind: "box",
+      rect: { x: 0, y: 0, width: 200, height: 100 },
+      fills: [{ kind: "solid", color: "#ffffff" }],
+      border: { widthPx: 4, color: "#111111" },
+    };
+    const { svg, report } = buildFigmaSvgDocument({
+      width: 200,
+      height: 100,
+      root,
+    });
+
+    expect(svg).toContain(
+      '<rect x="0" y="0" width="200" height="100" fill="#ffffff"/>',
+    );
+    expect(svg).toContain(
+      '<rect x="2" y="2" width="196" height="96" fill="none" stroke="#111111" stroke-width="4"/>',
+    );
+    expect(report.vectorized).toContain("Card");
+    expect(report.rasterized).toHaveLength(0);
+  });
+
+  it("renders per-corner radii as a <path> for both the fill and the inset stroke", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      kind: "box",
+      rect: { x: 0, y: 0, width: 100, height: 100 },
+      cornerRadii: { tl: 20, tr: 0, br: 20, bl: 0 },
+      fills: [{ kind: "solid", color: "red" }],
+      border: { widthPx: 2, color: "black" },
+    };
+    const { svg } = buildFigmaSvgDocument({ width: 100, height: 100, root });
+    // Two paths: one for the full-rect fill, one for the inset stroke.
+    const pathCount = (svg.match(/<path /g) || []).length;
+    expect(pathCount).toBe(2);
+    // tl/br are rounded (arcs), tr/bl are sharp (0 radius, straight lines).
+    expect(svg).toContain(
+      'd="M 20 0 L 100 0 L 100 80 A 20 20 0 0 1 80 100 L 0 100 L 0 20 A 20 20 0 0 1 20 0 Z"',
+    );
+  });
+
+  it("emits gradient defs with exact stop offsets for a linear-gradient fill", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      name: "Hero",
+      kind: "box",
+      rect: { x: 0, y: 0, width: 300, height: 300 }, // square: exact, not approximated
+      fills: [
+        {
+          kind: "linear-gradient",
+          angleDeg: 135,
+          stops: [
+            { offset: 0, color: "rgb(255, 0, 0)" },
+            { offset: 1, color: "rgb(0, 0, 255)" },
+          ],
+        },
+      ],
+    };
+    const { svg, report } = buildFigmaSvgDocument({
+      width: 300,
+      height: 300,
+      root,
+    });
+    expect(svg).toContain("<linearGradient");
+    expect(svg).toContain('<stop offset="0%" stop-color="rgb(255, 0, 0)"/>');
+    expect(svg).toContain('<stop offset="100%" stop-color="rgb(0, 0, 255)"/>');
+    expect(svg).toContain('gradientTransform="rotate(45 0.5 0.5)"');
+    // Square box: no aspect-ratio approximation note for this fill.
+    expect(report.approximated).toHaveLength(0);
+  });
+
+  it("flags a non-square element's gradient angle as approximated", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      name: "Banner",
+      kind: "box",
+      rect: { x: 0, y: 0, width: 400, height: 100 },
+      fills: [
+        {
+          kind: "linear-gradient",
+          angleDeg: 90,
+          stops: [
+            { offset: 0, color: "#fff" },
+            { offset: 1, color: "#000" },
+          ],
+        },
+      ],
+    };
+    const { report } = buildFigmaSvgDocument({ width: 400, height: 100, root });
+    expect(report.approximated.some((a) => a.node === "Banner")).toBe(true);
+  });
+
+  it("stacks multiple background layers in reverse so the first CSS layer paints on top", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      kind: "box",
+      rect: { x: 0, y: 0, width: 100, height: 100 },
+      fills: [
+        { kind: "solid", color: "rgba(255,0,0,0.5)" }, // CSS layer 0 (topmost)
+        { kind: "solid", color: "blue" }, // CSS layer 1 (underneath)
+      ],
+    };
+    const { svg } = buildFigmaSvgDocument({ width: 100, height: 100, root });
+    const blueIndex = svg.indexOf('fill="blue"');
+    const redIndex = svg.indexOf('fill="rgba(255,0,0,0.5)"');
+    expect(blueIndex).toBeGreaterThan(-1);
+    expect(redIndex).toBeGreaterThan(blueIndex); // painted later == on top
+  });
+
+  it("renders multi-line text as tspans at the exact supplied x/y positions", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      name: "Headline",
+      kind: "text",
+      rect: { x: 10, y: 10, width: 200, height: 60 },
+      text: {
+        lines: [
+          { text: "Hello", x: 10, y: 24 },
+          { text: "World", x: 10, y: 48 },
+        ],
+        style: {
+          fontFamily: "Inter",
+          fontSizePx: 16,
+          fontWeight: 700,
+          color: "#111111",
+          textAlign: "left",
+        },
+      },
+    };
+    const { svg, report } = buildFigmaSvgDocument({
+      width: 220,
+      height: 80,
+      root,
+    });
+    expect(svg).toContain('<tspan x="10" y="24">Hello</tspan>');
+    expect(svg).toContain('<tspan x="10" y="48">World</tspan>');
+    expect(svg).toContain('font-family="Inter"');
+    expect(svg).toContain('font-weight="700"');
+    expect(svg).toContain('dominant-baseline="central"');
+    expect(report.vectorizedTextCaveat).toContain("outlined vector paths");
+  });
+
+  it("clips a cover-fit image to its rounded rect and reports it as vectorized geometry", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      name: "Avatar",
+      kind: "image",
+      rect: { x: 0, y: 0, width: 64, height: 64 },
+      cornerRadii: { tl: 32, tr: 32, br: 32, bl: 32 },
+      image: { href: "https://example.com/a.png", fit: "cover" },
+    };
+    const { svg, report } = buildFigmaSvgDocument({
+      width: 64,
+      height: 64,
+      root,
+    });
+    expect(svg).toContain("<clipPath");
+    expect(svg).toContain('preserveAspectRatio="xMidYMid slice"');
+    expect(svg).toContain('clip-path="url(#clip-1)"');
+    expect(report.vectorized).toContain("Avatar");
+  });
+
+  it("marks an unsupported node (video/canvas/iframe/backdrop-blur) as rasterized with a reason", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      name: "Live chart",
+      kind: "raster",
+      rect: { x: 0, y: 0, width: 300, height: 200 },
+      raster: {
+        href: "https://cdn.example.com/exports/live-chart.png",
+        reason: "canvas element — rasterized via screenshot",
+      },
+    };
+    const { svg, report } = buildFigmaSvgDocument({
+      width: 300,
+      height: 200,
+      root,
+    });
+    expect(svg).toContain("<image");
+    expect(report.rasterized).toEqual([
+      {
+        node: "Live chart",
+        reason: "canvas element — rasterized via screenshot",
+      },
+    ]);
+  });
+
+  it("wraps rotated/opacity-adjusted nodes in a <g transform/opacity>", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      kind: "box",
+      rect: { x: 10, y: 10, width: 40, height: 20 },
+      rotationDeg: 15,
+      opacity: 0.5,
+      fills: [{ kind: "solid", color: "green" }],
+    };
+    const { svg } = buildFigmaSvgDocument({ width: 60, height: 40, root });
+    expect(svg).toContain('transform="rotate(15 30 20)"');
+    expect(svg).toContain('opacity="0.5"');
+  });
+
+  it("recurses into children under a parent group", () => {
+    const root: FigmaSvgNode = {
+      id: "root",
+      kind: "box",
+      rect: { x: 0, y: 0, width: 100, height: 100 },
+      fills: [{ kind: "solid", color: "white" }],
+      children: [
+        {
+          id: "child-1",
+          name: "Label",
+          kind: "text",
+          rect: { x: 10, y: 10, width: 80, height: 20 },
+          text: {
+            lines: [{ text: "Child", x: 10, y: 20 }],
+            style: { fontFamily: "Inter", fontSizePx: 14, color: "#000" },
+          },
+        },
+      ],
+    };
+    const { svg, report } = buildFigmaSvgDocument({
+      width: 100,
+      height: 100,
+      root,
+    });
+    expect(svg).toContain(">Child<");
+    expect(report.vectorized).toEqual(
+      expect.arrayContaining(["root", "Label"]),
+    );
+  });
+
+  it("produces a complete, well-formed document for a simple two-element screen", () => {
+    const root: FigmaSvgNode = {
+      id: "screen",
+      name: "Screen",
+      kind: "box",
+      rect: { x: 0, y: 0, width: 320, height: 120 },
+      fills: [{ kind: "solid", color: "#0f172a" }],
+      children: [
+        {
+          id: "label",
+          name: "Title",
+          kind: "text",
+          rect: { x: 24, y: 40, width: 200, height: 24 },
+          text: {
+            lines: [{ text: "Ship it", x: 24, y: 52 }],
+            style: {
+              fontFamily: "Inter",
+              fontSizePx: 20,
+              fontWeight: 600,
+              color: "#f8fafc",
+              textAlign: "left",
+            },
+          },
+        },
+      ],
+    };
+    const { svg } = buildFigmaSvgDocument({
+      width: 320,
+      height: 120,
+      title: "Two Element Screen",
+      root,
+    });
+    expect(svg.startsWith('<?xml version="1.0" encoding="UTF-8"?>')).toBe(true);
+    expect(svg).toContain('<svg xmlns="http://www.w3.org/2000/svg"');
+    expect(svg).toContain("<title>Two Element Screen</title>");
+    expect(svg.trim().endsWith("</svg>")).toBe(true);
+  });
+});
+
+describe("safeFigmaSvgFilename", () => {
+  it("sanitizes the title and appends a .svg extension with a timestamp", () => {
+    const filename = safeFigmaSvgFilename("My Cool Design!!");
+    expect(filename).toMatch(/^My-Cool-Design-figma-\d+\.svg$/);
+  });
+
+  it("falls back to 'design' for an empty/undefined title", () => {
+    expect(safeFigmaSvgFilename(undefined)).toMatch(/^design-figma-\d+\.svg$/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Raw scene hydration (pure — takes computed-style strings, no DOM/browser)
+// ---------------------------------------------------------------------------
+
+describe("buildFillLayersFromComputedStyle", () => {
+  it("returns just the solid background-color when there is no background-image", () => {
+    expect(
+      buildFillLayersFromComputedStyle("rgb(255, 255, 255)", "none"),
+    ).toEqual([{ kind: "solid", color: "rgba(255, 255, 255, 1)" }]);
+  });
+
+  it("omits a fully transparent background-color", () => {
+    expect(
+      buildFillLayersFromComputedStyle("rgba(0, 0, 0, 0)", "none"),
+    ).toEqual([]);
+  });
+
+  it("puts the background-image gradient layer BEFORE the background-color (color is bottommost)", () => {
+    const layers = buildFillLayersFromComputedStyle(
+      "rgb(17, 24, 39)",
+      "linear-gradient(90deg, rgb(255, 0, 0) 0%, rgb(0, 0, 255) 100%)",
+    );
+    expect(layers).toEqual([
+      {
+        kind: "linear-gradient",
+        angleDeg: 90,
+        stops: [
+          { offset: 0, color: "rgb(255, 0, 0)" },
+          { offset: 1, color: "rgb(0, 0, 255)" },
+        ],
+      },
+      { kind: "solid", color: "rgba(17, 24, 39, 1)" },
+    ]);
+  });
+
+  it("parses a url() background-image as an image fill", () => {
+    const layers = buildFillLayersFromComputedStyle(
+      "rgba(0, 0, 0, 0)",
+      'url("https://example.com/bg.png")',
+    );
+    expect(layers).toEqual([
+      { kind: "image", href: "https://example.com/bg.png", fit: "cover" },
+    ]);
+  });
+});
+
+function rawBoxFixture(
+  overrides: Partial<RawFigmaSvgNode> = {},
+): RawFigmaSvgNode {
+  return {
+    id: "n1",
+    domTag: "DIV",
+    rect: { x: 0, y: 0, width: 100, height: 100 },
+    rotationDeg: 0,
+    opacity: 1,
+    cornerRadiiRaw: { tl: 0, tr: 0, br: 0, bl: 0 },
+    backgroundColor: "rgba(0, 0, 0, 0)",
+    backgroundImage: "none",
+    boxShadow: "none",
+    borderWidthPx: 0,
+    borderColor: "rgb(0, 0, 0)",
+    borderStyle: "none",
+    borderNonUniform: false,
+    backdropFilter: "none",
+    isLeafText: false,
+    children: [],
+    ...overrides,
+  };
+}
+
+describe("hydrateRawFigmaSvgNode", () => {
+  it("hydrates a plain box with solid fill and border", () => {
+    const node = hydrateRawFigmaSvgNode(
+      rawBoxFixture({
+        name: "Card",
+        backgroundColor: "rgb(255, 255, 255)",
+        borderWidthPx: 2,
+        borderColor: "rgb(0, 0, 0)",
+        borderStyle: "solid",
+      }),
+    );
+    expect(node.kind).toBe("box");
+    expect(node.fills).toEqual([
+      { kind: "solid", color: "rgba(255, 255, 255, 1)" },
+    ]);
+    expect(node.border).toEqual({
+      widthPx: 2,
+      color: "rgb(0, 0, 0)",
+      dashed: false,
+      nonUniform: undefined,
+    });
+  });
+
+  it("omits opacity/rotation/cornerRadii when at their neutral defaults", () => {
+    const node = hydrateRawFigmaSvgNode(rawBoxFixture());
+    expect(node.opacity).toBeUndefined();
+    expect(node.rotationDeg).toBeUndefined();
+    expect(node.cornerRadii).toBeUndefined();
+  });
+
+  it("flags a non-uniform border for the approximated-border report path", () => {
+    const node = hydrateRawFigmaSvgNode(
+      rawBoxFixture({
+        borderWidthPx: 2,
+        borderStyle: "solid",
+        borderNonUniform: true,
+      }),
+    );
+    expect(node.border?.nonUniform).toBe(true);
+  });
+
+  it("hydrates a rasterized node (video/canvas/iframe/backdrop-blur) regardless of other fields", () => {
+    const node = hydrateRawFigmaSvgNode(
+      rawBoxFixture({
+        rasterReason:
+          "backdrop-filter cannot be expressed in SVG — rasterized this element's region via screenshot.",
+        rasterHref: "data:image/png;base64,AAA",
+      }),
+    );
+    expect(node.kind).toBe("raster");
+    expect(node.raster).toEqual({
+      href: "data:image/png;base64,AAA",
+      reason:
+        "backdrop-filter cannot be expressed in SVG — rasterized this element's region via screenshot.",
+    });
+  });
+
+  it("hydrates a leaf text node from textLines/textStyle", () => {
+    const node = hydrateRawFigmaSvgNode(
+      rawBoxFixture({
+        isLeafText: true,
+        textLines: [{ text: "Hello", x: 10, y: 20 }],
+        textStyle: {
+          fontFamily: "Inter",
+          fontSizePx: 16,
+          fontWeight: 700,
+          italic: false,
+          letterSpacingPx: 0,
+          color: "rgb(0, 0, 0)",
+          textAlign: "center",
+        },
+      }),
+    );
+    expect(node.kind).toBe("text");
+    expect(node.text?.lines).toEqual([{ text: "Hello", x: 10, y: 20 }]);
+    expect(node.text?.style.textAlign).toBe("center");
+  });
+
+  it("hydrates an IMG node with a normalized object-fit", () => {
+    const node = hydrateRawFigmaSvgNode(
+      rawBoxFixture({
+        domTag: "IMG",
+        imgSrc: "https://example.com/a.png",
+        imgObjectFit: "scale-down",
+      }),
+    );
+    expect(node.kind).toBe("image");
+    expect(node.image).toEqual({
+      href: "https://example.com/a.png",
+      fit: "contain",
+    });
+  });
+
+  it("recurses into children", () => {
+    const node = hydrateRawFigmaSvgNode(
+      rawBoxFixture({
+        children: [rawBoxFixture({ id: "child", name: "Child" })],
+      }),
+    );
+    expect(node.children).toHaveLength(1);
+    expect(node.children?.[0].name).toBe("Child");
+  });
+});
diff --git a/templates/design/server/lib/design-to-figma-svg.ts b/templates/design/server/lib/design-to-figma-svg.ts
new file mode 100644
index 0000000000..54b15c27c8
--- /dev/null
+++ b/templates/design/server/lib/design-to-figma-svg.ts
@@ -0,0 +1,1412 @@
+/**
+ * design-to-figma-svg.ts — serialize the design element model (absolutely
+ * positioned boxes + flex auto-layout containers, text, images, solid/
+ * gradient/image fills, borders, border-radius, shadows/blurs, opacity,
+ * rotation) into a standalone, GENUINELY VECTOR SVG document that Figma
+ * imports as editable shapes — not the `foreignObject` wrapper produced by
+ * `buildSvgForeignObject` in `design-export.ts` (that one round-trips the
+ * live DOM/CSS for the editor's own "Download SVG" command, but Figma cannot
+ * import `foreignObject` content as vectors — it stays an opaque embedded
+ * HTML blob). This module builds real `<rect>`/`<path>`/`<text>`/`<image>`
+ * markup with `<linearGradient>`/`<radialGradient>`/`<filter>` defs, which
+ * Figma's SVG importer parses into normal editable layers.
+ *
+ * Two layers:
+ *
+ *  1. A pure, browser-free SCENE -> SVG serializer (`buildFigmaSvgDocument`
+ *     and its helpers below). It consumes a `FigmaSvgNode` tree — plain
+ *     data, no DOM — and emits SVG markup plus an export report. This is
+ *     the part covered by `design-to-figma-svg.spec.ts` with hand-built
+ *     fixture nodes (gradient stops, rounded-rect path commands, stroke
+ *     inset geometry, tspan positions).
+ *
+ *  2. A Playwright-based SCENE EXTRACTOR (`renderDesignToFigmaSvg`, backed by
+ *     the in-page `collectRawFigmaSvgScene` walk) that renders the design's
+ *     real stored HTML in headless Chromium (mirrors
+ *     `take-design-screenshot.ts`'s launch/import pattern) and walks the
+ *     live, laid-out DOM to build a `FigmaSvgNode` tree from real
+ *     `getBoundingClientRect()` / `getComputedStyle()` values. Delegating
+ *     geometry to the actual browser layout engine is what makes the boxes
+ *     PIXEL-PERFECT without reimplementing flexbox/auto-layout math by hand
+ *     — the same reason `take-design-screenshot.ts` renders instead of
+ *     statically analyzing HTML. This half is exercised in practice via the
+ *     `export-design-as-figma-svg` action, not vitest (same split as
+ *     `collectPageDiagnostics` in `take-design-screenshot.ts` — see that
+ *     file's spec docblock for the rationale).
+ */
+
+import { parseCssColorExtended } from "../../shared/color-utils.js";
+import { importPlaywright, launchChromium } from "./playwright-runtime.js";
+
+// ---------------------------------------------------------------------------
+// Scene types
+// ---------------------------------------------------------------------------
+
+export interface FigmaSvgRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface FigmaSvgCornerRadii {
+  tl: number;
+  tr: number;
+  br: number;
+  bl: number;
+}
+
+export const ZERO_RADII: FigmaSvgCornerRadii = { tl: 0, tr: 0, br: 0, bl: 0 };
+
+export interface FigmaSvgColorStop {
+  /** 0-1 */
+  offset: number;
+  /** Any valid SVG color (rgb()/rgba()/#hex/named). */
+  color: string;
+}
+
+export type FigmaSvgFillLayer =
+  | { kind: "solid"; color: string }
+  | { kind: "linear-gradient"; angleDeg: number; stops: FigmaSvgColorStop[] }
+  | {
+      kind: "radial-gradient";
+      stops: FigmaSvgColorStop[];
+      /** objectBoundingBox 0-1, default centered circle. */
+      cx?: number;
+      cy?: number;
+      r?: number;
+    }
+  | {
+      kind: "image";
+      href: string;
+      fit: "cover" | "contain" | "stretch";
+    };
+
+export interface FigmaSvgShadow {
+  offsetX: number;
+  offsetY: number;
+  blur: number;
+  spread: number;
+  color: string;
+  inset?: boolean;
+}
+
+export interface FigmaSvgBorder {
+  widthPx: number;
+  color: string;
+  dashed?: boolean;
+  /** Set when the source had non-uniform per-side width/color/style and we
+   *  fell back to one representative side — surfaced as "approximated". */
+  nonUniform?: boolean;
+}
+
+export interface FigmaSvgTextLine {
+  text: string;
+  x: number;
+  /** Vertical CENTER of the line box (rendered with dominant-baseline="central"). */
+  y: number;
+}
+
+export interface FigmaSvgTextStyle {
+  fontFamily: string;
+  fontSizePx: number;
+  fontWeight?: number;
+  italic?: boolean;
+  letterSpacingPx?: number;
+  color: string;
+  textAlign?: "left" | "center" | "right" | "justify";
+}
+
+export interface FigmaSvgNode {
+  /** Stable id used for SVG element ids / gradient-def ids / the export report. */
+  id: string;
+  /** Human label (from data-agent-native-layer-name or a fallback). */
+  name?: string;
+  kind: "box" | "text" | "image" | "raster";
+  rect: FigmaSvgRect;
+  rotationDeg?: number;
+  /** 0-1; omit or 1 for fully opaque. */
+  opacity?: number;
+  cornerRadii?: FigmaSvgCornerRadii;
+  /** CSS order: index 0 is the TOPMOST paint layer (painted last in SVG). */
+  fills?: FigmaSvgFillLayer[];
+  border?: FigmaSvgBorder;
+  /** Non-inset drop shadows; inset shadows are reported as approximated/omitted. */
+  shadows?: FigmaSvgShadow[];
+  text?: { lines: FigmaSvgTextLine[]; style: FigmaSvgTextStyle };
+  image?: { href: string; fit: "cover" | "contain" | "stretch" };
+  /** Fully rasterized fallback (video/canvas/iframe/backdrop-blur/other unsupported paint). */
+  raster?: { href: string; reason: string };
+  children?: FigmaSvgNode[];
+}
+
+export interface FigmaSvgExportReport {
+  vectorized: string[];
+  approximated: Array<{ node: string; note: string }>;
+  rasterized: Array<{ node: string; reason: string }>;
+  omitted: Array<{ node: string; reason: string }>;
+  warnings: string[];
+  /** One-time caveat surfaced regardless of whether any text node was found. */
+  vectorizedTextCaveat: string;
+}
+
+// ---------------------------------------------------------------------------
+// Small formatting helpers
+// ---------------------------------------------------------------------------
+
+/** Round to 3 decimal places and strip a trailing ".000"/trailing zeros. */
+export function n(value: number): string {
+  if (!Number.isFinite(value)) return "0";
+  const rounded = Math.round(value * 1000) / 1000;
+  return String(rounded);
+}
+
+export function escapeXmlAttr(value: string): string {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+export function escapeXmlText(value: string): string {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+export function isUniformRadius(radii: FigmaSvgCornerRadii): boolean {
+  return (
+    radii.tl === radii.tr && radii.tr === radii.br && radii.br === radii.bl
+  );
+}
+
+export function isZeroRadii(radii: FigmaSvgCornerRadii): boolean {
+  return radii.tl === 0 && radii.tr === 0 && radii.br === 0 && radii.bl === 0;
+}
+
+export function clampRadius(radius: number, maxRadius: number): number {
+  return Math.max(0, Math.min(radius, maxRadius));
+}
+
+// ---------------------------------------------------------------------------
+// Rounded-rect path (per-corner radii) — SVG's `rx`/`ry` on <rect> is
+// uniform-only, so any element with differing corner radii must be emitted
+// as an explicit path built from four line/arc segments.
+// ---------------------------------------------------------------------------
+
+export function roundedRectPath(
+  rect: FigmaSvgRect,
+  radii: FigmaSvgCornerRadii,
+): string {
+  const { x, y, width, height } = rect;
+  const maxR = Math.max(0, Math.min(width, height) / 2);
+  const tl = clampRadius(radii.tl, maxR);
+  const tr = clampRadius(radii.tr, maxR);
+  const br = clampRadius(radii.br, maxR);
+  const bl = clampRadius(radii.bl, maxR);
+  const x2 = x + width;
+  const y2 = y + height;
+
+  return [
+    `M ${n(x + tl)} ${n(y)}`,
+    `L ${n(x2 - tr)} ${n(y)}`,
+    tr > 0 ? `A ${n(tr)} ${n(tr)} 0 0 1 ${n(x2)} ${n(y + tr)}` : "",
+    `L ${n(x2)} ${n(y2 - br)}`,
+    br > 0 ? `A ${n(br)} ${n(br)} 0 0 1 ${n(x2 - br)} ${n(y2)}` : "",
+    `L ${n(x + bl)} ${n(y2)}`,
+    bl > 0 ? `A ${n(bl)} ${n(bl)} 0 0 1 ${n(x)} ${n(y2 - bl)}` : "",
+    `L ${n(x)} ${n(y + tl)}`,
+    tl > 0 ? `A ${n(tl)} ${n(tl)} 0 0 1 ${n(x + tl)} ${n(y)}` : "",
+    "Z",
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+// ---------------------------------------------------------------------------
+// Border stroke geometry — CSS `border` paints INSIDE the box edge (the box's
+// own width/height already include the border band). SVG strokes are
+// centered on the path by default. Insetting the stroke's path by half the
+// stroke width on every side makes the stroke's outer edge land exactly on
+// the box's true edge and its inner edge land exactly border-width inside —
+// i.e. pixel-identical to the CSS border band — while a separate full-rect
+// fill shape (background-clip: border-box) still paints all the way to the
+// true edge underneath it.
+// ---------------------------------------------------------------------------
+
+export function insetRectForStroke(
+  rect: FigmaSvgRect,
+  strokeWidth: number,
+): FigmaSvgRect {
+  const inset = strokeWidth / 2;
+  const width = Math.max(0, rect.width - strokeWidth);
+  const height = Math.max(0, rect.height - strokeWidth);
+  return { x: rect.x + inset, y: rect.y + inset, width, height };
+}
+
+export function insetRadiiForStroke(
+  radii: FigmaSvgCornerRadii,
+  strokeWidth: number,
+): FigmaSvgCornerRadii {
+  const d = strokeWidth / 2;
+  const clamp = (r: number) => Math.max(0, r - d);
+  return {
+    tl: clamp(radii.tl),
+    tr: clamp(radii.tr),
+    br: clamp(radii.br),
+    bl: clamp(radii.bl),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Gradients
+// ---------------------------------------------------------------------------
+
+/**
+ * CSS `0deg` points "to top"; SVG's default objectBoundingBox gradient
+ * vector runs (0,0) -> (1,0), i.e. "to right", which is CSS's `90deg`.
+ * Rotating that default vector by `(angleDeg - 90)` around the box center
+ * reproduces the CSS direction exactly for a SQUARE element. For a
+ * non-square element, objectBoundingBox first non-uniformly scales the unit
+ * gradient vector to the box's aspect ratio before the rotation is applied,
+ * which skews the visually-apparent angle — documented in the export report
+ * as an approximation for non-square boxes, not a bug in this formula.
+ */
+export function gradientAngleToRotation(angleDeg: number): number {
+  return (((angleDeg - 90) % 360) + 360) % 360;
+}
+
+function stopMarkup(stops: FigmaSvgColorStop[]): string {
+  return stops
+    .map(
+      (s) =>
+        `<stop offset="${n(s.offset * 100)}%" stop-color="${escapeXmlAttr(s.color)}"/>`,
+    )
+    .join("");
+}
+
+export function buildLinearGradientDef(
+  id: string,
+  angleDeg: number,
+  stops: FigmaSvgColorStop[],
+): string {
+  const rotation = gradientAngleToRotation(angleDeg);
+  return `<linearGradient id="${id}" x1="0" y1="0" x2="1" y2="0" gradientTransform="rotate(${n(rotation)} 0.5 0.5)">${stopMarkup(stops)}</linearGradient>`;
+}
+
+export function buildRadialGradientDef(
+  id: string,
+  stops: FigmaSvgColorStop[],
+  opts?: { cx?: number; cy?: number; r?: number },
+): string {
+  const cx = opts?.cx ?? 0.5;
+  const cy = opts?.cy ?? 0.5;
+  const r = opts?.r ?? 0.5;
+  return `<radialGradient id="${id}" cx="${n(cx)}" cy="${n(cy)}" r="${n(r)}">${stopMarkup(stops)}</radialGradient>`;
+}
+
+// ---------------------------------------------------------------------------
+// Computed-style string parsers — pure, unit-testable without a browser.
+// These assume Chromium's normalized `getComputedStyle` output (the engine
+// `extractFigmaSvgScene` renders with), documented per-function.
+// ---------------------------------------------------------------------------
+
+/** Split on top-level commas only — doesn't split inside `rgba(...)`/`rgb(...)` parens. */
+export function splitTopLevelCommas(value: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of value) {
+    if (ch === "(") depth++;
+    if (ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current.trim());
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+const LENGTH_RE = /(-?[\d.]+)px/g;
+
+/**
+ * Parses Chromium's computed `box-shadow` string, e.g.
+ * `"rgba(0, 0, 0, 0.25) 0px 4px 12px 0px"` or `"rgb(0,0,0) 0px 2px 4px 0px inset"`,
+ * including multiple comma-separated shadows.
+ */
+export function parseComputedBoxShadow(
+  value: string | null | undefined,
+): FigmaSvgShadow[] {
+  if (!value || value === "none") return [];
+  return splitTopLevelCommas(value).map((part) => {
+    const inset = /\binset\b/.test(part);
+    const withoutInset = part.replace(/\binset\b/g, "").trim();
+    const colorMatch = withoutInset.match(
+      /^(rgba?\([^)]*\)|#[0-9a-fA-F]{3,8}|[a-zA-Z]+)/,
+    );
+    const color = colorMatch ? colorMatch[0] : "rgb(0, 0, 0)";
+    const rest = colorMatch
+      ? withoutInset.slice(colorMatch[0].length)
+      : withoutInset;
+    const lengths = Array.from(rest.matchAll(LENGTH_RE)).map((m) =>
+      Number.parseFloat(m[1]),
+    );
+    const [offsetX = 0, offsetY = 0, blur = 0, spread = 0] = lengths;
+    return { offsetX, offsetY, blur, spread, color, inset };
+  });
+}
+
+const ANGLE_KEYWORDS: Record<string, number> = {
+  "to top": 0,
+  "to top right": 45,
+  "to right top": 45,
+  "to right": 90,
+  "to bottom right": 135,
+  "to right bottom": 135,
+  "to bottom": 180,
+  "to bottom left": 225,
+  "to left bottom": 225,
+  "to left": 270,
+  "to top left": 315,
+  "to left top": 315,
+};
+
+function parseColorStop(part: string): FigmaSvgColorStop {
+  const trimmed = part.trim();
+  const percentMatch = trimmed.match(/(-?[\d.]+)%\s*$/);
+  if (!percentMatch) return { offset: 0, color: trimmed };
+  const offset = Number.parseFloat(percentMatch[1]) / 100;
+  const color = trimmed.slice(0, percentMatch.index).trim();
+  return { offset, color };
+}
+
+export interface ParsedGradient {
+  angleDeg: number;
+  stops: FigmaSvgColorStop[];
+}
+
+/**
+ * Parses Chromium's computed `linear-gradient(...)` string. Assumes explicit
+ * percentage stops, which Chromium always fills in on computed style even
+ * when the source omitted them.
+ */
+export function parseComputedLinearGradient(
+  value: string,
+): ParsedGradient | null {
+  const match = value.match(/linear-gradient\((.*)\)\s*$/s);
+  if (!match) return null;
+  const parts = splitTopLevelCommas(match[1]);
+  let angleDeg = 180; // CSS default direction is "to bottom".
+  let stopParts = parts;
+  const first = (parts[0] ?? "").trim();
+  const degMatch = first.match(/^(-?[\d.]+)deg$/);
+  if (degMatch) {
+    angleDeg = Number.parseFloat(degMatch[1]);
+    stopParts = parts.slice(1);
+  } else if (/^to\s/.test(first) && first in ANGLE_KEYWORDS) {
+    angleDeg = ANGLE_KEYWORDS[first];
+    stopParts = parts.slice(1);
+  }
+  return { angleDeg, stops: stopParts.map(parseColorStop) };
+}
+
+/**
+ * Parses Chromium's computed `radial-gradient(...)` string. Shape/position
+ * nuances (ellipse vs circle, off-center `at` position) are not modeled —
+ * always mapped to a centered circle spanning the element's bounding box —
+ * so callers should surface this as an approximation.
+ */
+export function parseComputedRadialGradient(
+  value: string,
+): { stops: FigmaSvgColorStop[] } | null {
+  const match = value.match(/radial-gradient\((.*)\)\s*$/s);
+  if (!match) return null;
+  const parts = splitTopLevelCommas(match[1]);
+  const stopParts = /\bat\b|circle|ellipse/.test(parts[0] ?? "")
+    ? parts.slice(1)
+    : parts;
+  return { stops: stopParts.map(parseColorStop) };
+}
+
+// ---------------------------------------------------------------------------
+// object-fit -> preserveAspectRatio
+// ---------------------------------------------------------------------------
+
+/**
+ * SVG `preserveAspectRatio="... slice"` clips content to the image's own
+ * x/y/width/height viewport, which reproduces CSS `object-fit: cover`
+ * exactly with no extra `<clipPath>` needed. `object-position` is not
+ * modeled beyond the common `center` case (always emits `xMidYMid`) —
+ * approximated for any other alignment.
+ */
+export function objectFitToPreserveAspectRatio(
+  fit: "cover" | "contain" | "stretch" | "none" | "scale-down",
+): string {
+  if (fit === "stretch" || fit === "none") return "none";
+  if (fit === "contain" || fit === "scale-down") return "xMidYMid meet";
+  return "xMidYMid slice"; // cover (default)
+}
+
+// ---------------------------------------------------------------------------
+// Shadow filter defs
+// ---------------------------------------------------------------------------
+
+function floodColorParts(color: string): {
+  floodColor: string;
+  floodOpacity: number;
+} {
+  const parsed = parseCssColorExtended(color);
+  if (!parsed) return { floodColor: color, floodOpacity: 1 };
+  return {
+    floodColor: `rgb(${Math.round(parsed.r)}, ${Math.round(parsed.g)}, ${Math.round(parsed.b)})`,
+    floodOpacity: parsed.a,
+  };
+}
+
+/**
+ * Builds a `<filter>` def for the non-inset shadows in `shadows` (inset
+ * shadows are the caller's responsibility to report as approximated/omitted
+ * — SVG has no direct inset-shadow primitive). Shadows with `spread === 0`
+ * use a plain `feDropShadow` chain; any shadow with a non-zero spread needs
+ * the decomposed feMorphology (dilate/erode) + feGaussianBlur + feOffset +
+ * feFlood + feComposite chain, since `feDropShadow` has no spread parameter.
+ * `stdDeviation = blur / 2` is the standard CSS-blur-radius-to-SVG-Gaussian
+ * conversion used across browsers/renderers.
+ */
+export function buildShadowFilterDef(
+  id: string,
+  shadows: FigmaSvgShadow[],
+): string {
+  const outer = shadows.filter((s) => !s.inset);
+  if (outer.length === 0) return "";
+
+  if (outer.every((s) => s.spread === 0)) {
+    const drops = outer
+      .map((s) => {
+        const { floodColor, floodOpacity } = floodColorParts(s.color);
+        return `<feDropShadow dx="${n(s.offsetX)}" dy="${n(s.offsetY)}" stdDeviation="${n(s.blur / 2)}" flood-color="${escapeXmlAttr(floodColor)}" flood-opacity="${n(floodOpacity)}"/>`;
+      })
+      .join("");
+    return `<filter id="${id}" x="-50%" y="-50%" width="200%" height="200%">${drops}</filter>`;
+  }
+
+  const parts = outer
+    .map((s, i) => {
+      const morph =
+        s.spread !== 0
+          ? `<feMorphology in="SourceAlpha" operator="${s.spread > 0 ? "dilate" : "erode"}" radius="${n(Math.abs(s.spread))}" result="spread${i}"/>`
+          : "";
+      const blurIn = s.spread !== 0 ? `spread${i}` : "SourceAlpha";
+      const { floodColor, floodOpacity } = floodColorParts(s.color);
+      return (
+        `${morph}` +
+        `<feGaussianBlur in="${blurIn}" stdDeviation="${n(s.blur / 2)}" result="blur${i}"/>` +
+        `<feOffset in="blur${i}" dx="${n(s.offsetX)}" dy="${n(s.offsetY)}" result="offset${i}"/>` +
+        `<feFlood flood-color="${escapeXmlAttr(floodColor)}" flood-opacity="${n(floodOpacity)}" result="color${i}"/>` +
+        `<feComposite in="color${i}" in2="offset${i}" operator="in" result="shadow${i}"/>`
+      );
+    })
+    .join("");
+  const merge = `<feMerge>${outer.map((_, i) => `<feMergeNode in="shadow${i}"/>`).join("")}<feMergeNode in="SourceGraphic"/></feMerge>`;
+  return `<filter id="${id}" x="-50%" y="-50%" width="200%" height="200%">${parts}${merge}</filter>`;
+}
+
+// ---------------------------------------------------------------------------
+// Node renderer
+// ---------------------------------------------------------------------------
+
+interface RenderCtx {
+  defs: string[];
+  report: FigmaSvgExportReport;
+  nextId: (prefix: string) => string;
+}
+
+function wrapGroup(
+  markup: string,
+  node: Pick<FigmaSvgNode, "rect" | "rotationDeg" | "opacity">,
+): string {
+  const attrs: string[] = [];
+  if (node.rotationDeg) {
+    const cx = node.rect.x + node.rect.width / 2;
+    const cy = node.rect.y + node.rect.height / 2;
+    attrs.push(`transform="rotate(${n(node.rotationDeg)} ${n(cx)} ${n(cy)})"`);
+  }
+  if (node.opacity !== undefined && node.opacity !== 1) {
+    attrs.push(`opacity="${n(node.opacity)}"`);
+  }
+  if (attrs.length === 0) return markup;
+  return `<g ${attrs.join(" ")}>${markup}</g>`;
+}
+
+function resolveFillPaint(
+  fill: FigmaSvgFillLayer,
+  node: FigmaSvgNode,
+  ctx: RenderCtx,
+): string {
+  if (fill.kind === "solid") return fill.color;
+
+  if (fill.kind === "linear-gradient") {
+    const id = ctx.nextId("lg");
+    ctx.defs.push(buildLinearGradientDef(id, fill.angleDeg, fill.stops));
+    const isSquareish = Math.abs(node.rect.width - node.rect.height) < 1;
+    if (!isSquareish) {
+      ctx.report.approximated.push({
+        node: node.name || node.id,
+        note: "Linear gradient angle mapped via objectBoundingBox rotation; exact for square elements, approximated for this element's non-square aspect ratio.",
+      });
+    }
+    return `url(#${id})`;
+  }
+
+  if (fill.kind === "radial-gradient") {
+    const id = ctx.nextId("rg");
+    ctx.defs.push(
+      buildRadialGradientDef(id, fill.stops, {
+        cx: fill.cx,
+        cy: fill.cy,
+        r: fill.r,
+      }),
+    );
+    ctx.report.approximated.push({
+      node: node.name || node.id,
+      note: "Radial gradient shape/position approximated as a centered circle over the element's bounding box.",
+    });
+    return `url(#${id})`;
+  }
+
+  // image fill
+  const id = ctx.nextId("img-fill");
+  const par = objectFitToPreserveAspectRatio(fill.fit);
+  ctx.defs.push(
+    `<pattern id="${id}" patternUnits="objectBoundingBox" width="1" height="1"><image href="${escapeXmlAttr(fill.href)}" x="0" y="0" width="${n(node.rect.width)}" height="${n(node.rect.height)}" preserveAspectRatio="${par}"/></pattern>`,
+  );
+  ctx.report.approximated.push({
+    node: node.name || node.id,
+    note: "Background-image fill approximated via an objectBoundingBox pattern; exact cover/contain cropping may differ from the browser for extreme aspect ratios.",
+  });
+  return `url(#${id})`;
+}
+
+function renderBox(node: FigmaSvgNode, ctx: RenderCtx): string {
+  const rect = node.rect;
+  const radii = node.cornerRadii ?? ZERO_RADII;
+  const fills = node.fills ?? [];
+
+  let filterId: string | null = null;
+  if (node.shadows && node.shadows.length > 0) {
+    const insetShadows = node.shadows.filter((s) => s.inset);
+    if (insetShadows.length > 0) {
+      ctx.report.approximated.push({
+        node: node.name || node.id,
+        note: `${insetShadows.length} inset shadow(s) omitted — SVG has no direct inset-shadow primitive.`,
+      });
+    }
+    const id = ctx.nextId("shadow");
+    const def = buildShadowFilterDef(id, node.shadows);
+    if (def) {
+      ctx.defs.push(def);
+      filterId = id;
+    }
+  }
+
+  const fillTag = (
+    r: FigmaSvgRect,
+    radiiForShape: FigmaSvgCornerRadii,
+    paint: string,
+    filterAttr: string,
+  ) =>
+    isUniformRadius(radiiForShape)
+      ? `<rect x="${n(r.x)}" y="${n(r.y)}" width="${n(r.width)}" height="${n(r.height)}"${radiiForShape.tl ? ` rx="${n(radiiForShape.tl)}"` : ""} fill="${paint}"${filterAttr}/>`
+      : `<path d="${roundedRectPath(r, radiiForShape)}" fill="${paint}"${filterAttr}/>`;
+
+  // CSS background layer 0 is the TOPMOST paint; SVG paints later elements
+  // on top, so emit layers in reverse (last CSS layer first). Only the
+  // topmost (last-emitted) shape carries the shadow filter — lower layers
+  // must not double-apply it.
+  const layers =
+    fills.length > 0
+      ? fills
+      : [{ kind: "solid", color: "none" } as FigmaSvgFillLayer];
+  const reversedLayers = layers.slice().reverse();
+  let body = reversedLayers
+    .map((f, i) => {
+      const isTopmost = i === reversedLayers.length - 1;
+      const paint = resolveFillPaint(f, node, ctx);
+      const filterAttr =
+        isTopmost && filterId ? ` filter="url(#${filterId})"` : "";
+      return fillTag(rect, radii, paint, filterAttr);
+    })
+    .join("");
+
+  if (node.border && node.border.widthPx > 0) {
+    const insetRect = insetRectForStroke(rect, node.border.widthPx);
+    const insetRadii = insetRadiiForStroke(radii, node.border.widthPx);
+    const dash = node.border.dashed
+      ? ` stroke-dasharray="${n(node.border.widthPx * 2)} ${n(node.border.widthPx)}"`
+      : "";
+    body += isUniformRadius(insetRadii)
+      ? `<rect x="${n(insetRect.x)}" y="${n(insetRect.y)}" width="${n(insetRect.width)}" height="${n(insetRect.height)}"${insetRadii.tl ? ` rx="${n(insetRadii.tl)}"` : ""} fill="none" stroke="${escapeXmlAttr(node.border.color)}" stroke-width="${n(node.border.widthPx)}"${dash}/>`
+      : `<path d="${roundedRectPath(insetRect, insetRadii)}" fill="none" stroke="${escapeXmlAttr(node.border.color)}" stroke-width="${n(node.border.widthPx)}"${dash}/>`;
+    if (node.border.nonUniform) {
+      ctx.report.approximated.push({
+        node: node.name || node.id,
+        note: "Border had differing per-side width/color/style; rendered using one representative side.",
+      });
+    }
+  }
+
+  ctx.report.vectorized.push(node.name || node.id);
+  const childrenMarkup = (node.children ?? [])
+    .map((child) => renderFigmaSvgNode(child, ctx))
+    .join("");
+  return wrapGroup(body + childrenMarkup, node);
+}
+
+function renderText(node: FigmaSvgNode, ctx: RenderCtx): string {
+  if (!node.text) return "";
+  const { style, lines } = node.text;
+  const anchor =
+    style.textAlign === "center"
+      ? "middle"
+      : style.textAlign === "right"
+        ? "end"
+        : "start";
+  if (style.textAlign === "justify") {
+    ctx.report.approximated.push({
+      node: node.name || node.id,
+      note: "text-align: justify has no SVG equivalent; rendered left-aligned.",
+    });
+  }
+
+  const tspans = lines
+    .map(
+      (l) =>
+        `<tspan x="${n(l.x)}" y="${n(l.y)}">${escapeXmlText(l.text)}</tspan>`,
+    )
+    .join("");
+  const attrs = [
+    `font-family="${escapeXmlAttr(style.fontFamily)}"`,
+    `font-size="${n(style.fontSizePx)}"`,
+    style.fontWeight ? `font-weight="${style.fontWeight}"` : "",
+    style.italic ? `font-style="italic"` : "",
+    style.letterSpacingPx ? `letter-spacing="${n(style.letterSpacingPx)}"` : "",
+    `fill="${escapeXmlAttr(style.color)}"`,
+    `text-anchor="${anchor}"`,
+    `dominant-baseline="central"`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  ctx.report.vectorized.push(node.name || node.id);
+  return wrapGroup(`<text ${attrs}>${tspans}</text>`, node);
+}
+
+function renderImage(node: FigmaSvgNode, ctx: RenderCtx): string {
+  if (!node.image) return "";
+  const rect = node.rect;
+  const radii = node.cornerRadii ?? ZERO_RADII;
+  const par = objectFitToPreserveAspectRatio(node.image.fit);
+  let clipAttr = "";
+  if (!isZeroRadii(radii)) {
+    const clipId = ctx.nextId("clip");
+    const shape = isUniformRadius(radii)
+      ? `<rect x="${n(rect.x)}" y="${n(rect.y)}" width="${n(rect.width)}" height="${n(rect.height)}" rx="${n(radii.tl)}"/>`
+      : `<path d="${roundedRectPath(rect, radii)}"/>`;
+    ctx.defs.push(`<clipPath id="${clipId}">${shape}</clipPath>`);
+    clipAttr = ` clip-path="url(#${clipId})"`;
+  }
+  ctx.report.vectorized.push(node.name || node.id);
+  const markup = `<image x="${n(rect.x)}" y="${n(rect.y)}" width="${n(rect.width)}" height="${n(rect.height)}" href="${escapeXmlAttr(node.image.href)}" preserveAspectRatio="${par}"${clipAttr}/>`;
+  return wrapGroup(markup, node);
+}
+
+function renderRaster(node: FigmaSvgNode, ctx: RenderCtx): string {
+  if (!node.raster) return "";
+  ctx.report.rasterized.push({
+    node: node.name || node.id,
+    reason: node.raster.reason,
+  });
+  const rect = node.rect;
+  const markup = `<image x="${n(rect.x)}" y="${n(rect.y)}" width="${n(rect.width)}" height="${n(rect.height)}" href="${escapeXmlAttr(node.raster.href)}" preserveAspectRatio="none"/>`;
+  return wrapGroup(markup, node);
+}
+
+export function renderFigmaSvgNode(node: FigmaSvgNode, ctx: RenderCtx): string {
+  switch (node.kind) {
+    case "box":
+      return renderBox(node, ctx);
+    case "text":
+      return renderText(node, ctx);
+    case "image":
+      return renderImage(node, ctx);
+    case "raster":
+      return renderRaster(node, ctx);
+    default:
+      return "";
+  }
+}
+
+export function createEmptyFigmaSvgReport(): FigmaSvgExportReport {
+  return {
+    vectorized: [],
+    approximated: [],
+    rasterized: [],
+    omitted: [],
+    warnings: [],
+    vectorizedTextCaveat:
+      "SVG <text> elements have pixel-exact geometry, but Figma converts ALL " +
+      "imported SVG text to outlined vector paths on paste/drag-import — it " +
+      "will not be live, editable type in Figma. This is a Figma import " +
+      "limitation, not a defect in this export.",
+  };
+}
+
+export function buildFigmaSvgDocument(args: {
+  width: number;
+  height: number;
+  title?: string | null;
+  root: FigmaSvgNode;
+}): { svg: string; report: FigmaSvgExportReport } {
+  const report = createEmptyFigmaSvgReport();
+  let idCounter = 0;
+  const ctx: RenderCtx = {
+    defs: [],
+    report,
+    nextId: (prefix) => `${prefix}-${++idCounter}`,
+  };
+  const body = renderFigmaSvgNode(args.root, ctx);
+  const defsBlock = ctx.defs.length ? `<defs>${ctx.defs.join("")}</defs>` : "";
+  const titleTag = args.title
+    ? `<title>${escapeXmlText(args.title)}</title>`
+    : "";
+  const svg =
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${n(args.width)}" height="${n(args.height)}" viewBox="0 0 ${n(args.width)} ${n(args.height)}">` +
+    `${titleTag}${defsBlock}${body}</svg>`;
+  return { svg, report };
+}
+
+export function safeFigmaSvgFilename(title: string | null | undefined): string {
+  const safe = (title || "design")
+    .replace(/[^a-zA-Z0-9_-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return `${safe || "design"}-figma-${Date.now()}.svg`;
+}
+
+// ---------------------------------------------------------------------------
+// Raw scene (browser-extracted) -> FigmaSvgNode hydration
+// ---------------------------------------------------------------------------
+//
+// `extractFigmaSvgScene` below walks the LIVE rendered DOM inside Playwright
+// and returns a tree of `RawFigmaSvgNode` — mostly-untouched computed-style
+// STRINGS plus real geometry from getBoundingClientRect(). The functions in
+// this section turn that raw tree into the final `FigmaSvgNode` tree consumed
+// by `buildFigmaSvgDocument` above, reusing the same pure
+// `parseComputedBoxShadow` / `parseComputedLinearGradient` /
+// `parseComputedRadialGradient` parsers already covered by
+// `design-to-figma-svg.spec.ts` — so this hydration step is itself pure and
+// unit-testable with a hand-built `RawFigmaSvgNode` fixture (no browser
+// needed), even though the DOM WALK that produces the raw tree is not.
+
+export interface RawFigmaSvgTextLine {
+  text: string;
+  x: number;
+  y: number;
+}
+
+export interface RawFigmaSvgTextStyle {
+  fontFamily: string;
+  fontSizePx: number;
+  fontWeight: number;
+  italic: boolean;
+  letterSpacingPx: number;
+  color: string;
+  textAlign: string;
+}
+
+export interface RawFigmaSvgNode {
+  id: string;
+  name?: string;
+  domTag: string;
+  rect: FigmaSvgRect;
+  rotationDeg: number;
+  opacity: number;
+  cornerRadiiRaw: FigmaSvgCornerRadii;
+  /** Computed `background-color`, e.g. "rgba(0, 0, 0, 0)" or "rgb(255, 255, 255)". */
+  backgroundColor: string;
+  /** Computed `background-image`, e.g. "none" or a comma-separated gradient/url list. */
+  backgroundImage: string;
+  /** Computed `box-shadow`, e.g. "none" or a Chromium-normalized shadow list. */
+  boxShadow: string;
+  borderWidthPx: number;
+  borderColor: string;
+  borderStyle: string;
+  borderNonUniform: boolean;
+  backdropFilter: string;
+  isLeafText: boolean;
+  textLines?: RawFigmaSvgTextLine[];
+  textStyle?: RawFigmaSvgTextStyle;
+  imgSrc?: string;
+  imgObjectFit?: string;
+  /** Set when this node must be rasterized (video/canvas/iframe/backdrop-blur/other unsupported paint). */
+  rasterReason?: string;
+  /** Filled in by the orchestrator after a screenshot crop (data: URI or hosted URL). */
+  rasterHref?: string;
+  children: RawFigmaSvgNode[];
+}
+
+/**
+ * Normalizes CSS `object-fit` to the 3-way union `FigmaSvgFill`/`image` fit
+ * accepts. `none` (no scaling) and `scale-down` (contain, but never upscale)
+ * both approximate to `contain` — closest available SVG mapping.
+ */
+function objectFitFromRaw(raw?: string): "cover" | "contain" | "stretch" {
+  if (raw === "cover") return "cover";
+  if (raw === "contain" || raw === "none" || raw === "scale-down")
+    return "contain";
+  return "stretch"; // CSS default object-fit is "fill", closest SVG mapping is "stretch".
+}
+
+/**
+ * Builds the ordered `FigmaSvgFillLayer[]` for a box's own background paint:
+ * each comma-separated `background-image` layer (gradients/url()) in CSS
+ * order (index 0 = topmost), followed by `background-color` as the implicit
+ * bottommost layer when it isn't fully transparent.
+ */
+export function buildFillLayersFromComputedStyle(
+  backgroundColor: string,
+  backgroundImage: string,
+): FigmaSvgFillLayer[] {
+  const layers: FigmaSvgFillLayer[] = [];
+
+  if (backgroundImage && backgroundImage !== "none") {
+    for (const part of splitTopLevelCommas(backgroundImage)) {
+      if (part.startsWith("linear-gradient")) {
+        const parsed = parseComputedLinearGradient(part);
+        if (parsed) {
+          layers.push({
+            kind: "linear-gradient",
+            angleDeg: parsed.angleDeg,
+            stops: parsed.stops,
+          });
+        }
+      } else if (part.startsWith("radial-gradient")) {
+        const parsed = parseComputedRadialGradient(part);
+        if (parsed)
+          layers.push({ kind: "radial-gradient", stops: parsed.stops });
+      } else if (part.startsWith("url(")) {
+        const hrefMatch = part.match(/url\((["']?)(.*?)\1\)/);
+        if (hrefMatch)
+          layers.push({ kind: "image", href: hrefMatch[2], fit: "cover" });
+      }
+    }
+  }
+
+  const bg = parseCssColorExtended(backgroundColor);
+  if (bg && bg.a > 0) {
+    layers.push({
+      kind: "solid",
+      color: `rgba(${Math.round(bg.r)}, ${Math.round(bg.g)}, ${Math.round(bg.b)}, ${bg.a})`,
+    });
+  }
+
+  return layers;
+}
+
+/** Pure hydration: `RawFigmaSvgNode` (browser-extracted computed strings + geometry) -> `FigmaSvgNode`. */
+export function hydrateRawFigmaSvgNode(raw: RawFigmaSvgNode): FigmaSvgNode {
+  const rotationDeg = raw.rotationDeg ? raw.rotationDeg : undefined;
+  const opacity = raw.opacity !== 1 ? raw.opacity : undefined;
+
+  if (raw.rasterReason) {
+    return {
+      id: raw.id,
+      name: raw.name,
+      kind: "raster",
+      rect: raw.rect,
+      rotationDeg,
+      opacity,
+      raster: { href: raw.rasterHref ?? "", reason: raw.rasterReason },
+    };
+  }
+
+  if (raw.isLeafText && raw.textLines && raw.textStyle) {
+    const textAlign =
+      raw.textStyle.textAlign === "center" ||
+      raw.textStyle.textAlign === "right" ||
+      raw.textStyle.textAlign === "justify"
+        ? raw.textStyle.textAlign
+        : "left";
+    return {
+      id: raw.id,
+      name: raw.name,
+      kind: "text",
+      rect: raw.rect,
+      rotationDeg,
+      opacity,
+      text: {
+        lines: raw.textLines,
+        style: {
+          fontFamily: raw.textStyle.fontFamily,
+          fontSizePx: raw.textStyle.fontSizePx,
+          fontWeight: raw.textStyle.fontWeight,
+          italic: raw.textStyle.italic,
+          letterSpacingPx: raw.textStyle.letterSpacingPx,
+          color: raw.textStyle.color,
+          textAlign,
+        },
+      },
+    };
+  }
+
+  if (raw.domTag === "IMG" && raw.imgSrc) {
+    return {
+      id: raw.id,
+      name: raw.name,
+      kind: "image",
+      rect: raw.rect,
+      rotationDeg,
+      opacity,
+      cornerRadii: isZeroRadii(raw.cornerRadiiRaw)
+        ? undefined
+        : raw.cornerRadiiRaw,
+      image: { href: raw.imgSrc, fit: objectFitFromRaw(raw.imgObjectFit) },
+    };
+  }
+
+  const fills = buildFillLayersFromComputedStyle(
+    raw.backgroundColor,
+    raw.backgroundImage,
+  );
+  const shadows = parseComputedBoxShadow(raw.boxShadow);
+  const border =
+    raw.borderWidthPx > 0
+      ? {
+          widthPx: raw.borderWidthPx,
+          color: raw.borderColor,
+          dashed: raw.borderStyle === "dashed" || raw.borderStyle === "dotted",
+          nonUniform: raw.borderNonUniform || undefined,
+        }
+      : undefined;
+
+  return {
+    id: raw.id,
+    name: raw.name,
+    kind: "box",
+    rect: raw.rect,
+    rotationDeg,
+    opacity,
+    cornerRadii: isZeroRadii(raw.cornerRadiiRaw)
+      ? undefined
+      : raw.cornerRadiiRaw,
+    fills: fills.length > 0 ? fills : undefined,
+    border,
+    shadows: shadows.length > 0 ? shadows : undefined,
+    children: raw.children.map(hydrateRawFigmaSvgNode),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// In-page DOM walk — mirrors take-design-screenshot.ts's
+// `collectPageDiagnostics`: a single self-contained function with no closures
+// over outer scope (Playwright serializes it via `Function#toString()` into
+// the page), so it duplicates a few tiny helpers rather than importing them.
+// Not unit-tested directly for the same reason `collectPageDiagnostics` isn't
+// — see that file's spec docblock. Geometry comes straight from
+// `getBoundingClientRect()`, which is what makes it pixel-perfect without
+// reimplementing flexbox/auto-layout math.
+// ---------------------------------------------------------------------------
+
+interface RawFigmaSvgSceneResult {
+  root: RawFigmaSvgNode;
+  /** The export root's absolute page-space offset, so the orchestrator can
+   *  convert a raster node's origin-relative rect back to page coordinates
+   *  for `page.screenshot({ clip })`. */
+  originOffset: { x: number; y: number };
+}
+
+function collectRawFigmaSvgScene(
+  rootSelector: string | null,
+): RawFigmaSvgSceneResult | null {
+  const root = rootSelector
+    ? document.querySelector(rootSelector)
+    : document.body;
+  if (!root) return null;
+  const originRect = root.getBoundingClientRect();
+  let autoId = 0;
+
+  function nextId(): string {
+    autoId += 1;
+    return `n${autoId}`;
+  }
+
+  function rotationFromTransform(transform: string): number {
+    if (!transform || transform === "none") return 0;
+    const m = transform.match(/matrix\(([^)]+)\)/);
+    if (!m) return 0;
+    const parts = m[1].split(",").map((v) => Number.parseFloat(v.trim()));
+    const [a, b] = parts;
+    if (!Number.isFinite(a) || !Number.isFinite(b)) return 0;
+    return Math.atan2(b, a) * (180 / Math.PI);
+  }
+
+  function isVisible(el: Element, style: CSSStyleDeclaration): boolean {
+    if (style.display === "none" || style.visibility === "hidden") return false;
+    if (el.getAttribute("data-agent-native-hidden") === "true") return false;
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  }
+
+  function splitLineOffsets(
+    node: Text,
+    totalLength: number,
+    lineCount: number,
+  ): number[] {
+    const offsets: number[] = [];
+    let start = 0;
+    const range = document.createRange();
+    for (let line = 0; line < lineCount - 1; line++) {
+      let lo = start;
+      let hi = totalLength;
+      while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        range.setStart(node, start);
+        range.setEnd(node, mid);
+        const rects = Array.from(range.getClientRects());
+        const tops = new Set(rects.map((r) => Math.round(r.top)));
+        if (tops.size <= 1) {
+          lo = mid;
+        } else {
+          hi = mid - 1;
+        }
+      }
+      offsets.push(lo || start + 1);
+      start = offsets[offsets.length - 1];
+    }
+    offsets.push(totalLength);
+    return offsets;
+  }
+
+  function extractTextLines(el: Element): RawFigmaSvgTextLine[] | null {
+    const textNode = Array.from(el.childNodes).find(
+      (c) =>
+        c.nodeType === Node.TEXT_NODE &&
+        (c.textContent || "").trim().length > 0,
+    ) as Text | undefined;
+    if (!textNode || el.children.length > 0) return null;
+    const full = textNode.textContent || "";
+    const range = document.createRange();
+    range.selectNodeContents(textNode);
+    const lineRects = Array.from(range.getClientRects());
+    if (lineRects.length === 0) return null;
+
+    const style = getComputedStyle(el);
+    const textAlign = style.textAlign;
+    const anchorX = (rect: DOMRect) => {
+      if (textAlign === "center") return rect.left + rect.width / 2;
+      if (textAlign === "right" || textAlign === "end") return rect.right;
+      return rect.left;
+    };
+
+    if (lineRects.length === 1) {
+      const r = lineRects[0];
+      return [
+        {
+          text: full.trim(),
+          x: anchorX(r) - originRect.left,
+          y: r.top + r.height / 2 - originRect.top,
+        },
+      ];
+    }
+
+    const offsets = splitLineOffsets(textNode, full.length, lineRects.length);
+    let start = 0;
+    return lineRects.map((r, i) => {
+      const end = offsets[i] ?? full.length;
+      const text = full.slice(start, end).trim();
+      start = end;
+      return {
+        text,
+        x: anchorX(r) - originRect.left,
+        y: r.top + r.height / 2 - originRect.top,
+      };
+    });
+  }
+
+  function walk(el: Element): RawFigmaSvgNode | null {
+    const style = getComputedStyle(el);
+    if (!isVisible(el, style)) return null;
+
+    const rect = el.getBoundingClientRect();
+    const relRect: FigmaSvgRect = {
+      x: rect.left - originRect.left,
+      y: rect.top - originRect.top,
+      width: rect.width,
+      height: rect.height,
+    };
+    const name = el.getAttribute("data-agent-native-layer-name") || undefined;
+    const id = el.getAttribute("data-agent-native-node-id") || nextId();
+    const tag = el.tagName.toUpperCase();
+
+    const widths = [
+      Number.parseFloat(style.borderTopWidth) || 0,
+      Number.parseFloat(style.borderRightWidth) || 0,
+      Number.parseFloat(style.borderBottomWidth) || 0,
+      Number.parseFloat(style.borderLeftWidth) || 0,
+    ];
+    const colors = [
+      style.borderTopColor,
+      style.borderRightColor,
+      style.borderBottomColor,
+      style.borderLeftColor,
+    ];
+    const styles = [
+      style.borderTopStyle,
+      style.borderRightStyle,
+      style.borderBottomStyle,
+      style.borderLeftStyle,
+    ];
+    const borderNonUniform =
+      widths.some((w) => Math.abs(w - widths[0]) > 0.5) ||
+      colors.some((c) => c !== colors[0]) ||
+      styles.some((s) => s !== styles[0]);
+
+    const base = {
+      id,
+      name,
+      domTag: tag,
+      rect: relRect,
+      rotationDeg: rotationFromTransform(style.transform),
+      opacity: Number.parseFloat(style.opacity || "1"),
+      cornerRadiiRaw: {
+        tl: Number.parseFloat(style.borderTopLeftRadius) || 0,
+        tr: Number.parseFloat(style.borderTopRightRadius) || 0,
+        br: Number.parseFloat(style.borderBottomRightRadius) || 0,
+        bl: Number.parseFloat(style.borderBottomLeftRadius) || 0,
+      },
+      backgroundColor: style.backgroundColor,
+      backgroundImage: style.backgroundImage,
+      boxShadow: style.boxShadow,
+      borderWidthPx: styles[0] === "none" ? 0 : widths[0],
+      borderColor: colors[0],
+      borderStyle: styles[0],
+      borderNonUniform,
+      backdropFilter:
+        (style as CSSStyleDeclaration & { backdropFilter?: string })
+          .backdropFilter || "none",
+      isLeafText: false,
+      children: [] as RawFigmaSvgNode[],
+    };
+
+    if (tag === "VIDEO" || tag === "CANVAS" || tag === "IFRAME") {
+      return {
+        ...base,
+        rasterReason: `<${tag.toLowerCase()}> content has no SVG equivalent — rasterized via screenshot.`,
+      };
+    }
+    if (base.backdropFilter !== "none") {
+      return {
+        ...base,
+        rasterReason:
+          "backdrop-filter cannot be expressed in SVG — rasterized this element's region via screenshot.",
+      };
+    }
+
+    if (tag === "IMG") {
+      const img = el as HTMLImageElement;
+      return {
+        ...base,
+        imgSrc: img.currentSrc || img.src,
+        imgObjectFit: getComputedStyle(img).objectFit,
+      };
+    }
+
+    const lines = extractTextLines(el);
+    if (lines) {
+      return {
+        ...base,
+        isLeafText: true,
+        textLines: lines,
+        textStyle: {
+          fontFamily: style.fontFamily,
+          fontSizePx: Number.parseFloat(style.fontSize) || 16,
+          fontWeight: Number.parseInt(style.fontWeight, 10) || 400,
+          italic: style.fontStyle === "italic",
+          letterSpacingPx:
+            style.letterSpacing === "normal"
+              ? 0
+              : Number.parseFloat(style.letterSpacing) || 0,
+          color: style.color,
+          textAlign: style.textAlign,
+        },
+      };
+    }
+
+    const children: RawFigmaSvgNode[] = [];
+    for (const child of Array.from(el.children)) {
+      const childNode = walk(child);
+      if (childNode) children.push(childNode);
+    }
+    return { ...base, children };
+  }
+
+  const rootNode = walk(root);
+  if (!rootNode) return null;
+  return {
+    root: rootNode,
+    originOffset: { x: originRect.left, y: originRect.top },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration — renders the design's HTML in headless Chromium (same
+// launch/import pattern as take-design-screenshot.ts), walks the live DOM,
+// hydrates the result into a FigmaSvgNode tree, and serializes it to SVG.
+// ---------------------------------------------------------------------------
+
+export interface RenderFigmaSvgOptions {
+  html: string;
+  width: number;
+  height: number;
+  title?: string | null;
+  /** CSS selector to scope a subtree export (e.g. `[data-agent-native-node-id="..."]`). */
+  rootSelector?: string | null;
+  /** Fetch and inline http(s) image `src`/background-image URLs as data: URIs. */
+  embedImages?: boolean;
+}
+
+async function embedRemoteImages(node: FigmaSvgNode): Promise<void> {
+  const jobs: Array<Promise<void>> = [];
+
+  function visit(n: FigmaSvgNode) {
+    if (n.kind === "image" && n.image && /^https?:\/\//i.test(n.image.href)) {
+      jobs.push(
+        fetchAsDataUri(n.image.href).then((dataUri) => {
+          if (dataUri && n.image) n.image.href = dataUri;
+        }),
+      );
+    }
+    for (const fill of n.fills ?? []) {
+      if (fill.kind === "image" && /^https?:\/\//i.test(fill.href)) {
+        jobs.push(
+          fetchAsDataUri(fill.href).then((dataUri) => {
+            if (dataUri) fill.href = dataUri;
+          }),
+        );
+      }
+    }
+    for (const child of n.children ?? []) visit(child);
+  }
+  visit(node);
+  await Promise.all(jobs);
+}
+
+async function fetchAsDataUri(url: string): Promise<string | null> {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return null;
+    const contentType = res.headers.get("content-type") || "image/png";
+    const buffer = Buffer.from(await res.arrayBuffer());
+    return `data:${contentType};base64,${buffer.toString("base64")}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walks the RAW scene tree (before hydration) and, for every node flagged
+ * `rasterReason` (video/canvas/iframe/backdrop-blur), takes a real cropped
+ * screenshot of that element's exact bounds while the page is still live,
+ * setting `rasterHref` to a `data:image/png` URI. Runs while `page` is still
+ * open, since it needs the live rendered content — the same reason
+ * `take-design-screenshot.ts` keeps its browser open for the whole capture.
+ */
+async function rasterizeUnsupportedNodes(
+  page: import("@playwright/test").Page,
+  node: RawFigmaSvgNode,
+  originOffset: { x: number; y: number },
+): Promise<void> {
+  if (node.rasterReason && !node.rasterHref) {
+    const clip = {
+      x: Math.max(0, node.rect.x + originOffset.x),
+      y: Math.max(0, node.rect.y + originOffset.y),
+      width: Math.max(1, Math.round(node.rect.width)),
+      height: Math.max(1, Math.round(node.rect.height)),
+    };
+    try {
+      const png = await page.screenshot({ clip, type: "png" });
+      node.rasterHref = `data:image/png;base64,${png.toString("base64")}`;
+    } catch {
+      // Leave rasterHref unset — hydrateRawFigmaSvgNode falls back to an
+      // empty href, and the export report still names the node as
+      // rasterized (with its reason) so the caller knows what's missing.
+    }
+  }
+  for (const child of node.children) {
+    await rasterizeUnsupportedNodes(page, child, originOffset);
+  }
+}
+
+/**
+ * Renders `html` in headless Chromium, walks the live DOM to build a
+ * `FigmaSvgNode` scene, and serializes it into a genuinely vector SVG
+ * document via `buildFigmaSvgDocument`. Throws when no Chromium binary is
+ * available — callers should catch and fall back (mirrors
+ * `take-design-screenshot.ts`'s `chromiumUnavailableReason` pattern).
+ */
+export async function renderDesignToFigmaSvg(
+  options: RenderFigmaSvgOptions,
+): Promise<{ svg: string; report: FigmaSvgExportReport }> {
+  const playwright = await importPlaywright();
+  const browser = await launchChromium(playwright.chromium);
+  try {
+    const context = await browser.newContext({
+      viewport: { width: options.width, height: options.height },
+    });
+    const page = await context.newPage();
+    try {
+      await page.setContent(options.html, { waitUntil: "networkidle" });
+      await page.waitForTimeout(300); // let Alpine.js / CDN Tailwind JIT settle.
+
+      const scene = (await page.evaluate(
+        collectRawFigmaSvgScene,
+        options.rootSelector ?? null,
+      )) as RawFigmaSvgSceneResult | null;
+      if (!scene) {
+        throw new Error(
+          options.rootSelector
+            ? `No element matched rootSelector "${options.rootSelector}"`
+            : "Design screen has no renderable content",
+        );
+      }
+
+      // Capture a real cropped screenshot for every node the DOM walk
+      // flagged as unsupported (video/canvas/iframe/backdrop-blur), while
+      // the page is still live — this is the "rasterize instead of fight
+      // it" fallback the property-mapping matrix promises for those cases.
+      await rasterizeUnsupportedNodes(page, scene.root, scene.originOffset);
+
+      const root = hydrateRawFigmaSvgNode(scene.root);
+      if (options.embedImages) {
+        await embedRemoteImages(root);
+      }
+
+      return buildFigmaSvgDocument({
+        width: options.width,
+        height: options.height,
+        title: options.title,
+        root,
+      });
+    } finally {
+      await context.close().catch(() => {});
+    }
+  } finally {
+    await browser.close().catch(() => {});
+  }
+}
diff --git a/templates/design/server/lib/figma-clipboard-match.spec.ts b/templates/design/server/lib/figma-clipboard-match.spec.ts
new file mode 100644
index 0000000000..02d07ec710
--- /dev/null
+++ b/templates/design/server/lib/figma-clipboard-match.spec.ts
@@ -0,0 +1,175 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  buildFigmaNodeCandidates,
+  extractVisibleTexts,
+  matchFigmaClipboardNodes,
+  type FigmaNodeCandidate,
+} from "./figma-clipboard-match.js";
+
+describe("extractVisibleTexts", () => {
+  it("strips tags and returns distinct trimmed text lines", () => {
+    expect(
+      extractVisibleTexts(
+        "<div><span>Hero</span><p>Sign up today</p><span>Hero</span></div>",
+      ),
+    ).toEqual(["Hero", "Sign up today"]);
+  });
+
+  it("decodes common HTML entities", () => {
+    expect(extractVisibleTexts("<p>Terms &amp; Conditions</p>")).toEqual([
+      "Terms & Conditions",
+    ]);
+  });
+
+  it("drops script/style content and empty lines", () => {
+    expect(
+      extractVisibleTexts(
+        "<style>.a{color:red}</style><div>  </div><p>Real text</p><script>evil()</script>",
+      ),
+    ).toEqual(["Real text"]);
+  });
+
+  it("returns an empty array for empty/undefined input", () => {
+    expect(extractVisibleTexts("")).toEqual([]);
+    expect(extractVisibleTexts(undefined)).toEqual([]);
+    expect(extractVisibleTexts(null)).toEqual([]);
+  });
+});
+
+describe("buildFigmaNodeCandidates", () => {
+  it("collects one candidate per top-level frame across all pages, with direct-children text", () => {
+    const document = {
+      children: [
+        {
+          id: "page-1",
+          children: [
+            {
+              id: "1:1",
+              name: "Hero",
+              children: [{ id: "1:2", name: "Title", characters: "Welcome" }],
+            },
+          ],
+        },
+        {
+          id: "page-2",
+          children: [{ id: "2:1", name: "Footer", children: [] }],
+        },
+      ],
+    };
+    expect(buildFigmaNodeCandidates(document)).toEqual([
+      { id: "1:1", name: "Hero", texts: ["Welcome"] },
+      { id: "2:1", name: "Footer", texts: [] },
+    ]);
+  });
+
+  it("ignores frames with no id and tolerates a missing document", () => {
+    expect(buildFigmaNodeCandidates(undefined)).toEqual([]);
+    expect(
+      buildFigmaNodeCandidates({
+        children: [{ id: "page-1", children: [{ name: "No id" }] }],
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("matchFigmaClipboardNodes", () => {
+  const candidate = (
+    id: string,
+    name: string,
+    texts: string[] = [],
+  ): FigmaNodeCandidate => ({ id, name, texts });
+
+  it("matches a single candidate whose name appears verbatim in the clipboard text", () => {
+    const result = matchFigmaClipboardNodes(
+      [candidate("1:1", "Hero"), candidate("1:2", "Footer")],
+      ["Hero", "Sign up today"],
+    );
+    expect(result).toEqual({
+      status: "matched",
+      matches: [{ id: "1:1", name: "Hero", reason: "name" }],
+    });
+  });
+
+  it("matches multiple candidates for a multi-select copy (several frames named in the clipboard)", () => {
+    const result = matchFigmaClipboardNodes(
+      [
+        candidate("1:1", "Header"),
+        candidate("1:2", "Footer"),
+        candidate("1:3", "Sidebar"),
+      ],
+      ["Header", "Footer"],
+    );
+    expect(result.status).toBe("matched");
+    expect(result.matches.map((m) => m.id).sort()).toEqual(["1:1", "1:2"]);
+    expect(result.matches.every((m) => m.reason === "name")).toBe(true);
+  });
+
+  it("is case/whitespace-insensitive when matching names", () => {
+    const result = matchFigmaClipboardNodes(
+      [candidate("1:1", "  Hero Section  ")],
+      ["hero section"],
+    );
+    expect(result.status).toBe("matched");
+    expect(result.matches[0]!.id).toBe("1:1");
+  });
+
+  it("falls back to text-content matching when no candidate name matches", () => {
+    const result = matchFigmaClipboardNodes(
+      [
+        candidate("1:1", "Frame 12", ["Welcome back", "Sign in"]),
+        candidate("1:2", "Frame 13", ["Pricing", "$9/mo"]),
+      ],
+      ["Welcome back", "Sign in"],
+    );
+    expect(result).toEqual({
+      status: "matched",
+      matches: [{ id: "1:1", name: "Frame 12", reason: "text" }],
+    });
+  });
+
+  it("requires at least two distinct text overlaps before trusting a text-only match", () => {
+    const result = matchFigmaClipboardNodes(
+      [candidate("1:1", "Frame 12", ["Welcome back"])],
+      ["Welcome back"],
+    );
+    expect(result).toEqual({ status: "none", matches: [] });
+  });
+
+  it("is ambiguous when two candidates both clear the text-match bar", () => {
+    const result = matchFigmaClipboardNodes(
+      [
+        candidate("1:1", "Frame 12", ["Welcome back", "Sign in"]),
+        candidate("1:2", "Frame 13", ["Welcome back", "Sign in"]),
+      ],
+      ["Welcome back", "Sign in"],
+    );
+    expect(result).toEqual({ status: "ambiguous", matches: [] });
+  });
+
+  it("is ambiguous (not matched) when name matches exceed the multi-match cap", () => {
+    const many = Array.from({ length: 9 }, (_, i) =>
+      candidate(`1:${i}`, `Frame ${i}`),
+    );
+    const result = matchFigmaClipboardNodes(
+      many,
+      many.map((c) => c.name),
+    );
+    expect(result).toEqual({ status: "ambiguous", matches: [] });
+  });
+
+  it("returns none when nothing overlaps at all", () => {
+    const result = matchFigmaClipboardNodes(
+      [candidate("1:1", "Hero", ["Welcome"])],
+      ["Totally unrelated copy", "Nothing matches"],
+    );
+    expect(result).toEqual({ status: "none", matches: [] });
+  });
+
+  it("returns none for an empty candidate list", () => {
+    expect(matchFigmaClipboardNodes([], ["Hero"])).toEqual({
+      status: "none",
+      matches: [],
+    });
+  });
+});
diff --git a/templates/design/server/lib/figma-clipboard-match.ts b/templates/design/server/lib/figma-clipboard-match.ts
new file mode 100644
index 0000000000..5cdfdab24a
--- /dev/null
+++ b/templates/design/server/lib/figma-clipboard-match.ts
@@ -0,0 +1,196 @@
+/**
+ * Conservative matcher: figures out which top-level Figma frame(s) a clipboard
+ * paste corresponds to, without ever risking an unintended whole-file import.
+ *
+ * Why this exists: Figma's clipboard `figmeta` marker (see
+ * `app/lib/figma-clipboard.ts`) only carries a `fileKey` — it has no node ids,
+ * and the `pasteID` it does carry is server-side/ephemeral (not resolvable to
+ * a node through the public REST API). So a clipboard paste alone can't name
+ * an exact node the way a copied frame LINK can (`?node-id=...`). Instead we
+ * fetch the file's shallow structure (see `fetchFileStructure(fileKey, 3)` in
+ * `figma-node-import.ts`: pages -> top-level frames -> their direct children)
+ * and heuristically match it against the *visible* clipboard HTML fallback
+ * (frame/layer names and text layer contents tend to reappear as literal text
+ * in that fallback markup).
+ *
+ * This is deliberately conservative: pure name/text equality only, no fuzzy
+ * matching, and it only ever returns a `matched` result when the evidence is
+ * unambiguous. Anything else — `none` or `ambiguous` — must fall back to the
+ * legacy HTML-paste path (see `import-figma-clipboard.ts`) rather than guess
+ * at a node import, since importing the wrong node is worse than importing a
+ * lossy but honest HTML approximation.
+ */
+
+import type { FigmaFileDepthNode } from "./figma-node-import.js";
+
+export interface FigmaNodeCandidate {
+  id: string;
+  name: string;
+  /** Text layer `characters` found among this node's direct children. */
+  texts: string[];
+}
+
+export type FigmaClipboardMatchStatus = "matched" | "ambiguous" | "none";
+
+export interface FigmaClipboardMatch {
+  id: string;
+  name: string;
+  reason: "name" | "text";
+}
+
+export interface FigmaClipboardMatchResult {
+  status: FigmaClipboardMatchStatus;
+  matches: FigmaClipboardMatch[];
+}
+
+/** Caps a "multi-select copy" match so a huge/garbled name-match list still degrades to ambiguous. */
+const MAX_MULTI_MATCH = 8;
+/** Minimum distinct visible-text overlaps required before trusting a text-only match (no name match). */
+const MIN_TEXT_MATCHES = 2;
+
+function normalize(value: string): string {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+/**
+ * Extracts distinct non-empty visible text lines from clipboard fallback HTML
+ * (already stripped of the hidden figmeta/figbuffer markers by
+ * `parseVisibleClipboardHtml`). Deliberately simple: strip tags, split on the
+ * resulting line breaks, trim, dedupe — good enough for literal-text overlap
+ * matching without pulling in an HTML parser.
+ */
+export function extractVisibleTexts(html: string | undefined | null): string[] {
+  if (!html) return [];
+  const withoutTagContent = html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, "\n");
+  const decoded = withoutTagContent
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#0?39;/gi, "'");
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const rawLine of decoded.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || seen.has(line)) continue;
+    seen.add(line);
+    out.push(line);
+  }
+  return out;
+}
+
+function collectTextCharacters(node: FigmaFileDepthNode | undefined): string[] {
+  if (!node) return [];
+  const out: string[] = [];
+  const characters = (node as { characters?: unknown }).characters;
+  if (typeof characters === "string" && characters.trim()) out.push(characters);
+  for (const child of node.children ?? [])
+    out.push(...collectTextCharacters(child));
+  return out;
+}
+
+/**
+ * Builds match candidates from a `depth=3` file-structure fetch: one
+ * candidate per top-level frame across every page, each carrying its own
+ * name plus the visible text found among its (one level of) children.
+ * Intentionally scoped to top-level frames only — never deeper — so a match
+ * can only ever resolve to whole frames a user could plausibly have copied,
+ * not to arbitrary nested layers.
+ */
+export function buildFigmaNodeCandidates(
+  document: FigmaFileDepthNode | undefined,
+): FigmaNodeCandidate[] {
+  const candidates: FigmaNodeCandidate[] = [];
+  for (const page of document?.children ?? []) {
+    for (const frame of page.children ?? []) {
+      if (!frame?.id) continue;
+      candidates.push({
+        id: frame.id,
+        name: frame.name ?? "",
+        texts: collectTextCharacters(frame),
+      });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Decision rules (see module doc for the "why"):
+ *
+ * 1. Any candidate whose *name* exactly equals (case/whitespace-insensitive)
+ *    one of the clipboard's visible text lines is a "name match" — the
+ *    strongest signal, since a frame's name reappearing verbatim in the copy
+ *    is unlikely by chance.
+ *      - Exactly one name match -> matched (single frame copy).
+ *      - 2..MAX_MULTI_MATCH name matches -> matched, all of them (multi-select
+ *        copy of several named frames).
+ *      - More than MAX_MULTI_MATCH -> ambiguous (too many to trust).
+ * 2. No name match: fall back to counting distinct visible-text overlaps
+ *    between each candidate's own text layers and the clipboard text.
+ *      - Exactly one candidate reaches MIN_TEXT_MATCHES -> matched (text
+ *        match).
+ *      - Zero or 2+ candidates reach MIN_TEXT_MATCHES -> ambiguous/none.
+ * 3. No candidate clears either bar -> none.
+ */
+export function matchFigmaClipboardNodes(
+  candidates: FigmaNodeCandidate[],
+  clipboardTexts: string[],
+): FigmaClipboardMatchResult {
+  const clipboardTextSet = new Set(
+    clipboardTexts.map(normalize).filter((text) => text.length > 0),
+  );
+
+  const nameMatches = candidates.filter((candidate) =>
+    clipboardTextSet.has(normalize(candidate.name)),
+  );
+
+  if (nameMatches.length === 1) {
+    const [match] = nameMatches;
+    return {
+      status: "matched",
+      matches: [{ id: match!.id, name: match!.name, reason: "name" }],
+    };
+  }
+  if (nameMatches.length > 1) {
+    if (nameMatches.length > MAX_MULTI_MATCH) {
+      return { status: "ambiguous", matches: [] };
+    }
+    return {
+      status: "matched",
+      matches: nameMatches.map((match) => ({
+        id: match.id,
+        name: match.name,
+        reason: "name" as const,
+      })),
+    };
+  }
+
+  const textScores = candidates.map((candidate) => {
+    const matchedTexts = new Set(
+      candidate.texts
+        .map(normalize)
+        .filter((text) => text.length > 0 && clipboardTextSet.has(text)),
+    );
+    return { candidate, score: matchedTexts.size };
+  });
+  const strongTextMatches = textScores.filter(
+    (entry) => entry.score >= MIN_TEXT_MATCHES,
+  );
+
+  if (strongTextMatches.length === 1) {
+    const { candidate } = strongTextMatches[0]!;
+    return {
+      status: "matched",
+      matches: [{ id: candidate.id, name: candidate.name, reason: "text" }],
+    };
+  }
+  if (strongTextMatches.length > 1) {
+    return { status: "ambiguous", matches: [] };
+  }
+
+  return { status: "none", matches: [] };
+}
diff --git a/templates/design/server/lib/figma-node-import.ts b/templates/design/server/lib/figma-node-import.ts
new file mode 100644
index 0000000000..0eb97832fa
--- /dev/null
+++ b/templates/design/server/lib/figma-node-import.ts
@@ -0,0 +1,311 @@
+/**
+ * Shared Figma REST fetch -> map -> screen-file core.
+ *
+ * Extracted from `import-figma-frame.ts` so a second import path (paste-driven
+ * node resolution, see `figma-clipboard-match.ts` / `import-figma-clipboard.ts`)
+ * can reuse the exact same fetch/map logic instead of re-implementing it.
+ * `import-figma-frame.ts` still owns the action interface and result shape; this
+ * module only owns the parts that talk to the Figma REST API and turn node JSON
+ * into `ImportedDesignFile` records.
+ *
+ * Pure/network-boundary split mirrors `figma-node-to-html.ts`'s own doc comment:
+ * this module fetches, `figma-node-to-html.ts` maps (pure, synchronous).
+ */
+
+import {
+  collectFallbackNodeIds,
+  collectImageFillRefs,
+  mapFigmaNodeToHtml,
+  type FidelityEntry,
+  type FidelityLevel,
+  type FigmaNode,
+} from "./figma-node-to-html.js";
+import {
+  normalizeImportedHtmlDocument,
+  type ImportedDesignFile,
+} from "./import-design-files.js";
+import { executeProviderApiRequest } from "./provider-api.js";
+
+/**
+ * Figma's box model treats a frame's declared width/height as the OUTER
+ * (border-box-equivalent) size: padding eats into the interior without
+ * growing the frame's footprint. The browser default is `box-sizing:
+ * content-box`, so `figma-node-to-html.ts`'s per-node inline `width`/`height`
+ * (mapped 1:1 from `absoluteBoundingBox`) plus any padding on the same node
+ * renders LARGER than Figma intends by exactly the padding amount, and the
+ * default UA `body { margin: 8px }` additionally offsets the whole imported
+ * screen away from (0,0). Both together produce visible horizontal/vertical
+ * overflow and a diagonal pixel offset relative to Figma's own render for any
+ * auto-layout frame with padding (i.e. most real designs). Scope the reset to
+ * this Figma-import pipeline only — the shared `normalizeImportedHtmlDocument`
+ * is also used by non-Figma import paths that must not be affected.
+ */
+function withFigmaBoxModelReset(html: string): string {
+  return `<style>*,*::before,*::after{box-sizing:border-box;}body{margin:0;}</style>\n${html}`;
+}
+
+type FigmaProviderEnvelope = {
+  response?: {
+    ok?: boolean;
+    status?: number;
+    statusText?: string;
+    json?: unknown;
+    text?: string;
+  };
+};
+
+export function providerJson(envelope: unknown, label: string): unknown {
+  const response = (envelope as FigmaProviderEnvelope | null)?.response;
+  if (!response) throw new Error(`Figma ${label} response was empty.`);
+  if (response.ok === false) {
+    const detail =
+      (typeof response.text === "string" && response.text.trim()) ||
+      response.statusText ||
+      `HTTP ${response.status ?? "error"}`;
+    throw new Error(`Figma ${label} request failed: ${detail}`);
+  }
+  return response.json;
+}
+
+export async function figmaGet(path: string, query?: Record<string, unknown>) {
+  return executeProviderApiRequest({
+    provider: "figma",
+    method: "GET",
+    path,
+    query,
+    maxBytes: 8 * 1024 * 1024,
+  });
+}
+
+export interface FigmaFileDepthNode {
+  id?: string;
+  name?: string;
+  type?: string;
+  children?: FigmaFileDepthNode[];
+  characters?: string;
+}
+
+/**
+ * Fetches the file's page/frame structure at a given `depth` (cheap: no
+ * geometry, just ids/names/types/children/characters). `depth=2` returns
+ * pages + their direct children (top-level frames) — used to find a default
+ * frame when no node-id is given. `depth=3` additionally returns each top
+ * frame's direct children — used by the clipboard matcher to read visible
+ * text for heuristic matching.
+ */
+export async function fetchFileStructure(
+  fileKey: string,
+  depth: number,
+): Promise<FigmaFileDepthNode> {
+  const envelope = await figmaGet(`/files/${fileKey}`, { depth });
+  const json = providerJson(envelope, "file") as {
+    document?: FigmaFileDepthNode;
+  };
+  return json.document ?? {};
+}
+
+export async function resolveTargetNodeId(
+  fileKey: string,
+  nodeId: string | null,
+): Promise<string> {
+  if (nodeId) return nodeId;
+
+  // No node-id given: find the file's first top-level frame under its first
+  // page. depth=2 keeps this cheap (pages + their direct children only, no
+  // deep geometry) instead of pulling the entire document tree.
+  const document = await fetchFileStructure(fileKey, 2);
+  const firstPage = document.children?.[0];
+  const firstFrame = firstPage?.children?.find((child) => Boolean(child?.id));
+  if (!firstFrame?.id) {
+    throw new Error(
+      "Could not find a frame to import. Pass a specific node-id or a Figma frame URL with ?node-id=.",
+    );
+  }
+  return firstFrame.id;
+}
+
+/**
+ * Fetches one or more nodes' full document JSON (with vector path geometry)
+ * in a single request — the Figma nodes endpoint accepts a comma-joined
+ * `ids` list. Throws immediately on the first node id that is missing,
+ * errored, or has no document payload, naming that specific node id.
+ */
+export async function fetchFigmaNodes(
+  fileKey: string,
+  nodeIds: string[],
+): Promise<Record<string, FigmaNode>> {
+  if (nodeIds.length === 0) return {};
+  const envelope = await figmaGet(`/files/${fileKey}/nodes`, {
+    ids: nodeIds.join(","),
+    geometry: "paths",
+  });
+  const json = providerJson(envelope, "nodes") as {
+    nodes?: Record<string, { document?: FigmaNode; err?: string } | undefined>;
+  };
+  const result: Record<string, FigmaNode> = {};
+  for (const nodeId of nodeIds) {
+    const entry = json.nodes?.[nodeId];
+    if (!entry) {
+      throw new Error(
+        `Figma node ${nodeId} was not found in file ${fileKey}. Check the node-id and that the token has access to this file.`,
+      );
+    }
+    if (entry.err) {
+      throw new Error(
+        `Figma returned an error for node ${nodeId}: ${entry.err}`,
+      );
+    }
+    if (!entry.document) {
+      throw new Error(`Figma node ${nodeId} had no document payload.`);
+    }
+    result[nodeId] = entry.document;
+  }
+  return result;
+}
+
+export async function fetchFigmaNode(
+  fileKey: string,
+  nodeId: string,
+): Promise<FigmaNode> {
+  const nodes = await fetchFigmaNodes(fileKey, [nodeId]);
+  return nodes[nodeId]!;
+}
+
+async function fetchFallbackImageUrls(
+  fileKey: string,
+  nodeIds: string[],
+): Promise<Record<string, string>> {
+  if (nodeIds.length === 0) return {};
+  const envelope = await figmaGet(`/images/${fileKey}`, {
+    ids: nodeIds.join(","),
+    format: "png",
+    scale: 2,
+  });
+  const json = providerJson(envelope, "images") as {
+    images?: Record<string, string | null | undefined>;
+  };
+  const result: Record<string, string> = {};
+  for (const [id, url] of Object.entries(json.images ?? {})) {
+    if (typeof url === "string" && url) result[id] = url;
+  }
+  return result;
+}
+
+async function fetchImageFillUrls(
+  fileKey: string,
+  imageRefs: string[],
+): Promise<Record<string, string>> {
+  if (imageRefs.length === 0) return {};
+  const envelope = await figmaGet(`/files/${fileKey}/images`);
+  const json = providerJson(envelope, "image fills") as {
+    images?: Record<string, string | null | undefined>;
+  };
+  const result: Record<string, string> = {};
+  for (const ref of imageRefs) {
+    const url = json.images?.[ref];
+    if (typeof url === "string" && url) result[ref] = url;
+  }
+  return result;
+}
+
+export function sanitizeTitle(
+  name: string | undefined,
+  fallback: string,
+): string {
+  const trimmed = name?.trim();
+  if (!trimmed) return fallback;
+  return (
+    trimmed
+      .replace(/[^\w. -]+/g, "-")
+      .replace(/\s+/g, "-")
+      .slice(0, 80) || fallback
+  );
+}
+
+export function summarizeFidelity(entries: FidelityEntry[]) {
+  const byLevel = (level: FidelityLevel) =>
+    entries
+      .filter((entry) => entry.level === level)
+      .map((entry) => ({
+        nodeId: entry.nodeId,
+        nodeName: entry.nodeName,
+        nodeType: entry.nodeType,
+        notes: entry.notes,
+      }));
+  return {
+    exactCount: entries.filter((entry) => entry.level === "exact").length,
+    approximated: byLevel("approximated"),
+    imageFallbacks: byLevel("image-fallback"),
+  };
+}
+
+/**
+ * Fetches whatever PNG fallback / image-fill URLs the given nodes need (union
+ * across all of them, one request each instead of one per node) and maps
+ * every node to an `ImportedDesignFile`. Cascading x-offset placement mirrors
+ * `saveImportedDesignFiles`' own frame layout so multiple imported nodes don't
+ * land stacked on top of each other before the canvas placement pass runs.
+ */
+export async function buildScreenFilesFromFigmaNodes(
+  fileKey: string,
+  nodesById: Record<string, FigmaNode>,
+  options: {
+    source?: (nodeId: string, node: FigmaNode) => Record<string, unknown>;
+    sourceLabel?: (nodeId: string, node: FigmaNode) => string;
+  } = {},
+): Promise<{ files: ImportedDesignFile[]; fidelityEntries: FidelityEntry[] }> {
+  const entries = Object.entries(nodesById);
+  const fallbackNodeIds = new Set<string>();
+  const imageFillRefs = new Set<string>();
+  for (const [, node] of entries) {
+    for (const id of collectFallbackNodeIds(node)) fallbackNodeIds.add(id);
+    for (const ref of collectImageFillRefs(node)) imageFillRefs.add(ref);
+  }
+
+  const [fallbackImageUrls, imageFillUrls] = await Promise.all([
+    fetchFallbackImageUrls(fileKey, Array.from(fallbackNodeIds)),
+    fetchImageFillUrls(fileKey, Array.from(imageFillRefs)),
+  ]);
+
+  const files: ImportedDesignFile[] = [];
+  const fidelityEntries: FidelityEntry[] = [];
+
+  for (const [nodeId, node] of entries) {
+    const { html, fidelity } = mapFigmaNodeToHtml(node, {
+      fallbackImageUrls,
+      imageFillUrls,
+    });
+    fidelityEntries.push(...fidelity.entries);
+
+    const title = sanitizeTitle(
+      node.name,
+      `figma-${nodeId.replace(/[:;]/g, "-")}`,
+    );
+    const sourceLabel =
+      options.sourceLabel?.(nodeId, node) ??
+      `Figma file ${fileKey}, node ${nodeId}`;
+    const content = normalizeImportedHtmlDocument(
+      withFigmaBoxModelReset(html || "<div></div>"),
+      sourceLabel,
+    );
+    files.push({
+      filename: `${title}.html`,
+      fileType: "html",
+      content,
+      source: {
+        sourceType: "figma-import",
+        figmaFileKey: fileKey,
+        figmaNodeId: nodeId,
+        figmaNodeName: node.name ?? null,
+        ...options.source?.(nodeId, node),
+      },
+      preferredFrame: {
+        title: node.name,
+        width: node.absoluteBoundingBox?.width,
+        height: node.absoluteBoundingBox?.height,
+      },
+    });
+  }
+
+  return { files, fidelityEntries };
+}
diff --git a/templates/design/server/lib/figma-node-to-html.test.ts b/templates/design/server/lib/figma-node-to-html.test.ts
new file mode 100644
index 0000000000..34958168f2
--- /dev/null
+++ b/templates/design/server/lib/figma-node-to-html.test.ts
@@ -0,0 +1,625 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  collectFallbackNodeIds,
+  collectImageFillRefs,
+  gradientAngleDegrees,
+  mapFigmaNodeToHtml,
+  type FigmaNode,
+  type FigmaPaint,
+} from "./figma-node-to-html";
+
+function box(x: number, y: number, width: number, height: number) {
+  return { x, y, width, height };
+}
+
+describe("gradientAngleDegrees", () => {
+  it("resolves the identity left-to-right handles to 90deg (CSS 'to right')", () => {
+    const paint: FigmaPaint = {
+      type: "GRADIENT_LINEAR",
+      gradientHandlePositions: [
+        { x: 0, y: 0.5 },
+        { x: 1, y: 0.5 },
+        { x: 1, y: 0 },
+      ],
+      gradientStops: [],
+    };
+    expect(gradientAngleDegrees(paint, { width: 200, height: 100 })).toBe(90);
+  });
+
+  it("resolves top-to-bottom handles to 180deg (CSS 'to bottom')", () => {
+    const paint: FigmaPaint = {
+      type: "GRADIENT_LINEAR",
+      gradientHandlePositions: [
+        { x: 0.5, y: 0 },
+        { x: 0.5, y: 1 },
+        { x: 1, y: 0 },
+      ],
+      gradientStops: [],
+    };
+    expect(gradientAngleDegrees(paint, { width: 200, height: 100 })).toBe(180);
+  });
+
+  it("resolves a top-left-to-bottom-right diagonal on a square box to 135deg", () => {
+    const paint: FigmaPaint = {
+      type: "GRADIENT_LINEAR",
+      gradientHandlePositions: [
+        { x: 0, y: 0 },
+        { x: 1, y: 1 },
+        { x: 1, y: 0 },
+      ],
+      gradientStops: [],
+    };
+    expect(gradientAngleDegrees(paint, { width: 100, height: 100 })).toBe(135);
+  });
+
+  it("corrects for a non-square box instead of using the raw normalized angle", () => {
+    // A tall, narrow box: the normalized diagonal (0,0)->(1,1) is NOT 45deg
+    // in real pixel space here, so the derived CSS angle must differ from
+    // the naive 135deg square-box answer.
+    const paint: FigmaPaint = {
+      type: "GRADIENT_LINEAR",
+      gradientHandlePositions: [
+        { x: 0, y: 0 },
+        { x: 1, y: 1 },
+        { x: 1, y: 0 },
+      ],
+      gradientStops: [],
+    };
+    const angle = gradientAngleDegrees(paint, { width: 50, height: 200 });
+    expect(angle).not.toBe(135);
+    // dx=50, dy=200 -> atan2(200,50) ~= 75.96deg -> +90 ~= 165.96deg
+    expect(angle).toBeCloseTo(165.96, 1);
+  });
+
+  it("returns null when gradientHandlePositions is missing", () => {
+    expect(
+      gradientAngleDegrees(
+        { type: "GRADIENT_LINEAR" },
+        { width: 10, height: 10 },
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("mapFigmaNodeToHtml - basic shapes", () => {
+  it("maps a solid-filled rectangle with exact position/size and per-corner radii", () => {
+    const root: FigmaNode = {
+      id: "1:1",
+      name: "Card",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 300, 200),
+      children: [
+        {
+          id: "1:2",
+          name: "Rect",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(20, 30, 100, 50),
+          fills: [{ type: "SOLID", color: { r: 1, g: 0, b: 0, a: 1 } }],
+          rectangleCornerRadii: [4, 8, 12, 16],
+        },
+      ],
+    };
+    const { html, fidelity } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("left: 20px; top: 30px; width: 100px; height: 50px");
+    expect(html).toContain("background-color: rgba(255, 0, 0, 1)");
+    expect(html).toContain("border-radius: 4px 8px 12px 16px");
+    expect(fidelity.summary.imageFallback).toBe(0);
+    expect(fidelity.entries.find((e) => e.nodeId === "1:2")?.level).toBe(
+      "exact",
+    );
+  });
+
+  it("maps an ellipse to border-radius: 50%", () => {
+    const root: FigmaNode = {
+      id: "1:1",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [
+        {
+          id: "1:3",
+          type: "ELLIPSE",
+          absoluteBoundingBox: box(0, 0, 40, 40),
+          fills: [{ type: "SOLID", color: { r: 0, g: 0, b: 1, a: 1 } }],
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("border-radius: 50%");
+  });
+});
+
+describe("mapFigmaNodeToHtml - strokes", () => {
+  const baseNode = (strokeAlign: FigmaNode["strokeAlign"]): FigmaNode => ({
+    id: "2:1",
+    type: "RECTANGLE",
+    absoluteBoundingBox: box(0, 0, 50, 50),
+    strokes: [{ type: "SOLID", color: { r: 0, g: 0, b: 0, a: 1 } }],
+    strokeWeight: 4,
+    strokeAlign,
+  });
+
+  it("renders CENTER stroke as outline with a negative half-weight offset", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [baseNode("CENTER")],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("outline: 4px solid rgba(0, 0, 0, 1)");
+    expect(html).toContain("outline-offset: -2px");
+  });
+
+  it("renders INSIDE stroke as an inset box-shadow", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [baseNode("INSIDE")],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("box-shadow: inset 0 0 0 4px rgba(0, 0, 0, 1)");
+  });
+
+  it("renders OUTSIDE stroke as an outline with zero offset", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [baseNode("OUTSIDE")],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("outline: 4px solid rgba(0, 0, 0, 1)");
+    expect(html).toContain("outline-offset: 0px");
+  });
+
+  it("renders per-side stroke weights as per-side borders and marks non-INSIDE as approximated", () => {
+    const node: FigmaNode = {
+      id: "2:2",
+      type: "RECTANGLE",
+      absoluteBoundingBox: box(0, 0, 50, 50),
+      strokes: [{ type: "SOLID", color: { r: 1, g: 1, b: 1, a: 1 } }],
+      strokeAlign: "CENTER",
+      individualStrokeWeights: { top: 1, right: 2, bottom: 3, left: 4 },
+    };
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [node],
+    };
+    const { html, fidelity } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("border-top: 1px solid");
+    expect(html).toContain("border-right: 2px solid");
+    expect(html).toContain("border-bottom: 3px solid");
+    expect(html).toContain("border-left: 4px solid");
+    expect(fidelity.entries.find((e) => e.nodeId === "2:2")?.level).toBe(
+      "approximated",
+    );
+  });
+});
+
+describe("mapFigmaNodeToHtml - text", () => {
+  it("resolves lineHeightPercentFontSize to an exact px value", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 200, 100),
+      children: [
+        {
+          id: "3:1",
+          type: "TEXT",
+          absoluteBoundingBox: box(0, 0, 200, 40),
+          characters: "Hello",
+          style: {
+            fontFamily: "Inter",
+            fontSize: 20,
+            fontWeight: 600,
+            lineHeightPercentFontSize: 150,
+            letterSpacing: 0.5,
+            textCase: "UPPER",
+            textDecoration: "UNDERLINE",
+            textAlignHorizontal: "CENTER",
+          },
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    // 20 * 150 / 100 = 30px
+    expect(html).toContain("line-height: 30px");
+    expect(html).toContain("letter-spacing: 0.5px");
+    expect(html).toContain("text-transform: uppercase");
+    expect(html).toContain("text-decoration: underline");
+    expect(html).toContain("text-align: center");
+    expect(html).toContain("font-weight: 600");
+    expect(html).toContain(">Hello<");
+  });
+
+  it("uses lineHeightPx directly when lineHeightUnit is PIXELS", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 200, 100),
+      children: [
+        {
+          id: "3:2",
+          type: "TEXT",
+          absoluteBoundingBox: box(0, 0, 200, 40),
+          characters: "Fixed",
+          style: {
+            fontFamily: "Inter",
+            fontSize: 16,
+            lineHeightPx: 24,
+            lineHeightUnit: "PIXELS",
+          },
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("line-height: 24px");
+  });
+});
+
+describe("mapFigmaNodeToHtml - auto layout", () => {
+  it("maps layoutMode/itemSpacing/padding/alignment to flexbox", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 400, 100),
+      layoutMode: "HORIZONTAL",
+      primaryAxisAlignItems: "SPACE_BETWEEN",
+      counterAxisAlignItems: "CENTER",
+      itemSpacing: 16,
+      paddingLeft: 8,
+      paddingRight: 8,
+      paddingTop: 4,
+      paddingBottom: 4,
+      children: [
+        {
+          id: "4:1",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(8, 4, 50, 92),
+          layoutSizingHorizontal: "FIXED",
+          fills: [{ type: "SOLID", color: { r: 0, g: 1, b: 0, a: 1 } }],
+        },
+        {
+          id: "4:2",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(74, 4, 50, 92),
+          layoutSizingHorizontal: "FILL",
+          fills: [{ type: "SOLID", color: { r: 0, g: 0, b: 1, a: 1 } }],
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("display: flex");
+    expect(html).toContain("flex-direction: row");
+    expect(html).toContain("justify-content: space-between");
+    expect(html).toContain("align-items: center");
+    expect(html).toContain("column-gap: 16px");
+    expect(html).toContain("padding: 4px 8px 4px 8px");
+    // Auto-layout children are flex items: no manual left/top.
+    expect(html).not.toMatch(/data-figma-node-id="4:1"[^>]*left:/);
+    // FILL sizing child grows along the main axis.
+    expect(html).toContain("flex-grow: 1");
+  });
+
+  it("maps horizontal FILL sizing to align-self: stretch (not flex-grow) under a VERTICAL (column) parent", () => {
+    // Regression test: a column auto-layout frame's main axis is vertical, so
+    // a child with layoutSizingHorizontal: "FILL" wants to stretch across the
+    // cross axis (align-self: stretch), not grow along the main axis
+    // (flex-grow/flex-basis). The old implementation ignored the parent's
+    // layoutMode and always mapped horizontal-FILL to flex-grow, which left
+    // `width: auto` with no stretch on column children -- they sized to
+    // content and overflowed the frame instead of filling its width.
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 400, 300),
+      layoutMode: "VERTICAL",
+      itemSpacing: 16,
+      paddingLeft: 24,
+      paddingRight: 24,
+      paddingTop: 24,
+      paddingBottom: 24,
+      children: [
+        {
+          id: "1:3",
+          type: "TEXT",
+          absoluteBoundingBox: box(24, 24, 352, 24),
+          layoutSizingHorizontal: "FILL",
+          style: { fontFamily: "Inter", fontSize: 20 },
+          characters: "Heading",
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("flex-direction: column");
+    expect(html).toContain("align-self: stretch");
+    expect(html).not.toContain("flex-grow: 1");
+    expect(html).not.toContain("flex-basis: 0%");
+  });
+
+  it("still maps vertical FILL sizing to flex-grow under a VERTICAL (column) parent", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 400, 300),
+      layoutMode: "VERTICAL",
+      children: [
+        {
+          id: "4:1",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(0, 0, 352, 100),
+          layoutSizingVertical: "FILL",
+          fills: [{ type: "SOLID", color: { r: 0, g: 0, b: 1, a: 1 } }],
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    // Vertical FILL under a column parent grows along the (vertical) main
+    // axis.
+    expect(html).toContain("flex-grow: 1");
+    expect(html).toContain("flex-basis: 0%");
+    expect(html).not.toContain("align-self: stretch");
+  });
+});
+
+describe("mapFigmaNodeToHtml - fills layering", () => {
+  it("reverses fill stack order so the topmost Figma fill is the topmost CSS layer", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [
+        {
+          id: "5:1",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(0, 0, 100, 100),
+          fills: [
+            { type: "SOLID", color: { r: 1, g: 0, b: 0, a: 1 } }, // bottom
+            {
+              type: "GRADIENT_LINEAR",
+              gradientHandlePositions: [
+                { x: 0, y: 0.5 },
+                { x: 1, y: 0.5 },
+                { x: 1, y: 0 },
+              ],
+              gradientStops: [
+                { position: 0, color: { r: 0, g: 0, b: 0, a: 1 } },
+                { position: 1, color: { r: 1, g: 1, b: 1, a: 1 } },
+              ],
+            }, // top
+          ],
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    // The gradient (top layer in Figma) must be the first background-image
+    // value, and the solid becomes the plain background-color underneath.
+    expect(html).toContain("background-image: linear-gradient(90deg,");
+    expect(html).toContain("background-color: rgba(255, 0, 0, 1)");
+  });
+
+  it("resolves an IMAGE fill via the provided imageFillUrls map and scale mode", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [
+        {
+          id: "5:2",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(0, 0, 100, 100),
+          fills: [{ type: "IMAGE", imageRef: "hash-1", scaleMode: "FILL" }],
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root, {
+      imageFillUrls: { "hash-1": "https://example.com/img.png" },
+    });
+    // The rendered `style="..."` attribute HTML-escapes embedded quotes (the
+    // CSS `url("...")` quoting is legitimate CSS but would otherwise
+    // prematurely terminate the surrounding double-quoted HTML attribute --
+    // see the styleAttr() doc comment). A real browser parses `&quot;` back
+    // to `"` before CSS parsing, so this remains a valid quoted url().
+    expect(html).toContain("url(&quot;https://example.com/img.png&quot;)");
+    expect(html).toContain("background-size: cover");
+  });
+
+  it('escapes embedded double quotes in the style attribute so a font-family value like "Inter" doesn\'t truncate the attribute (regression: silently dropped every style after font-family)', () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 400, 300),
+      children: [
+        {
+          id: "1:3",
+          type: "TEXT",
+          absoluteBoundingBox: box(0, 0, 200, 24),
+          style: { fontFamily: "Inter", fontSize: 20 },
+          characters: "Heading",
+        },
+      ],
+    };
+    const { html } = mapFigmaNodeToHtml(root);
+    // The style attribute must not contain a bare, unescaped `"` -- every
+    // quote inside the attribute value has to be `&quot;`.
+    const styleAttrMatch = html.match(/style="([^"]*(?:&quot;[^"]*)*)"/g);
+    expect(styleAttrMatch).not.toBeNull();
+    // Every style="..." attribute's raw content is `&quot;`-escaped, not a
+    // literal quote -- if font-family's `"Inter"` leaked through unescaped,
+    // the regex above would fail to capture the whole attribute (it would
+    // terminate early) and the assertion below would catch the literal `"`.
+    expect(html).toContain("font-family: &quot;Inter&quot;, sans-serif");
+    expect(html).not.toMatch(/style="[^"]*font-family: "Inter"/);
+    // The properties declared AFTER font-family in object-key order must
+    // still be present and inside the same attribute -- this is exactly
+    // what silently disappeared before the fix.
+    expect(html).toContain("font-size: 20px");
+    expect(html).toContain("display: flex");
+  });
+});
+
+describe("mapFigmaNodeToHtml - effects and blend modes", () => {
+  it("maps DROP_SHADOW to box-shadow and marks LAYER_BLUR as approximated", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [
+        {
+          id: "6:1",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(0, 0, 50, 50),
+          effects: [
+            {
+              type: "DROP_SHADOW",
+              offset: { x: 2, y: 4 },
+              radius: 8,
+              spread: 1,
+              color: { r: 0, g: 0, b: 0, a: 0.5 },
+            },
+            { type: "LAYER_BLUR", radius: 6 },
+          ],
+        },
+      ],
+    };
+    const { html, fidelity } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("box-shadow: 2px 4px 8px 1px rgba(0, 0, 0, 0.5)");
+    expect(html).toContain("filter: blur(6px)");
+    const entry = fidelity.entries.find((e) => e.nodeId === "6:1");
+    expect(entry?.level).toBe("approximated");
+  });
+
+  it("maps a CSS-supported blend mode exactly and a Figma-only mode to its closest fallback", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [
+        {
+          id: "7:1",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(0, 0, 50, 50),
+          blendMode: "MULTIPLY",
+        },
+        {
+          id: "7:2",
+          type: "RECTANGLE",
+          absoluteBoundingBox: box(50, 0, 50, 50),
+          blendMode: "LINEAR_DODGE",
+        },
+      ],
+    };
+    const { html, fidelity } = mapFigmaNodeToHtml(root);
+    expect(html).toContain("mix-blend-mode: multiply");
+    expect(html).toContain("mix-blend-mode: plus-lighter");
+    expect(fidelity.entries.find((e) => e.nodeId === "7:2")?.level).toBe(
+      "approximated",
+    );
+  });
+});
+
+describe("mapFigmaNodeToHtml - image fallback", () => {
+  it("renders an unsupported node type (VECTOR) as an <img> using the fallback image URL", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [
+        {
+          id: "8:1",
+          name: "Icon",
+          type: "VECTOR",
+          absoluteBoundingBox: box(10, 10, 24, 24),
+        },
+      ],
+    };
+    const { html, fidelity } = mapFigmaNodeToHtml(root, {
+      fallbackImageUrls: { "8:1": "https://example.com/render.png" },
+    });
+    expect(html).toContain("<img");
+    expect(html).toContain('src="https://example.com/render.png"');
+    expect(html).toContain("left: 10px; top: 10px; width: 24px; height: 24px");
+    expect(fidelity.entries.find((e) => e.nodeId === "8:1")?.level).toBe(
+      "image-fallback",
+    );
+  });
+
+  it("renders nothing (and records image-fallback) when no fallback URL is available", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      absoluteBoundingBox: box(0, 0, 100, 100),
+      children: [
+        {
+          id: "8:2",
+          type: "BOOLEAN_OPERATION",
+          absoluteBoundingBox: box(0, 0, 10, 10),
+        },
+      ],
+    };
+    const { html, fidelity } = mapFigmaNodeToHtml(root);
+    expect(html).not.toContain("<img");
+    expect(fidelity.entries.find((e) => e.nodeId === "8:2")?.level).toBe(
+      "image-fallback",
+    );
+  });
+});
+
+describe("collectFallbackNodeIds", () => {
+  it("collects ids for vector networks, boolean ops, and unsupported types without recursing into them", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      children: [
+        {
+          id: "v1",
+          type: "VECTOR",
+          children: [{ id: "should-not-appear", type: "RECTANGLE" }],
+        },
+        { id: "b1", type: "BOOLEAN_OPERATION" },
+        {
+          id: "f1",
+          type: "FRAME",
+          children: [{ id: "r1", type: "RECTANGLE" }],
+        },
+      ],
+    };
+    expect(collectFallbackNodeIds(root)).toEqual(["v1", "b1"]);
+  });
+
+  it("skips invisible nodes", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      children: [{ id: "v1", type: "VECTOR", visible: false }],
+    };
+    expect(collectFallbackNodeIds(root)).toEqual([]);
+  });
+});
+
+describe("collectImageFillRefs", () => {
+  it("collects distinct imageRefs from fills and strokes across the tree", () => {
+    const root: FigmaNode = {
+      id: "root",
+      type: "FRAME",
+      children: [
+        {
+          id: "n1",
+          type: "RECTANGLE",
+          fills: [{ type: "IMAGE", imageRef: "hash-a" }],
+        },
+        {
+          id: "n2",
+          type: "RECTANGLE",
+          fills: [{ type: "IMAGE", imageRef: "hash-a" }],
+          strokes: [{ type: "IMAGE", imageRef: "hash-b" }],
+        },
+      ],
+    };
+    expect(collectImageFillRefs(root).sort()).toEqual(["hash-a", "hash-b"]);
+  });
+});
diff --git a/templates/design/server/lib/figma-node-to-html.ts b/templates/design/server/lib/figma-node-to-html.ts
new file mode 100644
index 0000000000..d44668496a
--- /dev/null
+++ b/templates/design/server/lib/figma-node-to-html.ts
@@ -0,0 +1,1334 @@
+/**
+ * Figma node JSON -> HTML mapper.
+ *
+ * Input is the `document` subtree returned by
+ * `GET /v1/files/:fileKey/nodes?ids=...&geometry=paths` (or the file's root
+ * `document` node). Output is a self-contained HTML fragment using absolute
+ * positioning + inline styles, matching Figma's own canvas model 1:1 rather
+ * than reconstructing a semantic/Tailwind layout — the goal is pixel fidelity
+ * for an imported snapshot, not idiomatic hand-authored markup.
+ *
+ * This module is pure and synchronous: it never calls the network. The
+ * caller (an action) is responsible for:
+ *   1. Fetching the node JSON from the Figma REST API.
+ *   2. Calling `collectFallbackNodeIds` / `collectImageFillRefs` to find out
+ *      which nodes need a rendered PNG fallback and which image fills need
+ *      resolved URLs.
+ *   3. Fetching those via `/v1/images/:fileKey` (fallback renders) and
+ *      `/v1/files/:fileKey/images` (fill ref -> URL map).
+ *   4. Calling `mapFigmaNodeToHtml` with the resulting maps.
+ *
+ * ## Pixel-perfect property coverage
+ *
+ * | Property                                   | Fidelity      | Notes |
+ * | ------------------------------------------- | ------------- | ----- |
+ * | Position/size (absoluteBoundingBox)         | exact         | frame-relative |
+ * | Auto-layout (flex*)                         | exact         | Figma auto-layout IS flexbox |
+ * | Text font/size/weight/case/decoration/align | exact         | |
+ * | Line-height (px vs percent-of-font-size)    | exact         | resolved to px |
+ * | Letter-spacing                              | exact         | already px in REST API |
+ * | Solid fills                                 | exact         | |
+ * | Gradient fills (angle/position)              | exact (linear)/approximated (radial/angular/diamond) | derived from gradientHandlePositions, not a default angle |
+ * | Multiple fills (layering)                    | exact         | reversed to match CSS background-image stacking |
+ * | Image fills (scale modes)                    | exact (FILL/FIT/TILE/STRETCH-axis-aligned) / approximated (skewed imageTransform) | |
+ * | Strokes (uniform, align)                     | exact         | CENTER via outline+negative offset, INSIDE via inset box-shadow, OUTSIDE via outline |
+ * | Strokes (per-side weights)                   | approximated  | CSS has no per-side outline; falls back to per-side `border` (inside-only) |
+ * | Corner radii (uniform + per-corner)          | exact         | |
+ * | Effects: drop/inner shadow                   | exact         | |
+ * | Effects: layer/background blur               | approximated  | Figma <-> CSS blur radius scale is not publicly specified as 1:1 |
+ * | Opacity                                      | exact         | |
+ * | Blend modes (CSS-supported)                   | exact         | |
+ * | Blend modes (Figma-only: LINEAR_BURN/DODGE/LIGHTER/DARKER) | approximated | mapped to closest CSS equivalent |
+ * | clipsContent                                  | exact        | overflow: hidden |
+ * | Rotation                                      | approximated | pivots about the bounding-box center (see below) |
+ * | Vector networks / boolean ops / unsupported types | image fallback | never approximated structurally |
+ *
+ * ### Rotation caveat
+ * The REST API's `rotation` field is in degrees (-180..180), and
+ * `absoluteBoundingBox` is the *already-rotated* axis-aligned bounding box —
+ * Figma does not expose the pre-rotation box directly. We reconstruct the
+ * unrotated box by treating the AABB's center as invariant under rotation
+ * (true for a shape rotated about its own center) and rotate the CSS element
+ * about `transform-origin: center` by `-rotation` degrees (Figma's rotation
+ * is clockwise-negative relative to CSS's clockwise-positive convention).
+ * This is exact when Figma pivots rotation about the shape's center and only
+ * approximated if Figma's internal pivot differs (rare in practice; visually
+ * indistinguishable in the overwhelming majority of designs). A fully exact
+ * alternative would consume `relativeTransform` as a CSS `matrix()` directly,
+ * which is a documented follow-up if a specific design surfaces a visible
+ * mismatch.
+ */
+
+export interface FigmaColor {
+  r: number;
+  g: number;
+  b: number;
+  a?: number;
+}
+
+export interface FigmaColorStop {
+  position: number;
+  color: FigmaColor;
+}
+
+export interface FigmaImageFilter {
+  exposure?: number;
+  contrast?: number;
+  saturation?: number;
+  temperature?: number;
+  tint?: number;
+  highlights?: number;
+  shadows?: number;
+}
+
+export interface FigmaPaint {
+  type:
+    | "SOLID"
+    | "GRADIENT_LINEAR"
+    | "GRADIENT_RADIAL"
+    | "GRADIENT_ANGULAR"
+    | "GRADIENT_DIAMOND"
+    | "IMAGE"
+    | "EMOJI"
+    | "VIDEO";
+  visible?: boolean;
+  opacity?: number;
+  color?: FigmaColor;
+  gradientHandlePositions?: Array<{ x: number; y: number }>;
+  gradientStops?: FigmaColorStop[];
+  imageRef?: string;
+  scaleMode?: "FILL" | "FIT" | "TILE" | "STRETCH";
+  imageTransform?: [[number, number, number], [number, number, number]];
+  filters?: FigmaImageFilter;
+}
+
+export interface FigmaEffect {
+  type: "DROP_SHADOW" | "INNER_SHADOW" | "LAYER_BLUR" | "BACKGROUND_BLUR";
+  visible?: boolean;
+  radius?: number;
+  spread?: number;
+  color?: FigmaColor;
+  offset?: { x: number; y: number };
+  blendMode?: string;
+}
+
+export interface FigmaTypeStyle {
+  fontFamily?: string;
+  fontPostScriptName?: string;
+  fontWeight?: number;
+  fontSize?: number;
+  italic?: boolean;
+  letterSpacing?: number;
+  lineHeightPx?: number;
+  lineHeightPercent?: number;
+  lineHeightPercentFontSize?: number;
+  lineHeightUnit?: "PIXELS" | "FONT_SIZE_%" | "INTRINSIC_%";
+  textCase?: "ORIGINAL" | "UPPER" | "LOWER" | "TITLE";
+  textDecoration?: "NONE" | "UNDERLINE" | "STRIKETHROUGH";
+  textAlignHorizontal?: "LEFT" | "RIGHT" | "CENTER" | "JUSTIFIED";
+  textAlignVertical?: "TOP" | "CENTER" | "BOTTOM";
+  textAutoResize?: "NONE" | "WIDTH_AND_HEIGHT" | "HEIGHT" | "TRUNCATE";
+  fills?: FigmaPaint[];
+}
+
+export interface FigmaIndividualStrokeWeights {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+export interface FigmaBoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface FigmaNode {
+  id: string;
+  name?: string;
+  type: string;
+  visible?: boolean;
+  opacity?: number;
+  blendMode?: string;
+  rotation?: number;
+  absoluteBoundingBox?: FigmaBoundingBox;
+  size?: { x: number; y: number };
+  clipsContent?: boolean;
+  characters?: string;
+  style?: FigmaTypeStyle;
+  fills?: FigmaPaint[];
+  strokes?: FigmaPaint[];
+  strokeWeight?: number;
+  strokeAlign?: "INSIDE" | "OUTSIDE" | "CENTER";
+  individualStrokeWeights?: FigmaIndividualStrokeWeights;
+  cornerRadius?: number;
+  rectangleCornerRadii?: [number, number, number, number];
+  effects?: FigmaEffect[];
+  layoutMode?: "NONE" | "HORIZONTAL" | "VERTICAL" | "GRID";
+  primaryAxisAlignItems?: "MIN" | "CENTER" | "MAX" | "SPACE_BETWEEN";
+  counterAxisAlignItems?: "MIN" | "CENTER" | "MAX" | "BASELINE";
+  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";
+  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";
+  layoutWrap?: "NO_WRAP" | "WRAP";
+  itemSpacing?: number;
+  counterAxisSpacing?: number;
+  paddingLeft?: number;
+  paddingRight?: number;
+  paddingTop?: number;
+  paddingBottom?: number;
+  children?: FigmaNode[];
+}
+
+export type FidelityLevel = "exact" | "approximated" | "image-fallback";
+
+export interface FidelityEntry {
+  nodeId: string;
+  nodeName: string;
+  nodeType: string;
+  level: FidelityLevel;
+  notes: string[];
+}
+
+export interface FidelityReport {
+  entries: FidelityEntry[];
+  summary: {
+    exact: number;
+    approximated: number;
+    imageFallback: number;
+  };
+}
+
+export interface MapFigmaNodeOptions {
+  /** imageRef hash -> resolved public URL, from `/v1/files/:key/images`. */
+  imageFillUrls?: Record<string, string>;
+  /** nodeId -> rendered PNG URL, from `/v1/images/:key` for fallback subtrees. */
+  fallbackImageUrls?: Record<string, string>;
+  /** Node ids that should be rendered as an image regardless of type. */
+  forceImageFallbackNodeIds?: Set<string>;
+}
+
+export interface MapFigmaNodeResult {
+  html: string;
+  fidelity: FidelityReport;
+}
+
+const UNSUPPORTED_STRUCTURAL_TYPES = new Set([
+  "BOOLEAN_OPERATION",
+  "VECTOR",
+  "STAR",
+  "REGULAR_POLYGON",
+  "SLICE",
+  "STICKY",
+  "SHAPE_WITH_TEXT",
+  "CONNECTOR",
+  "WASHI_TAPE",
+  "TABLE",
+]);
+
+const SUPPORTED_CONTAINER_TYPES = new Set([
+  "FRAME",
+  "GROUP",
+  "COMPONENT",
+  "COMPONENT_SET",
+  "INSTANCE",
+  "SECTION",
+]);
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+function round(value: number, precision = 2): number {
+  const factor = 10 ** precision;
+  return Math.round(value * factor) / factor;
+}
+
+function px(value: number | undefined, precision = 2): string | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return `${round(value, precision)}px`;
+}
+
+function colorToCss(
+  color: FigmaColor | undefined,
+  opacityMul = 1,
+): string | null {
+  if (!color) return null;
+  const r = Math.round((color.r ?? 0) * 255);
+  const g = Math.round((color.g ?? 0) * 255);
+  const b = Math.round((color.b ?? 0) * 255);
+  const a = round((color.a ?? 1) * opacityMul, 4);
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function escapeAttr(value: string): string {
+  return escapeHtml(value);
+}
+
+/**
+ * Builds the CSS text for a `style="..."` attribute AND escapes it for HTML
+ * attribute context. This matters because at least one style value we emit
+ * legitimately contains a literal double-quote character: font-family values
+ * are built as `"Inter", sans-serif` (CSS requires quoting family names with
+ * spaces). Without escaping here, that embedded `"` prematurely terminates
+ * the enclosing `style="..."` attribute the moment a browser (or any other
+ * HTML parser) reads it -- silently dropping every style declared after
+ * font-family in object-key order (font-size, font-weight, line-height,
+ * text-align, and the text node's own `display: flex` used to emulate
+ * vertical alignment). The visible symptom is text rendering at the
+ * browser's default font/size instead of the mapped Figma typography, with
+ * no error anywhere -- caught here via a real headless-browser render that
+ * showed a Figma TEXT node's own style attribute silently truncated at
+ * `font-family: "`.
+ */
+function styleAttr(styles: Record<string, string | undefined>): string {
+  const parts = Object.entries(styles)
+    .filter((entry): entry is [string, string] => typeof entry[1] === "string")
+    .map(([key, value]) => `${key}: ${value}`);
+  return escapeAttr(parts.join("; "));
+}
+
+// ---------------------------------------------------------------------------
+// Fidelity report builder
+// ---------------------------------------------------------------------------
+
+class FidelityTracker {
+  private entries = new Map<string, FidelityEntry>();
+
+  record(node: FigmaNode, level: FidelityLevel, note: string) {
+    const existing = this.entries.get(node.id);
+    if (existing) {
+      // Never downgrade an image-fallback entry, and never upgrade below the
+      // worst level recorded for this node.
+      const rank: Record<FidelityLevel, number> = {
+        exact: 0,
+        approximated: 1,
+        "image-fallback": 2,
+      };
+      if (rank[level] > rank[existing.level]) existing.level = level;
+      existing.notes.push(note);
+      return;
+    }
+    this.entries.set(node.id, {
+      nodeId: node.id,
+      nodeName: node.name ?? node.id,
+      nodeType: node.type,
+      level,
+      notes: [note],
+    });
+  }
+
+  build(): FidelityReport {
+    const entries = [...this.entries.values()];
+    const summary = entries.reduce(
+      (acc, entry) => {
+        if (entry.level === "exact") acc.exact += 1;
+        else if (entry.level === "approximated") acc.approximated += 1;
+        else acc.imageFallback += 1;
+        return acc;
+      },
+      { exact: 0, approximated: 0, imageFallback: 0 },
+    );
+    return { entries, summary };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Gradient angle / position derivation
+// ---------------------------------------------------------------------------
+
+interface GradientGeometry {
+  start: { x: number; y: number };
+  end: { x: number; y: number };
+  width: { x: number; y: number };
+}
+
+function resolveGradientGeometry(paint: FigmaPaint): GradientGeometry | null {
+  const handles = paint.gradientHandlePositions;
+  if (!handles || handles.length < 3) return null;
+  return { start: handles[0]!, end: handles[1]!, width: handles[2]! };
+}
+
+/**
+ * Derive a CSS `linear-gradient()` angle (degrees) from Figma's normalized
+ * `gradientHandlePositions`. Handle positions are normalized independently in
+ * x and y (0..1 relative to the node's bounding box), so the angle must be
+ * computed in actual pixel space using the node's real width/height —
+ * otherwise a non-square box silently distorts the angle.
+ *
+ * Verified against Figma's documented identity handles
+ * (start=(0,0.5), end=(1,0.5), width=(1,0), i.e. a plain left-to-right
+ * gradient) which must resolve to CSS `90deg` ("to right"):
+ *   dx = 1*w, dy = 0  -> atan2(0, dx) = 0deg -> +90 = 90deg. Matches.
+ * And a top-to-bottom gradient (start=(0.5,0), end=(0.5,1)) must resolve to
+ * CSS `180deg` ("to bottom"):
+ *   dx = 0, dy = 1*h -> atan2(dy, 0) = 90deg -> +90 = 180deg. Matches.
+ */
+export function gradientAngleDegrees(
+  paint: FigmaPaint,
+  box: { width: number; height: number },
+): number | null {
+  const geometry = resolveGradientGeometry(paint);
+  if (!geometry) return null;
+  const dx = (geometry.end.x - geometry.start.x) * box.width;
+  const dy = (geometry.end.y - geometry.start.y) * box.height;
+  const angleRad = Math.atan2(dy, dx);
+  const angleDeg = (angleRad * 180) / Math.PI + 90;
+  return ((angleDeg % 360) + 360) % 360;
+}
+
+function gradientStopsCss(paint: FigmaPaint): string {
+  const stops = paint.gradientStops ?? [];
+  return stops
+    .map((stop) => {
+      const color = colorToCss(stop.color, paint.opacity ?? 1) ?? "transparent";
+      return `${color} ${round(stop.position * 100, 2)}%`;
+    })
+    .join(", ");
+}
+
+function vectorLength(
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+  box: { width: number; height: number },
+): number {
+  const dx = (to.x - from.x) * box.width;
+  const dy = (to.y - from.y) * box.height;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+/**
+ * Convert one Figma paint layer to a CSS `background-image` value (or plain
+ * color for a SOLID paint used standalone). Returns null for paints that
+ * cannot be expressed as a background-image (handled elsewhere).
+ */
+function paintToCssImage(
+  paint: FigmaPaint,
+  box: { width: number; height: number },
+  tracker: FidelityTracker,
+  node: FigmaNode,
+): string | null {
+  if (paint.visible === false) return null;
+  const stops = gradientStopsCss(paint);
+  if (!stops) return null;
+
+  switch (paint.type) {
+    case "GRADIENT_LINEAR": {
+      const angle = gradientAngleDegrees(paint, box);
+      tracker.record(
+        node,
+        "exact",
+        "Linear gradient angle derived from gradientHandlePositions.",
+      );
+      return `linear-gradient(${round(angle ?? 90, 2)}deg, ${stops})`;
+    }
+    case "GRADIENT_RADIAL": {
+      const geometry = resolveGradientGeometry(paint);
+      if (!geometry) return `radial-gradient(${stops})`;
+      const cx = round(geometry.start.x * 100, 2);
+      const cy = round(geometry.start.y * 100, 2);
+      const radiusX = vectorLength(geometry.start, geometry.width, box);
+      const radiusY = vectorLength(geometry.start, geometry.end, box);
+      tracker.record(
+        node,
+        "approximated",
+        "Radial gradient rendered as an axis-aligned ellipse sized from gradientHandlePositions; rotated/skewed radial gradients are not expressible in CSS radial-gradient().",
+      );
+      return `radial-gradient(ellipse ${round(radiusX, 2)}px ${round(radiusY, 2)}px at ${cx}% ${cy}%, ${stops})`;
+    }
+    case "GRADIENT_ANGULAR": {
+      const geometry = resolveGradientGeometry(paint);
+      const cx = geometry ? round(geometry.start.x * 100, 2) : 50;
+      const cy = geometry ? round(geometry.start.y * 100, 2) : 50;
+      const fromAngle = geometry ? gradientAngleDegrees(paint, box) : 0;
+      tracker.record(
+        node,
+        "approximated",
+        "Conic (angular) gradient start angle derived from gradientHandlePositions using the same angle formula as linear gradients; CSS conic-gradient() has no elliptical distortion so non-uniform boxes may render slightly differently than Figma.",
+      );
+      return `conic-gradient(from ${round(fromAngle ?? 0, 2)}deg at ${cx}% ${cy}%, ${stops})`;
+    }
+    case "GRADIENT_DIAMOND": {
+      const geometry = resolveGradientGeometry(paint);
+      const cx = geometry ? round(geometry.start.x * 100, 2) : 50;
+      const cy = geometry ? round(geometry.start.y * 100, 2) : 50;
+      const radiusX = geometry
+        ? vectorLength(geometry.start, geometry.width, box)
+        : box.width / 2;
+      const radiusY = geometry
+        ? vectorLength(geometry.start, geometry.end, box)
+        : box.height / 2;
+      tracker.record(
+        node,
+        "approximated",
+        "Diamond gradient has no CSS equivalent; approximated as an axis-aligned elliptical radial-gradient sized from gradientHandlePositions. True diamond (rotated-square) falloff is not reproduced.",
+      );
+      return `radial-gradient(ellipse ${round(radiusX, 2)}px ${round(radiusY, 2)}px at ${cx}% ${cy}%, ${stops})`;
+    }
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fills -> background
+// ---------------------------------------------------------------------------
+
+interface BackgroundResult {
+  backgroundColor?: string;
+  backgroundImage?: string;
+  backgroundSize?: string;
+  backgroundPosition?: string;
+  backgroundRepeat?: string;
+  color?: string; // for TEXT nodes, fill paints color the glyphs, not a background
+}
+
+function imageScaleModeCss(
+  paint: FigmaPaint,
+  node: FigmaNode,
+  tracker: FidelityTracker,
+): { size: string; position: string; repeat: string } {
+  const transform = paint.imageTransform;
+  const isAxisAligned =
+    !transform ||
+    (Math.abs(transform[0][1]) < 1e-6 && Math.abs(transform[1][0]) < 1e-6);
+  if (!isAxisAligned) {
+    tracker.record(
+      node,
+      "approximated",
+      "Image fill has a non-axis-aligned imageTransform (rotated/skewed crop); approximated using the scale-mode-only CSS mapping without the transform matrix.",
+    );
+  }
+  switch (paint.scaleMode) {
+    case "FILL":
+      return { size: "cover", position: "center", repeat: "no-repeat" };
+    case "FIT":
+      return { size: "contain", position: "center", repeat: "no-repeat" };
+    case "TILE":
+      return { size: "auto", position: "top left", repeat: "repeat" };
+    case "STRETCH":
+      return { size: "100% 100%", position: "center", repeat: "no-repeat" };
+    default:
+      return { size: "cover", position: "center", repeat: "no-repeat" };
+  }
+}
+
+/**
+ * Build the background-* properties for a node's fill stack. Figma paints
+ * fills bottom-to-top (index 0 is the bottommost layer); CSS
+ * `background-image` layers top-to-bottom (first value on top), so the
+ * stack is reversed here to preserve visual order. A solid fill above other
+ * layers is expressed as a flat `linear-gradient(color, color)` since CSS
+ * `background-color` always paints *beneath every* background-image and
+ * cannot be interleaved mid-stack.
+ */
+function buildFills(
+  node: FigmaNode,
+  fills: FigmaPaint[] | undefined,
+  box: { width: number; height: number },
+  options: MapFigmaNodeOptions,
+  tracker: FidelityTracker,
+  isTextNode: boolean,
+): BackgroundResult {
+  const visible = (fills ?? []).filter((fill) => fill.visible !== false);
+  if (visible.length === 0) return {};
+
+  if (isTextNode) {
+    // Text color comes from the topmost visible SOLID fill; gradient/image
+    // text fills are a CSS `background-clip: text` trick we intentionally
+    // skip for now (rare in practice) and record as approximated.
+    const solid = [...visible].reverse().find((fill) => fill.type === "SOLID");
+    if (solid) {
+      return {
+        color: colorToCss(solid.color, solid.opacity ?? 1) ?? undefined,
+      };
+    }
+    tracker.record(
+      node,
+      "approximated",
+      "Text fill is a gradient/image, not a solid color; rendered with the default text color instead of a background-clip: text gradient.",
+    );
+    return {};
+  }
+
+  const images: string[] = [];
+  const sizes: string[] = [];
+  const positions: string[] = [];
+  const repeats: string[] = [];
+  let backgroundColor: string | undefined;
+
+  // Reverse so the topmost Figma fill becomes the first (topmost) CSS layer.
+  const ordered = [...visible].reverse();
+  for (let index = 0; index < ordered.length; index += 1) {
+    const fill = ordered[index]!;
+    const isBottommost = index === ordered.length - 1;
+
+    if (fill.type === "SOLID") {
+      const color = colorToCss(fill.color, fill.opacity ?? 1);
+      if (!color) continue;
+      if (isBottommost) {
+        // A bottom-most solid always paints beneath every background-image
+        // layer, so it can always become plain backgroundColor regardless of
+        // how many gradient/image layers are stacked above it.
+        backgroundColor = color;
+      } else {
+        // Solid above other layers: express as a flat gradient so it stacks
+        // in the correct z-order alongside gradient/image layers.
+        images.push(`linear-gradient(${color}, ${color})`);
+        sizes.push("100% 100%");
+        positions.push("center");
+        repeats.push("no-repeat");
+      }
+      continue;
+    }
+
+    if (fill.type === "IMAGE") {
+      const url = fill.imageRef
+        ? options.imageFillUrls?.[fill.imageRef]
+        : undefined;
+      if (!url) {
+        tracker.record(
+          node,
+          "approximated",
+          `Image fill imageRef "${fill.imageRef ?? "unknown"}" had no resolved URL; layer omitted.`,
+        );
+        continue;
+      }
+      const mode = imageScaleModeCss(fill, node, tracker);
+      images.push(`url("${url}")`);
+      sizes.push(mode.size);
+      positions.push(mode.position);
+      repeats.push(mode.repeat);
+      continue;
+    }
+
+    const cssImage = paintToCssImage(fill, box, tracker, node);
+    if (cssImage) {
+      images.push(cssImage);
+      sizes.push("100% 100%");
+      positions.push("center");
+      repeats.push("no-repeat");
+    }
+  }
+
+  const result: BackgroundResult = {};
+  if (backgroundColor) result.backgroundColor = backgroundColor;
+  if (images.length > 0) {
+    result.backgroundImage = images.join(", ");
+    result.backgroundSize = sizes.join(", ");
+    result.backgroundPosition = positions.join(", ");
+    result.backgroundRepeat = repeats.join(", ");
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Strokes -> border / outline / box-shadow
+// ---------------------------------------------------------------------------
+
+interface StrokeResult {
+  styles: Record<string, string | undefined>;
+  insetShadow?: string;
+}
+
+function buildStrokes(node: FigmaNode, tracker: FidelityTracker): StrokeResult {
+  const strokes = (node.strokes ?? []).filter(
+    (stroke) => stroke.visible !== false,
+  );
+  if (strokes.length === 0) return { styles: {} };
+
+  const first = strokes[0]!;
+  const color =
+    colorToCss(first.color, first.opacity ?? 1) ?? "rgba(0, 0, 0, 1)";
+  const iw = node.individualStrokeWeights;
+  const hasPerSide =
+    iw &&
+    (iw.top !== undefined ||
+      iw.right !== undefined ||
+      iw.bottom !== undefined ||
+      iw.left !== undefined);
+  const uniformWeight = node.strokeWeight ?? 0;
+
+  if (hasPerSide) {
+    // CSS `outline`/inset-`box-shadow` tricks are single-weight only; per-side
+    // stroke weights can only be expressed as a real per-side `border`, which
+    // always renders fully inside the border-box regardless of strokeAlign.
+    // This is exact for INSIDE and an approximation for CENTER/OUTSIDE.
+    const top = iw?.top ?? uniformWeight;
+    const right = iw?.right ?? uniformWeight;
+    const bottom = iw?.bottom ?? uniformWeight;
+    const left = iw?.left ?? uniformWeight;
+    tracker.record(
+      node,
+      node.strokeAlign === "INSIDE" || !node.strokeAlign
+        ? "exact"
+        : "approximated",
+      `Per-side stroke weights rendered as CSS border (inside-aligned); strokeAlign="${node.strokeAlign ?? "INSIDE"}" cannot vary per-side with outline tricks.`,
+    );
+    return {
+      styles: {
+        "border-top": top ? `${px(top)} solid ${color}` : undefined,
+        "border-right": right ? `${px(right)} solid ${color}` : undefined,
+        "border-bottom": bottom ? `${px(bottom)} solid ${color}` : undefined,
+        "border-left": left ? `${px(left)} solid ${color}` : undefined,
+      },
+    };
+  }
+
+  if (!uniformWeight) return { styles: {} };
+
+  switch (node.strokeAlign) {
+    case "OUTSIDE":
+      tracker.record(
+        node,
+        "exact",
+        "OUTSIDE stroke rendered via outline (offset 0).",
+      );
+      return {
+        styles: {
+          outline: `${px(uniformWeight)} solid ${color}`,
+          "outline-offset": "0px",
+        },
+      };
+    case "INSIDE":
+      tracker.record(
+        node,
+        "exact",
+        "INSIDE stroke rendered via inset box-shadow.",
+      );
+      return {
+        styles: {},
+        insetShadow: `inset 0 0 0 ${px(uniformWeight)} ${color}`,
+      };
+    case "CENTER":
+    default:
+      // outline-offset of -half the weight pulls the outline half inside,
+      // half outside the border-box edge -- reproducing Figma's CENTER
+      // straddle exactly (plain CSS `border` cannot straddle the edge).
+      tracker.record(
+        node,
+        "exact",
+        "CENTER stroke rendered via outline with outline-offset = -weight/2 (straddles the edge like Figma).",
+      );
+      return {
+        styles: {
+          outline: `${px(uniformWeight)} solid ${color}`,
+          "outline-offset": px(-uniformWeight / 2),
+        },
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Corner radii
+// ---------------------------------------------------------------------------
+
+function buildCornerRadius(node: FigmaNode): string | undefined {
+  if (node.rectangleCornerRadii) {
+    const [tl, tr, br, bl] = node.rectangleCornerRadii;
+    return `${px(tl) ?? "0px"} ${px(tr) ?? "0px"} ${px(br) ?? "0px"} ${px(bl) ?? "0px"}`;
+  }
+  if (typeof node.cornerRadius === "number" && node.cornerRadius > 0) {
+    return px(node.cornerRadius);
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Effects -> box-shadow / filter / backdrop-filter
+// ---------------------------------------------------------------------------
+
+interface EffectResult {
+  boxShadowLayers: string[];
+  filter?: string;
+  backdropFilter?: string;
+}
+
+function buildEffects(
+  node: FigmaNode,
+  isTextNode: boolean,
+  tracker: FidelityTracker,
+): EffectResult {
+  const effects = (node.effects ?? []).filter(
+    (effect) => effect.visible !== false,
+  );
+  const boxShadowLayers: string[] = [];
+  let filter: string | undefined;
+  let backdropFilter: string | undefined;
+
+  for (const effect of effects) {
+    if (effect.type === "DROP_SHADOW" || effect.type === "INNER_SHADOW") {
+      const color = colorToCss(effect.color, 1) ?? "rgba(0, 0, 0, 1)";
+      const x = px(effect.offset?.x ?? 0) ?? "0px";
+      const y = px(effect.offset?.y ?? 0) ?? "0px";
+      const blur = px(effect.radius ?? 0) ?? "0px";
+      const spread =
+        !isTextNode && typeof effect.spread === "number"
+          ? ` ${px(effect.spread)}`
+          : "";
+      const inset = effect.type === "INNER_SHADOW" ? "inset " : "";
+      boxShadowLayers.push(`${inset}${x} ${y} ${blur}${spread} ${color}`);
+      tracker.record(
+        node,
+        "exact",
+        `${effect.type} rendered as ${isTextNode ? "text-shadow" : "box-shadow"}.`,
+      );
+    } else if (effect.type === "LAYER_BLUR") {
+      const radius = px(effect.radius ?? 0) ?? "0px";
+      filter = filter ? `${filter} blur(${radius})` : `blur(${radius})`;
+      tracker.record(
+        node,
+        "approximated",
+        "LAYER_BLUR mapped 1:1 to CSS filter: blur(); Figma's blur radius-to-CSS-stdDeviation scale is not publicly documented, so the rendered softness may differ slightly.",
+      );
+    } else if (effect.type === "BACKGROUND_BLUR") {
+      const radius = px(effect.radius ?? 0) ?? "0px";
+      backdropFilter = backdropFilter
+        ? `${backdropFilter} blur(${radius})`
+        : `blur(${radius})`;
+      tracker.record(
+        node,
+        "approximated",
+        "BACKGROUND_BLUR mapped 1:1 to CSS backdrop-filter: blur(); same radius-scale caveat as LAYER_BLUR.",
+      );
+    }
+  }
+
+  return { boxShadowLayers, filter, backdropFilter };
+}
+
+// ---------------------------------------------------------------------------
+// Blend modes
+// ---------------------------------------------------------------------------
+
+const CSS_BLEND_MODES = new Set([
+  "multiply",
+  "screen",
+  "overlay",
+  "darken",
+  "lighten",
+  "color-dodge",
+  "color-burn",
+  "hard-light",
+  "soft-light",
+  "difference",
+  "exclusion",
+  "hue",
+  "saturation",
+  "color",
+  "luminosity",
+]);
+
+const FIGMA_ONLY_BLEND_MODE_FALLBACK: Record<string, string> = {
+  LINEAR_BURN: "multiply",
+  LINEAR_DODGE: "plus-lighter",
+  LIGHTER: "plus-lighter",
+  DARKER: "darken",
+};
+
+function buildBlendMode(
+  node: FigmaNode,
+  tracker: FidelityTracker,
+): string | undefined {
+  const mode = node.blendMode;
+  if (!mode || mode === "PASS_THROUGH" || mode === "NORMAL") return undefined;
+  const cssMode = mode.toLowerCase().replace(/_/g, "-");
+  if (CSS_BLEND_MODES.has(cssMode)) return cssMode;
+  const fallback = FIGMA_ONLY_BLEND_MODE_FALLBACK[mode];
+  if (fallback) {
+    tracker.record(
+      node,
+      "approximated",
+      `Figma blend mode "${mode}" has no CSS equivalent; approximated as mix-blend-mode: ${fallback}.`,
+    );
+    return fallback;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Text styling
+// ---------------------------------------------------------------------------
+
+function resolveLineHeight(style: FigmaTypeStyle): string | undefined {
+  if (
+    typeof style.lineHeightPx === "number" &&
+    style.lineHeightUnit !== "FONT_SIZE_%"
+  ) {
+    return px(style.lineHeightPx);
+  }
+  if (
+    typeof style.lineHeightPercentFontSize === "number" &&
+    typeof style.fontSize === "number"
+  ) {
+    // lineHeightPercentFontSize is literally "percent of the font's nominal
+    // size" -- resolve to an exact px value rather than a unitless ratio so
+    // the rendered line box matches Figma regardless of font metrics.
+    return px(style.fontSize * (style.lineHeightPercentFontSize / 100));
+  }
+  if (typeof style.lineHeightPx === "number") {
+    return px(style.lineHeightPx);
+  }
+  return undefined;
+}
+
+function textTransformCss(
+  textCase: FigmaTypeStyle["textCase"],
+): string | undefined {
+  switch (textCase) {
+    case "UPPER":
+      return "uppercase";
+    case "LOWER":
+      return "lowercase";
+    case "TITLE":
+      return "capitalize";
+    default:
+      return undefined;
+  }
+}
+
+function textDecorationCss(
+  decoration: FigmaTypeStyle["textDecoration"],
+): string | undefined {
+  switch (decoration) {
+    case "UNDERLINE":
+      return "underline";
+    case "STRIKETHROUGH":
+      return "line-through";
+    default:
+      return undefined;
+  }
+}
+
+function textAlignCss(
+  align: FigmaTypeStyle["textAlignHorizontal"],
+): string | undefined {
+  switch (align) {
+    case "CENTER":
+      return "center";
+    case "RIGHT":
+      return "right";
+    case "JUSTIFIED":
+      return "justify";
+    case "LEFT":
+      return "left";
+    default:
+      return undefined;
+  }
+}
+
+function verticalAlignJustifyContent(
+  align: FigmaTypeStyle["textAlignVertical"],
+): string {
+  switch (align) {
+    case "CENTER":
+      return "center";
+    case "BOTTOM":
+      return "flex-end";
+    default:
+      return "flex-start";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-layout
+// ---------------------------------------------------------------------------
+
+function primaryAxisJustify(align: FigmaNode["primaryAxisAlignItems"]): string {
+  switch (align) {
+    case "CENTER":
+      return "center";
+    case "MAX":
+      return "flex-end";
+    case "SPACE_BETWEEN":
+      return "space-between";
+    default:
+      return "flex-start";
+  }
+}
+
+function counterAxisAlign(align: FigmaNode["counterAxisAlignItems"]): string {
+  switch (align) {
+    case "CENTER":
+      return "center";
+    case "MAX":
+      return "flex-end";
+    case "BASELINE":
+      return "baseline";
+    default:
+      return "flex-start";
+  }
+}
+
+function buildAutoLayoutStyles(
+  node: FigmaNode,
+): Record<string, string | undefined> {
+  if (
+    !node.layoutMode ||
+    node.layoutMode === "NONE" ||
+    node.layoutMode === "GRID"
+  ) {
+    return {};
+  }
+  const isHorizontal = node.layoutMode === "HORIZONTAL";
+  const styles: Record<string, string | undefined> = {
+    display: "flex",
+    "flex-direction": isHorizontal ? "row" : "column",
+    "justify-content": primaryAxisJustify(node.primaryAxisAlignItems),
+    "align-items": counterAxisAlign(node.counterAxisAlignItems),
+  };
+  if (node.layoutWrap === "WRAP") styles["flex-wrap"] = "wrap";
+  if (typeof node.itemSpacing === "number" && node.itemSpacing !== 0) {
+    styles[isHorizontal ? "column-gap" : "row-gap"] = px(node.itemSpacing);
+  }
+  if (
+    typeof node.counterAxisSpacing === "number" &&
+    node.counterAxisSpacing !== 0
+  ) {
+    styles[isHorizontal ? "row-gap" : "column-gap"] = px(
+      node.counterAxisSpacing,
+    );
+  }
+  const padTop = node.paddingTop ?? 0;
+  const padRight = node.paddingRight ?? 0;
+  const padBottom = node.paddingBottom ?? 0;
+  const padLeft = node.paddingLeft ?? 0;
+  if (padTop || padRight || padBottom || padLeft) {
+    styles.padding = `${px(padTop)} ${px(padRight)} ${px(padBottom)} ${px(padLeft)}`;
+  }
+  return styles;
+}
+
+/**
+ * "FILL" sizing must map to different CSS depending on which axis is the
+ * flex *main* axis for this node's parent: main-axis FILL grows via
+ * `flex-grow`/`flex-basis` (row parent -> horizontal FILL, column parent ->
+ * vertical FILL); cross-axis FILL stretches via `align-self: stretch` (row
+ * parent -> vertical FILL, column parent -> horizontal FILL). Passing only a
+ * `parentHasAutoLayout` boolean (as this used to) loses the row/column
+ * direction and always mapped horizontal-FILL to flex-grow — correct for row
+ * parents but wrong for column parents, where a FILL-width text/rect child
+ * got `width: auto` with no stretch and overflowed to its content width.
+ */
+function buildChildSizingStyles(
+  node: FigmaNode,
+  parentLayoutMode: "NONE" | "HORIZONTAL" | "VERTICAL",
+): Record<string, string | undefined> {
+  if (parentLayoutMode === "NONE") return {};
+  const parentIsHorizontal = parentLayoutMode === "HORIZONTAL";
+  const styles: Record<string, string | undefined> = {};
+  if (node.layoutSizingHorizontal === "FILL") {
+    if (parentIsHorizontal) {
+      styles["flex-grow"] = "1";
+      styles["flex-basis"] = "0%";
+    } else {
+      styles["align-self"] = "stretch";
+    }
+    styles.width = "auto";
+  } else if (node.layoutSizingHorizontal === "HUG") {
+    styles.width = "auto";
+  }
+  if (node.layoutSizingVertical === "FILL") {
+    if (parentIsHorizontal) {
+      styles["align-self"] = "stretch";
+    } else {
+      styles["flex-grow"] = "1";
+      styles["flex-basis"] = "0%";
+    }
+    styles.height = "auto";
+  } else if (node.layoutSizingVertical === "HUG") {
+    styles.height = "auto";
+  }
+  return styles;
+}
+
+// ---------------------------------------------------------------------------
+// Node type classification
+// ---------------------------------------------------------------------------
+
+function needsImageFallback(
+  node: FigmaNode,
+  options: MapFigmaNodeOptions,
+): boolean {
+  if (options.forceImageFallbackNodeIds?.has(node.id)) return true;
+  if (UNSUPPORTED_STRUCTURAL_TYPES.has(node.type)) return true;
+  if (
+    !SUPPORTED_CONTAINER_TYPES.has(node.type) &&
+    node.type !== "RECTANGLE" &&
+    node.type !== "ELLIPSE" &&
+    node.type !== "LINE" &&
+    node.type !== "TEXT"
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Walk a node tree and return the ids of every subtree that will render as a
+ * PNG image fallback (vector networks, boolean ops, and any node type this
+ * mapper does not model structurally). Call this before fetching node data
+ * so the caller can request rendered images for exactly these ids via
+ * `GET /v1/images/:fileKey?ids=...&scale=2`.
+ */
+export function collectFallbackNodeIds(
+  node: FigmaNode,
+  options: MapFigmaNodeOptions = {},
+): string[] {
+  const ids: string[] = [];
+  const visit = (current: FigmaNode) => {
+    if (current.visible === false) return;
+    if (needsImageFallback(current, options)) {
+      ids.push(current.id);
+      return; // Don't recurse into a subtree that's rendered as one image.
+    }
+    for (const child of current.children ?? []) visit(child);
+  };
+  visit(node);
+  return ids;
+}
+
+/**
+ * Walk a node tree and return every distinct `imageRef` used by IMAGE fills
+ * (on fills or strokes) so the caller can resolve them to URLs via
+ * `GET /v1/files/:fileKey/images` before mapping.
+ */
+export function collectImageFillRefs(node: FigmaNode): string[] {
+  const refs = new Set<string>();
+  const visitPaints = (paints: FigmaPaint[] | undefined) => {
+    for (const paint of paints ?? []) {
+      if (paint.type === "IMAGE" && paint.imageRef) refs.add(paint.imageRef);
+    }
+  };
+  const visit = (current: FigmaNode) => {
+    visitPaints(current.fills);
+    visitPaints(current.strokes);
+    for (const child of current.children ?? []) visit(child);
+  };
+  visit(node);
+  return [...refs];
+}
+
+// ---------------------------------------------------------------------------
+// Main mapper
+// ---------------------------------------------------------------------------
+
+function frameRelativeBox(
+  node: FigmaNode,
+  parentBox: FigmaBoundingBox | null,
+): { left: number; top: number; width: number; height: number } {
+  const box = node.absoluteBoundingBox;
+  if (!box) return { left: 0, top: 0, width: 0, height: 0 };
+  return {
+    left: box.x - (parentBox?.x ?? box.x),
+    top: box.y - (parentBox?.y ?? box.y),
+    width: box.width,
+    height: box.height,
+  };
+}
+
+function buildNode(
+  node: FigmaNode,
+  parentBox: FigmaBoundingBox | null,
+  parentLayoutMode: "NONE" | "HORIZONTAL" | "VERTICAL",
+  options: MapFigmaNodeOptions,
+  tracker: FidelityTracker,
+  isRoot: boolean,
+): string {
+  const parentHasAutoLayout = parentLayoutMode !== "NONE";
+  if (node.visible === false) return "";
+
+  const box = frameRelativeBox(node, parentBox);
+  const nameAttr = node.name
+    ? ` data-agent-native-layer-name="${escapeAttr(node.name)}"`
+    : "";
+  const idAttr = ` data-figma-node-id="${escapeAttr(node.id)}"`;
+  const typeAttr = ` data-figma-node-type="${escapeAttr(node.type)}"`;
+
+  if (needsImageFallback(node, options)) {
+    const imageUrl = options.fallbackImageUrls?.[node.id];
+    if (!imageUrl) {
+      tracker.record(
+        node,
+        "image-fallback",
+        `Node type "${node.type}" requires an image fallback but no rendered URL was provided; nothing was rendered for this node.`,
+      );
+      return "";
+    }
+    tracker.record(
+      node,
+      "image-fallback",
+      `Node type "${node.type}" cannot be reproduced structurally (vector network / boolean op / unsupported type); rendered as an exact PNG (scale=2) instead of an approximated structural guess.`,
+    );
+    const styles: Record<string, string | undefined> = {
+      position: isRoot ? "relative" : "absolute",
+      left: isRoot ? undefined : px(box.left),
+      top: isRoot ? undefined : px(box.top),
+      width: px(box.width),
+      height: px(box.height),
+      opacity:
+        typeof node.opacity === "number" && node.opacity !== 1
+          ? String(round(node.opacity, 4))
+          : undefined,
+    };
+    return `<img${idAttr}${typeAttr}${nameAttr} src="${escapeAttr(imageUrl)}" alt="${escapeAttr(node.name ?? "")}" style="${styleAttr(styles)}" />`;
+  }
+
+  const isTextNode = node.type === "TEXT";
+  const isEllipse = node.type === "ELLIPSE";
+  const box2 = { width: box.width, height: box.height };
+
+  const fills = buildFills(
+    node,
+    node.fills,
+    box2,
+    options,
+    tracker,
+    isTextNode,
+  );
+  const strokeResult = buildStrokes(node, tracker);
+  const effects = buildEffects(node, isTextNode, tracker);
+  const cornerRadius = isEllipse ? "50%" : buildCornerRadius(node);
+  const blendMode = buildBlendMode(node, tracker);
+
+  const boxShadowParts = [...effects.boxShadowLayers];
+  if (strokeResult.insetShadow) boxShadowParts.push(strokeResult.insetShadow);
+
+  const rotation =
+    typeof node.rotation === "number" && Math.abs(node.rotation) > 0.001
+      ? node.rotation
+      : undefined;
+  if (rotation !== undefined) {
+    tracker.record(
+      node,
+      "approximated",
+      `Rotation (${round(rotation, 2)}deg) reconstructed by pivoting the unrotated box about the absoluteBoundingBox center; exact only when Figma's internal pivot is also the shape's center.`,
+    );
+  }
+
+  const autoLayoutStyles = buildAutoLayoutStyles(node);
+  const childSizingStyles = buildChildSizingStyles(node, parentLayoutMode);
+  const hasAutoLayout = Boolean(autoLayoutStyles.display);
+  // A node is positioned relative to its parent's free canvas (absolute,
+  // left/top from absoluteBoundingBox) unless its *parent* is an auto-layout
+  // container, in which case it's a normal flex item (relative, no left/top)
+  // -- this mirrors Figma's own rule that auto-layout children give up
+  // manual x/y in favor of flex flow.
+  const isFlexChild = !isRoot && parentHasAutoLayout;
+
+  const baseStyles: Record<string, string | undefined> = {
+    position: isRoot ? "relative" : isFlexChild ? "relative" : "absolute",
+    left: isRoot || isFlexChild ? undefined : px(box.left),
+    top: isRoot || isFlexChild ? undefined : px(box.top),
+    width: childSizingStyles.width ?? px(box.width),
+    height: childSizingStyles.height ?? px(box.height),
+    "background-color": fills.backgroundColor,
+    "background-image": fills.backgroundImage,
+    "background-size": fills.backgroundSize,
+    "background-position": fills.backgroundPosition,
+    "background-repeat": fills.backgroundRepeat,
+    color: fills.color,
+    "border-radius": cornerRadius,
+    "box-shadow":
+      boxShadowParts.length > 0 ? boxShadowParts.join(", ") : undefined,
+    filter: effects.filter,
+    "backdrop-filter": effects.backdropFilter,
+    "-webkit-backdrop-filter": effects.backdropFilter,
+    opacity:
+      typeof node.opacity === "number" && node.opacity !== 1
+        ? String(round(node.opacity, 4))
+        : undefined,
+    "mix-blend-mode": blendMode,
+    overflow: node.clipsContent ? "hidden" : undefined,
+    transform:
+      rotation !== undefined ? `rotate(${round(-rotation, 3)}deg)` : undefined,
+    "transform-origin": rotation !== undefined ? "center" : undefined,
+    ...autoLayoutStyles,
+    ...strokeResult.styles,
+    ...childSizingStyles,
+  };
+
+  if (isTextNode) {
+    const style = node.style ?? {};
+    baseStyles["font-family"] = style.fontFamily
+      ? `"${style.fontFamily.replace(/"/g, "")}", sans-serif`
+      : undefined;
+    baseStyles["font-size"] = px(style.fontSize);
+    baseStyles["font-weight"] =
+      typeof style.fontWeight === "number"
+        ? String(style.fontWeight)
+        : undefined;
+    baseStyles["font-style"] = style.italic ? "italic" : undefined;
+    baseStyles["line-height"] = resolveLineHeight(style);
+    baseStyles["letter-spacing"] =
+      typeof style.letterSpacing === "number" && style.letterSpacing !== 0
+        ? px(style.letterSpacing)
+        : undefined;
+    baseStyles["text-transform"] = textTransformCss(style.textCase);
+    baseStyles["text-decoration"] = textDecorationCss(style.textDecoration);
+    baseStyles["text-align"] = textAlignCss(style.textAlignHorizontal);
+    if (style.textAutoResize === "TRUNCATE") {
+      baseStyles["white-space"] = "nowrap";
+      baseStyles.overflow = "hidden";
+      baseStyles["text-overflow"] = "ellipsis";
+    }
+    baseStyles.display = "flex";
+    baseStyles["flex-direction"] = "column";
+    baseStyles["justify-content"] = verticalAlignJustifyContent(
+      style.textAlignVertical,
+    );
+    tracker.record(node, "exact", "Text styling mapped from TypeStyle fields.");
+
+    const characters = node.characters ?? "";
+    return `<div${idAttr}${typeAttr}${nameAttr} style="${styleAttr(baseStyles)}">${escapeHtml(characters)}</div>`;
+  }
+
+  tracker.record(
+    node,
+    "exact",
+    "Position, size, fills, strokes, and effects mapped 1:1.",
+  );
+
+  // hasAutoLayout guarantees node.layoutMode is "HORIZONTAL" or "VERTICAL"
+  // (buildAutoLayoutStyles returns {} -- no `display` -- for "NONE"/"GRID").
+  const childParentLayoutMode: "NONE" | "HORIZONTAL" | "VERTICAL" =
+    hasAutoLayout ? (node.layoutMode as "HORIZONTAL" | "VERTICAL") : "NONE";
+  const childrenHtml = (node.children ?? [])
+    .map((child) =>
+      buildNode(
+        child,
+        node.absoluteBoundingBox ?? null,
+        childParentLayoutMode,
+        options,
+        tracker,
+        false,
+      ),
+    )
+    .filter(Boolean)
+    .join("\n");
+
+  return `<div${idAttr}${typeAttr}${nameAttr} style="${styleAttr(baseStyles)}">\n${childrenHtml}\n</div>`;
+}
+
+/**
+ * Map a Figma node (and its subtree) to an HTML fragment plus a fidelity
+ * report describing which properties were exact, approximated, or rendered
+ * as an image fallback.
+ */
+export function mapFigmaNodeToHtml(
+  node: FigmaNode,
+  options: MapFigmaNodeOptions = {},
+): MapFigmaNodeResult {
+  const tracker = new FidelityTracker();
+  const html = buildNode(node, null, "NONE", options, tracker, true);
+  return { html, fidelity: tracker.build() };
+}
diff --git a/templates/design/server/lib/figma-paste-fallback.ts b/templates/design/server/lib/figma-paste-fallback.ts
new file mode 100644
index 0000000000..db7b84dfb9
--- /dev/null
+++ b/templates/design/server/lib/figma-paste-fallback.ts
@@ -0,0 +1,64 @@
+/**
+ * Shared "legacy" Figma paste fallback: saves the visible clipboard HTML
+ * (markers stripped by `parseVisibleClipboardHtml`) as a new Design screen.
+ *
+ * Extracted from `import-design-source.ts`'s `figma-paste-html` branch so the
+ * REST-first clipboard import path (`import-figma-clipboard.ts`) can fall back
+ * to the exact same behavior when node resolution can't confidently match the
+ * pasted content to specific Figma nodes, instead of re-implementing it.
+ */
+
+import {
+  normalizeImportedHtmlDocument,
+  resolveImportDesignId,
+  saveImportedDesignFiles,
+} from "./import-design-files.js";
+import { parseVisibleClipboardHtml } from "./visible-clipboard-html.js";
+
+export interface SaveFigmaPasteHtmlFallbackInput {
+  designId?: string;
+  clipboardHtml: string;
+  originalName?: string;
+}
+
+function baseFilename(originalName: string | undefined, fallback: string) {
+  return (originalName?.trim() || fallback).replace(/\.[^.]+$/, "") + ".html";
+}
+
+export async function saveFigmaPasteHtmlFallback(
+  input: SaveFigmaPasteHtmlFallbackInput,
+) {
+  const parsed = parseVisibleClipboardHtml(input.clipboardHtml);
+  if (!parsed.fallbackHtml) {
+    throw new Error(
+      "No visible HTML was found in the clipboard. Copy a frame, then paste into the canvas.",
+    );
+  }
+  const designId = await resolveImportDesignId(input.designId);
+  const saved = await saveImportedDesignFiles({
+    designId,
+    sourceType: "figma-paste-html",
+    files: [
+      {
+        filename: baseFilename(input.originalName, "figma-paste"),
+        fileType: "html",
+        content: normalizeImportedHtmlDocument(
+          parsed.fallbackHtml,
+          "visible clipboard HTML",
+        ),
+        source: {
+          sourceType: "figma-paste-html",
+        },
+      },
+    ],
+  });
+  return {
+    ...saved,
+    stats: {
+      sourceKind: "figma-paste",
+      format: "html",
+      frameCount: saved.files.length,
+      imageCount: 0,
+    },
+  };
+}
diff --git a/templates/design/server/lib/playwright-runtime.ts b/templates/design/server/lib/playwright-runtime.ts
new file mode 100644
index 0000000000..129f07c130
--- /dev/null
+++ b/templates/design/server/lib/playwright-runtime.ts
@@ -0,0 +1,78 @@
+/**
+ * playwright-runtime.ts — shared headless-Chromium bootstrap used by every
+ * server-side action that needs a real rendered DOM (as opposed to static
+ * HTML/CSS analysis): `take-design-screenshot.ts`'s visual diagnostics pass
+ * and `design-to-figma-svg.ts`'s scene extractor for the Figma SVG export.
+ *
+ * Extracted out of `take-design-screenshot.ts` (which originally owned this
+ * logic) so `server/lib/*` modules can share it without an inverted
+ * lib -> action dependency. `take-design-screenshot.ts` re-exports these same
+ * names for backward compatibility with its existing spec/imports.
+ */
+
+export type PlaywrightModule = {
+  chromium: import("@playwright/test").BrowserType;
+};
+
+/**
+ * Dynamic import of a real Chromium-capable Playwright package.  Tries the
+ * bare `"playwright"` package first (present when `@agent-native/core`'s
+ * optional dependency resolved), then falls back to `@playwright/test` (a
+ * direct devDependency of this template, used by its own e2e suite, which
+ * re-exports the same chromium/Browser API). Loaded via a non-literal
+ * specifier so bundlers don't try to statically resolve/include it — it's
+ * optional and can be entirely absent (e.g. in a hosted deploy).
+ */
+export async function importPlaywright(): Promise<PlaywrightModule> {
+  try {
+    const specifier = "playwright";
+    return (await import(
+      /* @vite-ignore */ specifier
+    )) as unknown as PlaywrightModule;
+  } catch {
+    return (await import("@playwright/test")) as unknown as PlaywrightModule;
+  }
+}
+
+const SYSTEM_CHROME_EXECUTABLES = [
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/google-chrome",
+  "/usr/bin/chromium-browser",
+  "/usr/bin/chromium",
+];
+
+/** Pure classifier for "no Chromium binary available" errors. */
+export function isMissingBrowserError(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err);
+  return /Executable doesn't exist|playwright install|browser.*not found|chromium.*not found/i.test(
+    message,
+  );
+}
+
+/** Launches Chromium, falling back to a system Chrome/Chromium binary when
+ *  Playwright's bundled browser isn't installed (hosted/serverless deploys). */
+export async function launchChromium(
+  chromium: import("@playwright/test").BrowserType,
+): Promise<import("@playwright/test").Browser> {
+  const launchOptions = { args: ["--no-sandbox"] };
+  try {
+    return await chromium.launch(launchOptions);
+  } catch (err) {
+    if (!isMissingBrowserError(err)) throw err;
+    const { existsSync } = await import("node:fs");
+    for (const executablePath of SYSTEM_CHROME_EXECUTABLES) {
+      if (!existsSync(executablePath)) continue;
+      try {
+        return await chromium.launch({ ...launchOptions, executablePath });
+      } catch {
+        // Try the next candidate; the original error is rethrown below.
+      }
+    }
+    throw err;
+  }
+}
+
+// NOTE: no shared `chromiumUnavailableReason` here on purpose — each caller's
+// message should name ITS OWN fallback (e.g. `take-design-screenshot.ts`
+// points at `run-design-audit`; the Figma SVG export points at `export-svg`),
+// so that stays a small, action-local export next to each call site.
diff --git a/templates/design/server/plugins/db.ts b/templates/design/server/plugins/db.ts
index 268771838d..d175a42e73 100644
--- a/templates/design/server/plugins/db.ts
+++ b/templates/design/server/plugins/db.ts
@@ -356,8 +356,49 @@ ALTER TABLE design_files ADD COLUMN IF NOT EXISTS content_operation_result_hash
  * drops, renames, or retypes anything — and any failure here is logged and
  * swallowed so it can never fail boot.
  */
+/**
+ * Best-effort unique index guarding against the add-localhost-screens
+ * cross-request race: two concurrent calls placing the same localhost route
+ * each see "no existing design_files row" from their own snapshot and both
+ * insert a fresh row using the same deterministic filename for that route
+ * (see actions/add-localhost-screens.ts). A unique index on
+ * (design_id, filename) makes the losing insert fail instead of silently
+ * creating an overlapping duplicate screen.
+ *
+ * This intentionally does NOT live in `runDesignMigrations` above:
+ * `CREATE UNIQUE INDEX` fails outright against any database that already
+ * contains a duplicate (design_id, filename) pair — e.g. from this exact race
+ * having already fired before this fix shipped — and `runMigrations` has no
+ * way to tolerate that failure class (only lock-timeout / duplicate-column /
+ * permission errors are swallowed there). A failed migration entry blocks
+ * every later entry in the list forever: it crashes the process outright in
+ * local dev, and on serverless it silently stops applying anything past it on
+ * every cold start. So this runs as its own best-effort step instead: created
+ * when possible, safely skipped (with a warning) when legacy duplicates block
+ * it. `add-localhost-screens.ts`'s insert path tolerates either outcome — it
+ * catches a real unique-violation from this index and falls back to updating
+ * the row that won the race, and is a no-op/no-crash path when the index
+ * isn't present yet.
+ */
+async function ensureDesignFilesUniqueIndex(): Promise<void> {
+  try {
+    await getDbExec().execute(
+      `CREATE UNIQUE INDEX IF NOT EXISTS design_files_design_filename_unique_idx ON design_files (design_id, filename)`,
+    );
+  } catch (err) {
+    console.warn(
+      "[db] design_files_design_filename_unique_idx not created — likely " +
+        "pre-existing duplicate (design_id, filename) rows from the " +
+        "add-localhost-screens race predating this fix. New concurrent " +
+        "inserts remain best-effort until the duplicates are cleaned up:",
+      err instanceof Error ? err.message : err,
+    );
+  }
+}
+
 export default async (nitroApp: any): Promise<void> => {
   await runDesignMigrations(nitroApp);
+  await ensureDesignFilesUniqueIndex();
   try {
     const summary = await ensureAdditiveColumns({
       db: getDbExec(),
diff --git a/templates/design/server/source-workspace.ts b/templates/design/server/source-workspace.ts
index 585f93d0b2..da78dbc1c2 100644
--- a/templates/design/server/source-workspace.ts
+++ b/templates/design/server/source-workspace.ts
@@ -211,6 +211,70 @@ export async function readLiveSourceFile(file: SourceWorkspaceFile): Promise<{
   };
 }
 
+/**
+ * A caller-supplied editor snapshot has two distinct identities:
+ *
+ * - `content` is the working copy the mutation must transform (it may contain
+ *   unsaved local edits), while
+ * - `expectedVersionHash` is the live source version that working copy is
+ *   allowed to replace.
+ *
+ * Hashing `currentContent` for both roles creates a false conflict whenever a
+ * local working copy is legitimately ahead of the persisted/live base. This
+ * helper accepts that working copy only when its SQL revision still matches
+ * and the live document is either the persisted base it was derived from or
+ * the working copy itself (for callers that already published it to Yjs).
+ * Any third live value is a genuine concurrent edit and fails closed. The
+ * returned live hash must be passed to `writeInlineSourceFile`, whose
+ * read-check-write lock closes the race after this preparation step.
+ */
+export class SourceWorkspaceEditConflictError extends Error {
+  constructor(
+    message = "Source file changed since the editor snapshot was prepared.",
+  ) {
+    super(message);
+    this.name = "SourceWorkspaceEditConflictError";
+  }
+}
+
+export async function prepareInlineSourceEdit(args: {
+  file: SourceWorkspaceFile;
+  currentContent?: string;
+  revision?: string;
+}): Promise<{ content: string; expectedVersionHash: string }> {
+  const live = await readLiveSourceFile(args.file);
+
+  if (args.currentContent === undefined) {
+    return {
+      content: live.content,
+      expectedVersionHash: live.versionHash,
+    };
+  }
+
+  if (!args.revision) {
+    throw new SourceWorkspaceEditConflictError(
+      "A source revision is required with current editor content.",
+    );
+  }
+  if (!args.file.updatedAt || args.revision !== args.file.updatedAt) {
+    throw new SourceWorkspaceEditConflictError();
+  }
+
+  const persistedVersionHash = sourceContentHash(args.file.content ?? "");
+  const workingVersionHash = sourceContentHash(args.currentContent);
+  if (
+    live.versionHash !== persistedVersionHash &&
+    live.versionHash !== workingVersionHash
+  ) {
+    throw new SourceWorkspaceEditConflictError();
+  }
+
+  return {
+    content: args.currentContent,
+    expectedVersionHash: live.versionHash,
+  };
+}
+
 export async function writeInlineSourceFile(args: {
   designId: string;
   file: SourceWorkspaceFile;
diff --git a/templates/design/shared/board-file.ts b/templates/design/shared/board-file.ts
index 93bb6c7e7a..cda74091c4 100644
--- a/templates/design/shared/board-file.ts
+++ b/templates/design/shared/board-file.ts
@@ -680,8 +680,19 @@ export function stripBoardSurfaceOffsetFromCoord(value: number): number {
  * coordinate space. This is the pure seam used by
  * `handleOverviewPrimitiveReparent` (DesignEditor.tsx).
  *
- * Both inputs are normalized with `stripBoardSurfaceOffsetFromCoord` first:
- * a source that was persisted in board-iframe viewport coordinates
+ * The flat subtraction below is only correct when both `source` and `target`
+ * are already expressed in the SAME coordinate space — historically that
+ * meant "both are direct children of the screen root", because callers used
+ * to read a node's own inline left/top verbatim (parent-relative, not
+ * root-relative). DesignEditor.tsx's `getAbsolutePositioningForNodeInHtml`
+ * now resolves both inputs with an ancestor walk
+ * (`authoredElementPosition`) up to the screen root before calling this, so
+ * the subtraction is valid regardless of how deeply either node is nested —
+ * dropping a node into a container that's itself nested inside another frame
+ * no longer produces a garbage delta.
+ *
+ * Both inputs are also normalized with `stripBoardSurfaceOffsetFromCoord`
+ * first: a source that was persisted in board-iframe viewport coordinates
  * (boardCoord + 65536 — see BOARD_SURFACE_CONTENT_OFFSET_PX) is rebased to
  * board space before subtracting the target's origin, so the child's new
  * left/top always comes out parent-relative regardless of which upstream
diff --git a/templates/design/shared/canvas-math.test.ts b/templates/design/shared/canvas-math.test.ts
index 5207b46370..1acc88cca6 100644
--- a/templates/design/shared/canvas-math.test.ts
+++ b/templates/design/shared/canvas-math.test.ts
@@ -25,6 +25,7 @@ import {
   resizeFrameFromDelta,
   resizeFrameGroupFromDelta,
   resizeRotatedFrameFromDelta,
+  resizeRotatedFrameFromDeltaWithSnap,
   rotateFrameGroupAroundCenter,
   rotatePoint,
   rotatedRectIntersects,
@@ -979,6 +980,245 @@ describe("rotation-aware resize", () => {
   });
 });
 
+describe("resizeRotatedFrameFromDeltaWithSnap", () => {
+  const snapOptions = {
+    thresholdScreenPx: 8,
+    zoom: 100,
+  };
+
+  it("matches the unsnapped rotated resize when no sibling is close enough to snap", () => {
+    const origin = { x: 100, y: 100, width: 200, height: 150, rotation: 30 };
+    const unsnapped = resizeRotatedFrameFromDelta(origin, "se", 40, 20);
+    const { frame, guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "se",
+      40,
+      20,
+      [{ id: "far", geometry: { x: 5000, y: 5000, width: 100, height: 100 } }],
+      snapOptions,
+    );
+    expect(frame.x).toBeCloseTo(unsnapped.x);
+    expect(frame.y).toBeCloseTo(unsnapped.y);
+    expect(frame.width).toBeCloseTo(unsnapped.width);
+    expect(frame.height).toBeCloseTo(unsnapped.height);
+    expect(guides).toEqual([]);
+  });
+
+  it("falls back to the plain (non-rotated) snap path when rotation is 0", () => {
+    const origin = { x: 0, y: 0, width: 100, height: 100 };
+    // A sibling positioned so its left edge sits just past the resized right
+    // edge, within the snap threshold once converted from screen px.
+    const stationary = [
+      { id: "sibling", geometry: { x: 145, y: 0, width: 50, height: 50 } },
+    ];
+    const { frame, guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "e",
+      40,
+      0,
+      stationary,
+      snapOptions,
+    );
+    const direct = computeResizeSnap(
+      resizeFrameFromDelta(origin, "e", 40, 0),
+      stationary,
+      "e",
+      snapOptions,
+    );
+    expect(frame).toEqual(direct.frame);
+    expect(guides).toEqual(direct.guides);
+  });
+
+  it("snaps a slightly-rotated frame's world AABB edge against a nearby sibling edge", () => {
+    // Documented approximation (see resizeRotatedFrameFromDeltaWithSnap's own
+    // doc comment): snapping compares the frame's actual world-space AABB
+    // against stationary siblings' world bounds, with the handle mapped by
+    // nearest quadrant (15° → quadrant 0, "e" stays "e"). A sibling whose
+    // left edge sits just inside the unsnapped AABB's right edge should pull
+    // the resize so the AABB right edge lands (approximately, cos² factor at
+    // off-axis angles) on the sibling's left edge.
+    const origin = { x: 0, y: 0, width: 100, height: 100, rotation: 15 };
+    const unsnapped = resizeRotatedFrameFromDelta(origin, "e", 44, 0);
+    const unsnappedRight = getRotatedFrameAABB(unsnapped).right;
+    const siblingLeft = unsnappedRight - 6;
+    const stationary = [
+      {
+        id: "sibling",
+        geometry: { x: siblingLeft, y: 0, width: 50, height: 50 },
+      },
+    ];
+    const { frame, guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "e",
+      44,
+      0,
+      stationary,
+      snapOptions,
+    );
+    expect(frame.rotation).toBe(15);
+    expect(guides.length).toBeGreaterThan(0);
+    // The world AABB right edge lands on the sibling's left edge (within the
+    // documented off-axis approximation tolerance), pulling the frame in.
+    expect(
+      Math.abs(getRotatedFrameAABB(frame).right - siblingLeft),
+    ).toBeLessThan(1);
+    expect(frame.width).toBeLessThan(unsnapped.width);
+  });
+
+  it("snaps along the correct world axis at 90°: dragging the local east edge snaps the world BOTTOM edge", () => {
+    // At 90° the local east edge faces due south, so a downward drag grows
+    // the frame's world-space height. A sibling whose top edge sits just past
+    // the unsnapped world bottom must pull the resize down to meet it — an
+    // x-axis (unrotated-local) comparison would find nothing to snap to.
+    const origin = { x: 0, y: 0, width: 100, height: 100, rotation: 90 };
+    const unsnapped = resizeRotatedFrameFromDelta(origin, "e", 0, 40);
+    const unsnappedBottom = getRotatedFrameAABB(unsnapped).bottom;
+    expect(unsnappedBottom).toBeCloseTo(140);
+    const stationary = [
+      {
+        id: "below",
+        geometry: { x: 0, y: unsnappedBottom + 5, width: 100, height: 50 },
+      },
+    ];
+    const { frame, guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "e",
+      0,
+      40,
+      stationary,
+      snapOptions,
+    );
+    expect(frame.rotation).toBe(90);
+    expect(guides.length).toBeGreaterThan(0);
+    // Exact at axis-aligned rotations: the world bottom edge lands flush on
+    // the sibling's top edge, growing the local width from 140 to 145.
+    expect(getRotatedFrameAABB(frame).bottom).toBeCloseTo(unsnappedBottom + 5);
+    expect(frame.width).toBeCloseTo(145);
+  });
+
+  it("snaps along the correct world axis at 180°: dragging the local east edge snaps the world LEFT edge", () => {
+    const origin = { x: 0, y: 0, width: 100, height: 100, rotation: 180 };
+    // At 180° the local east edge faces due west: drag left to grow.
+    const unsnapped = resizeRotatedFrameFromDelta(origin, "e", -40, 0);
+    const unsnappedLeft = getRotatedFrameAABB(unsnapped).left;
+    expect(unsnappedLeft).toBeCloseTo(-40);
+    const stationary = [
+      {
+        id: "leftward",
+        geometry: { x: unsnappedLeft - 5 - 50, y: 0, width: 50, height: 100 },
+      },
+    ];
+    const { frame, guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "e",
+      -40,
+      0,
+      stationary,
+      snapOptions,
+    );
+    expect(frame.rotation).toBe(180);
+    expect(guides.length).toBeGreaterThan(0);
+    expect(getRotatedFrameAABB(frame).left).toBeCloseTo(unsnappedLeft - 5);
+    expect(frame.width).toBeCloseTo(145);
+  });
+
+  it("snaps along the correct world axis at 270°: dragging the local east edge snaps the world TOP edge", () => {
+    const origin = { x: 0, y: 0, width: 100, height: 100, rotation: 270 };
+    // At 270° the local east edge faces due north: drag up to grow.
+    const unsnapped = resizeRotatedFrameFromDelta(origin, "e", 0, -40);
+    const unsnappedTop = getRotatedFrameAABB(unsnapped).top;
+    expect(unsnappedTop).toBeCloseTo(-40);
+    const stationary = [
+      {
+        id: "above",
+        geometry: { x: 0, y: unsnappedTop - 5 - 50, width: 100, height: 50 },
+      },
+    ];
+    const { frame, guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "e",
+      0,
+      -40,
+      stationary,
+      snapOptions,
+    );
+    expect(frame.rotation).toBe(270);
+    expect(guides.length).toBeGreaterThan(0);
+    expect(getRotatedFrameAABB(frame).top).toBeCloseTo(unsnappedTop - 5);
+    expect(frame.width).toBeCloseTo(145);
+  });
+
+  it("skips snapping entirely (never wrong-axis) when the rotation is far off-axis", () => {
+    // 45° is the farthest possible from any axis-aligned orientation: the
+    // frame's true edges match no axis-aligned box, so snapping is skipped
+    // (no guides) and the resize is exactly the unsnapped rotated resize.
+    const origin = { x: 0, y: 0, width: 100, height: 100, rotation: 45 };
+    const unsnapped = resizeRotatedFrameFromDelta(origin, "e", 30, 30);
+    const aabb = getRotatedFrameAABB(unsnapped);
+    // Siblings hugging every side of the unsnapped AABB — any snap attempt on
+    // any axis would find a candidate within threshold.
+    const stationary = [
+      {
+        id: "right",
+        geometry: { x: aabb.right + 4, y: 0, width: 50, height: 50 },
+      },
+      {
+        id: "below",
+        geometry: { x: 0, y: aabb.bottom + 4, width: 50, height: 50 },
+      },
+    ];
+    const { frame, guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "e",
+      30,
+      30,
+      stationary,
+      snapOptions,
+    );
+    expect(guides).toEqual([]);
+    expect(frame.x).toBeCloseTo(unsnapped.x);
+    expect(frame.y).toBeCloseTo(unsnapped.y);
+    expect(frame.width).toBeCloseTo(unsnapped.width);
+    expect(frame.height).toBeCloseTo(unsnapped.height);
+  });
+
+  it("skips snapping (but still resizes) when preserveAspectRatio is requested", () => {
+    const origin = { x: 0, y: 0, width: 200, height: 100, rotation: 20 };
+    const stationary = [
+      { id: "sibling", geometry: { x: 500, y: 0, width: 50, height: 50 } },
+    ];
+    const { frame, guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "se",
+      40,
+      0,
+      stationary,
+      { ...snapOptions, preserveAspectRatio: true },
+      { preserveAspectRatio: true },
+    );
+    expect(guides).toEqual([]);
+    expect(frame.width / frame.height).toBeCloseTo(
+      origin.width / origin.height,
+    );
+  });
+
+  it("bypasses snapping when the meta/ctrl bypass flag is set", () => {
+    const origin = { x: 0, y: 0, width: 100, height: 100, rotation: 15 };
+    const stationary = [
+      { id: "sibling", geometry: { x: 145, y: 0, width: 50, height: 50 } },
+    ];
+    const { guides } = resizeRotatedFrameFromDeltaWithSnap(
+      origin,
+      "e",
+      44,
+      0,
+      stationary,
+      { ...snapOptions, bypass: true },
+    );
+    expect(guides).toEqual([]);
+  });
+});
+
 describe("rotatedRectIntersects", () => {
   function boundsAndCenterOf(geometry: FrameGeometry) {
     const bounds = getFrameBounds(geometry);
diff --git a/templates/design/shared/canvas-math.ts b/templates/design/shared/canvas-math.ts
index ec94f392b0..3977260a98 100644
--- a/templates/design/shared/canvas-math.ts
+++ b/templates/design/shared/canvas-math.ts
@@ -1228,51 +1228,34 @@ function projectionsOverlap(
  * For `origin.rotation` falsy this is identical to calling
  * `resizeFrameFromDelta` directly.
  */
-export function resizeRotatedFrameFromDelta(
+/**
+ * Shared re-anchor step used by both resizeRotatedFrameFromDelta and its
+ * snap-aware counterpart below: given the frame's ORIGIN geometry (still
+ * carrying its rotation) and a candidate RESIZED-LOCAL geometry (unrotated,
+ * already grown/shrunk along the frame's own local axes — optionally
+ * adjusted by a snap pass in between), translates the resized-local geometry
+ * so the same handle-opposite anchor point (or the frame's own center, for
+ * an alt/option "resize from center" drag) stays fixed in WORLD space once
+ * rotation is re-applied. See resizeRotatedFrameFromDelta's original inline
+ * comment (kept there) for why alt-resize anchors on the center instead of
+ * the opposite corner/edge.
+ */
+function reanchorRotatedResizeToWorld(
   origin: FrameGeometry,
   handle: ResizeHandle,
-  worldDx: number,
-  worldDy: number,
-  options: ResizeFrameOptions = {},
+  degrees: number,
+  resizedLocal: FrameGeometry,
+  options: Pick<ResizeFrameOptions, "resizeFromCenter">,
 ): FrameGeometry {
-  const degrees = origin.rotation ?? 0;
-  if (!degrees) {
-    return resizeFrameFromDelta(origin, handle, worldDx, worldDy, options);
-  }
-
   const originCenter = {
     x: origin.x + origin.width / 2,
     y: origin.y + origin.height / 2,
   };
-  // Alt/option resize (`resizeFromCenter`) already grows the frame
-  // symmetrically about its own center in LOCAL space (resizeFrameFromDelta
-  // below keeps the center fixed on both axes for that mode). To keep that
-  // center fixed in WORLD space too — matching Figma, where alt-resizing a
-  // rotated frame grows around its visual center rather than pivoting off an
-  // opposite corner — the re-anchor step below must use the center as its
-  // fixed point instead of the handle's opposite corner/edge. Using the
-  // center as the anchor is a no-op for the rotation (a point rotates around
-  // itself unchanged), so it stays put in world space by construction.
-  // Non-center (default) resizes keep anchoring on the opposite corner/edge
-  // so that world-fixed-anchor behavior is unchanged.
   const anchorLocalBefore = options.resizeFromCenter
     ? originCenter
     : getResizeAnchorPoint(origin, handle);
   const anchorWorld = rotatePoint(anchorLocalBefore, originCenter, degrees);
 
-  // Map the world-space pointer delta into the frame's own unrotated axes so
-  // dragging "outward along the handle" behaves the same regardless of how
-  // the frame is rotated.
-  const localDelta = rotateVector({ x: worldDx, y: worldDy }, -degrees);
-
-  const resizedLocal = resizeFrameFromDelta(
-    { ...origin, rotation: undefined },
-    handle,
-    localDelta.x,
-    localDelta.y,
-    options,
-  );
-
   const centerAfterLocal = {
     x: resizedLocal.x + resizedLocal.width / 2,
     y: resizedLocal.y + resizedLocal.height / 2,
@@ -1298,6 +1281,221 @@ export function resizeRotatedFrameFromDelta(
   };
 }
 
+export function resizeRotatedFrameFromDelta(
+  origin: FrameGeometry,
+  handle: ResizeHandle,
+  worldDx: number,
+  worldDy: number,
+  options: ResizeFrameOptions = {},
+): FrameGeometry {
+  const degrees = origin.rotation ?? 0;
+  if (!degrees) {
+    return resizeFrameFromDelta(origin, handle, worldDx, worldDy, options);
+  }
+
+  // Map the world-space pointer delta into the frame's own unrotated axes so
+  // dragging "outward along the handle" behaves the same regardless of how
+  // the frame is rotated.
+  const localDelta = rotateVector({ x: worldDx, y: worldDy }, -degrees);
+
+  const resizedLocal = resizeFrameFromDelta(
+    { ...origin, rotation: undefined },
+    handle,
+    localDelta.x,
+    localDelta.y,
+    options,
+  );
+
+  return reanchorRotatedResizeToWorld(
+    origin,
+    handle,
+    degrees,
+    resizedLocal,
+    options,
+  );
+}
+
+/** Resize handles in clockwise screen order (y grows downward), so rotating a
+ *  handle by one 90° quadrant clockwise is a +2 step through this ring. */
+const RESIZE_HANDLES_CLOCKWISE: readonly ResizeHandle[] = [
+  "n",
+  "ne",
+  "e",
+  "se",
+  "s",
+  "sw",
+  "w",
+  "nw",
+];
+
+/** Maps a local resize handle to the world-space direction it points after
+ *  rotating the frame clockwise by `quadrants` 90° steps (CSS-positive
+ *  rotation is clockwise on screen): at 90°, the local east handle points
+ *  due south in world space, so "e" → "s". */
+function rotateHandleByQuadrants(
+  handle: ResizeHandle,
+  quadrants: number,
+): ResizeHandle {
+  const index = RESIZE_HANDLES_CLOCKWISE.indexOf(handle);
+  return RESIZE_HANDLES_CLOCKWISE[(index + 2 * ((quadrants % 4) + 4)) % 8]!;
+}
+
+/**
+ * Beyond this many degrees away from the nearest axis-aligned orientation
+ * (0/90/180/270), resize snapping is skipped for rotated frames: the frame's
+ * true edges diverge too far from any axis-aligned box for edge/center
+ * alignment against siblings to mean anything, and a wrong-axis guide is
+ * worse than none.
+ */
+const ROTATED_RESIZE_SNAP_MAX_OFF_AXIS_DEGREES = 30;
+
+/**
+ * Rotation-aware counterpart to resizeRotatedFrameFromDelta that also snaps
+ * to nearby stationary siblings, matching computeResizeSnap's contract for
+ * the unrotated group-resize path (CV-style: same threshold/guide shape).
+ *
+ * How rotated snapping works (see WORK ITEM 2 in the canvas bug pass this was
+ * added for, reworked in the pre-ship review): the unsnapped rotated resize
+ * is computed first, then its actual world-space AABB is snapped against
+ * stationary siblings' world bounds with the exact same computeResizeSnap
+ * machinery a non-rotated resize uses — with the resize handle mapped into
+ * its world orientation by the frame's nearest 90° quadrant (at ~90° the
+ * local east edge faces due south in world space, so "e" snaps the AABB's
+ * bottom edge; at ~180° it faces west; etc.). Any snap offset is then fed
+ * back into the rotated resize as extra world pointer travel, so anchoring
+ * stays exact. This is edge-exact at 0/90/180/270 (the AABB edges ARE the
+ * frame's edges there) and approximate in between (pointer travel maps to
+ * AABB-edge movement with a cos² factor); once the rotation is more than
+ * ROTATED_RESIZE_SNAP_MAX_OFF_AXIS_DEGREES from every axis-aligned
+ * orientation, snapping is skipped entirely (no guides) rather than snapping
+ * an axis that no longer matches what the user sees.
+ */
+export function resizeRotatedFrameFromDeltaWithSnap(
+  origin: FrameGeometry,
+  handle: ResizeHandle,
+  worldDx: number,
+  worldDy: number,
+  stationary: FrameEntry[],
+  snapOptions: ResizeSnapOptions,
+  options: ResizeFrameOptions = {},
+): { frame: FrameGeometry; guides: AlignmentGuide[] } {
+  const degrees = origin.rotation ?? 0;
+  if (!degrees) {
+    const resizedLocal = resizeFrameFromDelta(
+      origin,
+      handle,
+      worldDx,
+      worldDy,
+      options,
+    );
+    return computeResizeSnap(resizedLocal, stationary, handle, snapOptions);
+  }
+
+  const localDelta = rotateVector({ x: worldDx, y: worldDy }, -degrees);
+
+  const resizedLocal = resizeFrameFromDelta(
+    { ...origin, rotation: undefined },
+    handle,
+    localDelta.x,
+    localDelta.y,
+    options,
+  );
+
+  // Snapping is skipped outright for a rotated frame whenever the caller's
+  // aspect-preserve flag is set (shift-held or the K scale tool):
+  // independently snapping x and y against the local-bounds approximation
+  // above would distort the locked ratio the aspect-preserving resize above
+  // just computed, and computeAspectPreservingResizeSnap's own single-locked-
+  // ratio reasoning only holds against the frame's true (rotated) shape, not
+  // this approximation. No snap beats a wrong one here.
+  if (snapOptions.preserveAspectRatio || snapOptions.bypass) {
+    return {
+      frame: reanchorRotatedResizeToWorld(
+        origin,
+        handle,
+        degrees,
+        resizedLocal,
+        options,
+      ),
+      guides: [],
+    };
+  }
+
+  const unsnapped = reanchorRotatedResizeToWorld(
+    origin,
+    handle,
+    degrees,
+    resizedLocal,
+    options,
+  );
+
+  // Map the resize handle into its world orientation by the nearest 90°
+  // quadrant (see the doc comment above). Far off-axis, skip snapping
+  // outright — a wrong-axis snap/guide is worse than none.
+  const normalizedDegrees = ((degrees % 360) + 360) % 360;
+  const nearestQuadrant = Math.round(normalizedDegrees / 90) % 4;
+  const offAxisDegrees = Math.abs(
+    normalizedDegrees - Math.round(normalizedDegrees / 90) * 90,
+  );
+  if (offAxisDegrees > ROTATED_RESIZE_SNAP_MAX_OFF_AXIS_DEGREES) {
+    return { frame: unsnapped, guides: [] };
+  }
+
+  const worldHandle = rotateHandleByQuadrants(handle, nearestQuadrant);
+  const aabb = getRotatedFrameAABB(unsnapped);
+  const worldBox: FrameGeometry = {
+    x: aabb.left,
+    y: aabb.top,
+    width: aabb.width,
+    height: aabb.height,
+  };
+  // Min sizes are per-axis, so they swap with the axes at 90/270.
+  const worldSnapOptions =
+    nearestQuadrant % 2 === 1
+      ? {
+          ...snapOptions,
+          minWidth: snapOptions.minHeight,
+          minHeight: snapOptions.minWidth,
+        }
+      : snapOptions;
+
+  const snap = computeResizeSnap(
+    worldBox,
+    stationary,
+    worldHandle,
+    worldSnapOptions,
+  );
+  if (snap.guides.length === 0) {
+    return { frame: unsnapped, guides: [] };
+  }
+
+  // The snap moved the dragged world edge(s) of the AABB; express that
+  // movement as extra world pointer travel and recompute the rotated resize,
+  // so the anchor-fixing translation stays exact instead of being applied to
+  // an already-snapped box.
+  const snapDx = handleAffectsEast(worldHandle)
+    ? snap.frame.x + snap.frame.width - (worldBox.x + worldBox.width)
+    : handleAffectsWest(worldHandle)
+      ? snap.frame.x - worldBox.x
+      : 0;
+  const snapDy = handleAffectsSouth(worldHandle)
+    ? snap.frame.y + snap.frame.height - (worldBox.y + worldBox.height)
+    : handleAffectsNorth(worldHandle)
+      ? snap.frame.y - worldBox.y
+      : 0;
+
+  return {
+    frame: resizeRotatedFrameFromDelta(
+      origin,
+      handle,
+      worldDx + snapDx,
+      worldDy + snapDy,
+      options,
+    ),
+    guides: snap.guides,
+  };
+}
+
 /** The local (unrotated) point that a given resize handle keeps fixed: the
  *  edge/corner opposite the handle, or the center of an axis the handle
  *  doesn't affect at all (e.g. "n" leaves the horizontal axis untouched). */
diff --git a/templates/design/shared/code-layer.test.ts b/templates/design/shared/code-layer.test.ts
index d7911e0698..88543a7db3 100644
--- a/templates/design/shared/code-layer.test.ts
+++ b/templates/design/shared/code-layer.test.ts
@@ -1494,6 +1494,49 @@ describe("moveNodeBetweenDocuments", () => {
     expect(movedIdx).toBeGreaterThan(templateCloseIdx);
   });
 
+  it("no-anchor body-append strips absolute positioning when the destination <body> is a flex container", () => {
+    const sourceHtml = `<body><div data-agent-native-node-id="move-me" style="position: absolute; left: 24px; top: 48px; color: red">Move</div></body>`;
+    const destHtml = `<body style="display: flex; flex-direction: column; gap: 16px"><div data-agent-native-node-id="existing">Existing</div></body>`;
+
+    const result = moveNodeBetweenDocuments(sourceHtml, destHtml, {
+      nodeId: "move-me",
+    });
+
+    expect(result.status).toBe("applied");
+    // Same normalization as the anchored `placement: "inside"` branch: the
+    // moved node becomes a flow child of the flex body, so its stale
+    // absolute offsets must be stripped or it renders detached from the
+    // body's ordering/gap/alignment.
+    const movedIdx = result.destHtml.indexOf(
+      `data-agent-native-node-id="move-me"`,
+    );
+    expect(movedIdx).toBeGreaterThan(-1);
+    const movedTag = result.destHtml.slice(
+      result.destHtml.lastIndexOf("<", movedIdx),
+      result.destHtml.indexOf(">", movedIdx) + 1,
+    );
+    expect(movedTag).not.toContain("position: absolute");
+    expect(movedTag).not.toContain("left:");
+    expect(movedTag).not.toContain("top:");
+    // Non-positioning styles on the moved root survive.
+    expect(movedTag).toContain("color: red");
+  });
+
+  it("no-anchor body-append keeps absolute positioning when the destination <body> is a plain flow container", () => {
+    const sourceHtml = `<body><div data-agent-native-node-id="move-me" style="position: absolute; left: 24px; top: 48px">Move</div></body>`;
+    const destHtml = `<body><div data-agent-native-node-id="existing">Existing</div></body>`;
+
+    const result = moveNodeBetweenDocuments(sourceHtml, destHtml, {
+      nodeId: "move-me",
+    });
+
+    expect(result.status).toBe("applied");
+    // A non-flex/grid body is a normal positioning context; the moved node's
+    // explicit absolute placement is intentional and must be preserved.
+    expect(result.destHtml).toContain("position: absolute");
+    expect(result.destHtml).toContain("left: 24px");
+  });
+
   it("anchored insert (placement inside) never lands inside a nested <template> even when the anchor itself precedes templates", () => {
     const sourceHtml = `<body><div data-agent-native-node-id="move-me">Move</div></body>`;
     const destHtml =
@@ -2000,6 +2043,41 @@ describe("style edit property normalization for fill layers", () => {
     expect(patch.content).toContain("background-image");
   });
 
+  it("keeps quoted image URLs intact across sequential style patches", () => {
+    const imagePatch = applyVisualEdit(html, {
+      kind: "style",
+      target: { selector: "#cta" },
+      property: "backgroundImage",
+      value:
+        'url("https://example.com/fill.png") /* agent-native-image-fit:tile */',
+    } as EditIntent);
+    const repeatPatch = applyVisualEdit(imagePatch.content, {
+      kind: "style",
+      target: { selector: "#cta" },
+      property: "backgroundRepeat",
+      value: "repeat",
+    } as EditIntent);
+    const positionPatch = applyVisualEdit(repeatPatch.content, {
+      kind: "style",
+      target: { selector: "#cta" },
+      property: "backgroundPosition",
+      value: "top left",
+    } as EditIntent);
+
+    expect(positionPatch.result.status).toBe("applied");
+    expect(positionPatch.content).toContain(
+      "url(&quot;https://example.com/fill.png&quot;)",
+    );
+    expect(positionPatch.content).not.toContain("&amp;quot;");
+    const projection = buildCodeLayerProjection(positionPatch.content);
+    const button = projection.nodes.find((node) => node.tag === "button");
+    expect(button?.style["background-image"]).toContain(
+      'url("https://example.com/fill.png")',
+    );
+    expect(button?.style["background-repeat"]).toBe("repeat");
+    expect(button?.style["background-position"]).toBe("top left");
+  });
+
   it("rejects a backgroundImage url() with a javascript: scheme", () => {
     const patch = applyVisualEdit(html, {
       kind: "style",
diff --git a/templates/design/shared/code-layer.ts b/templates/design/shared/code-layer.ts
index 76f1450c92..018408dd0e 100644
--- a/templates/design/shared/code-layer.ts
+++ b/templates/design/shared/code-layer.ts
@@ -1007,7 +1007,11 @@ function getAttribute(
 
 function attributeValue(element: ParsedElement, name: string): string | null {
   const value = getAttribute(element, name)?.value;
-  if (typeof value === "string") return value;
+  // Parsed attributes contain source text, so quoted values may still carry
+  // entities emitted by an earlier deterministic patch. Decode before using
+  // them semantically or reserializing; otherwise sequential style edits turn
+  // `&quot;` into `&amp;quot;` on every pass and corrupt quoted CSS url() values.
+  if (typeof value === "string") return decodeBasicHtmlEntities(value);
   if (value === true) return "";
   return null;
 }
@@ -3143,6 +3147,7 @@ function applyMoveNodeEdit(
   element: ParsedElement,
   anchor: ParsedElement,
   intent: MoveNodeEditIntent,
+  destinationParent?: ParsedElement,
 ): { content: string; capability: EditCapability } | PatchResultStatus {
   if (element.index === anchor.index) return "conflict";
   if (anchor.start >= element.start && anchor.end <= element.end) {
@@ -3152,7 +3157,14 @@ function applyMoveNodeEdit(
     return "unsupported";
   }
 
-  const fragment = html.slice(element.start, element.end);
+  const sourceParentIndex = element.parentIndex;
+  const entersNewParent =
+    destinationParent !== undefined &&
+    sourceParentIndex !== destinationParent.index;
+  const rawFragment = html.slice(element.start, element.end);
+  const fragment = entersNewParent
+    ? prepareMovedFragmentForParent(rawFragment, destinationParent)
+    : rawFragment;
   const withoutTarget = `${html.slice(0, element.start)}${html.slice(
     element.end,
   )}`;
@@ -3178,6 +3190,51 @@ function applyMoveNodeEdit(
   };
 }
 
+/**
+ * Whether children of this element participate in normal flex/grid flow.
+ * Inline style is authoritative for inspector-created auto layout; the class
+ * checks cover authored Tailwind/utility layouts in standalone Alpine files.
+ */
+function isFlowLayoutContainer(element: ParsedElement | undefined): boolean {
+  if (!element) return false;
+  const display = parseStyle(attributeValue(element, "style")).display;
+  if (
+    display === "flex" ||
+    display === "inline-flex" ||
+    display === "grid" ||
+    display === "inline-grid"
+  ) {
+    return true;
+  }
+  const classes = new Set(classList(element));
+  return (
+    classes.has("flex") ||
+    classes.has("inline-flex") ||
+    classes.has("grid") ||
+    classes.has("inline-grid")
+  );
+}
+
+/**
+ * A Figma auto-layout drop makes the moved layer a flow child. Carrying its
+ * former `position:absolute` offsets into the new flex/grid parent leaves it
+ * visually detached from ordering, gap, and alignment even though the layer
+ * tree says it was reparented. Normalize only the moved fragment's root; its
+ * descendants keep their own positioning contexts unchanged.
+ */
+function prepareMovedFragmentForParent(
+  fragment: string,
+  destinationParent: ParsedElement | undefined,
+): string {
+  if (!isFlowLayoutContainer(destinationParent)) return fragment;
+  const fragmentRoot = parseHtmlElements(fragment).find(
+    (element) => element.parentIndex === undefined,
+  );
+  return fragmentRoot
+    ? stripAbsolutePositioningFromChild(fragment, fragmentRoot)
+    : fragment;
+}
+
 /** Generate a fresh unique data-agent-native-node-id value not already in the set. */
 function freshNodeId(usedIds: Set<string>, basis: string): string {
   const base = `an-${hashStable(basis)}`;
@@ -3264,11 +3321,42 @@ function stripAbsolutePositioningFromChild(
   child: ParsedElement,
 ): string {
   const currentStyle = attributeValue(child, "style");
-  if (!currentStyle) return html;
-  const nextStyle = stripStyleProperties(currentStyle, [
-    ...AUTO_LAYOUT_STRIP_PROPS,
-  ]);
-  return replaceOrInsertAttribute(html, child, "style", nextStyle);
+  let nextHtml = currentStyle
+    ? replaceOrInsertAttribute(
+        html,
+        child,
+        "style",
+        stripStyleProperties(currentStyle, [...AUTO_LAYOUT_STRIP_PROPS]),
+      )
+    : html;
+
+  // Source-backed Alpine/Tailwind designs commonly express positioning as
+  // utility classes instead of inline CSS. Once the layer moves into a new
+  // flex/grid parent, those utilities would keep it out of flow even though
+  // the Layers tree shows it as a child. Remove only position-mode utilities;
+  // inset utilities can remain because they are inert for a statically
+  // positioned flex/grid item, and preserving them avoids needless source
+  // churn if the user later makes the layer absolute again.
+  const reparsedRoot = parseHtmlElements(nextHtml).find(
+    (element) => element.parentIndex === undefined,
+  );
+  if (!reparsedRoot) return nextHtml;
+  const classes = classList(reparsedRoot);
+  const flowClasses = classes.filter((token) => {
+    const variants = token.split(":");
+    const utility = variants[variants.length - 1]?.replace(/^!/, "");
+    return (
+      utility !== "absolute" && utility !== "fixed" && utility !== "sticky"
+    );
+  });
+  if (flowClasses.length === classes.length) return nextHtml;
+  nextHtml = replaceOrInsertAttribute(
+    nextHtml,
+    reparsedRoot,
+    "class",
+    flowClasses.join(" "),
+  );
+  return nextHtml;
 }
 
 /**
@@ -4018,7 +4106,19 @@ export function applyVisualEdit(
     const removedLength = element.end - element.start;
     moveInsertAt =
       element.start < rawInsertAt ? rawInsertAt - removedLength : rawInsertAt;
-    edit = applyMoveNodeEdit(html, element, anchorElement, intent);
+    const destinationParent =
+      intent.placement === "inside"
+        ? anchorElement
+        : anchorResolution.node.parentId
+          ? initial.elementByNodeId.get(anchorResolution.node.parentId)
+          : undefined;
+    edit = applyMoveNodeEdit(
+      html,
+      element,
+      anchorElement,
+      intent,
+      destinationParent,
+    );
   }
 
   if (typeof edit === "string") {
@@ -4265,6 +4365,13 @@ export function moveNodeBetweenDocuments(
         : destHtml.length;
       anchorRedirected = true;
     }
+    const destinationParent =
+      placement === "inside"
+        ? anchor
+        : anchor.parentIndex === undefined
+          ? undefined
+          : destElements[anchor.parentIndex];
+    fragment = prepareMovedFragmentForParent(fragment, destinationParent);
     nextDestHtml = `${destHtml.slice(0, insertAt)}${fragment}${destHtml.slice(insertAt)}`;
   } else {
     // Default: find <body> and append inside it, or append at end of doc.
@@ -4281,6 +4388,13 @@ export function moveNodeBetweenDocuments(
     if (isOffsetInsideTemplateInterior(destHtml, insertAt)) {
       insertAt = destHtml.length;
     }
+    // Appending inside <body> makes the moved node a flow child of the body,
+    // exactly like the anchored `placement: "inside"` branch above. When the
+    // destination body is a flex/grid container, carrying the fragment's
+    // former absolute offsets along would leave it visually detached from
+    // the body's ordering/gap/alignment, so run the same normalization
+    // (prepareMovedFragmentForParent no-ops for non-flow bodies).
+    fragment = prepareMovedFragmentForParent(fragment, bodyEl);
     nextDestHtml = `${destHtml.slice(0, insertAt)}${fragment}${destHtml.slice(insertAt)}`;
   }
 
diff --git a/templates/design/shared/component-library.spec.ts b/templates/design/shared/component-library.spec.ts
new file mode 100644
index 0000000000..0ba1db4398
--- /dev/null
+++ b/templates/design/shared/component-library.spec.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  entriesForComponent,
+  scanComponentLibrary,
+  summarizeComponentLibrary,
+} from "./component-library.js";
+
+const indexHtml =
+  "<main>" +
+  '<button data-agent-native-node-id="btn1" data-agent-native-component="PrimaryButton">Save</button>' +
+  '<button data-agent-native-node-id="btn2" data-agent-native-component="PrimaryButton">Submit</button>' +
+  '<div data-agent-native-node-id="card1" data-agent-native-component="Card">Body</div>' +
+  "</main>";
+
+const aboutHtml =
+  "<section>" +
+  '<button data-agent-native-node-id="btn3" data-agent-native-component="SecondaryButton">Cancel</button>' +
+  "</section>";
+
+describe("scanComponentLibrary", () => {
+  it("finds instances across multiple files, preserving file then document order", () => {
+    const entries = scanComponentLibrary([
+      { id: "f1", designId: "d1", filename: "index.html", content: indexHtml },
+      { id: "f2", designId: "d1", filename: "about.html", content: aboutHtml },
+    ]);
+
+    expect(entries.map((e) => e.nodeId)).toEqual([
+      "btn1",
+      "btn2",
+      "card1",
+      "btn3",
+    ]);
+    expect(entries[0]).toMatchObject({
+      name: "PrimaryButton",
+      fileId: "f1",
+      filename: "index.html",
+    });
+    expect(entries[3]).toMatchObject({
+      name: "SecondaryButton",
+      fileId: "f2",
+      filename: "about.html",
+    });
+  });
+
+  it("skips files with empty/missing content instead of throwing", () => {
+    const entries = scanComponentLibrary([
+      { id: "f1", designId: "d1", filename: "empty.html", content: null },
+      { id: "f2", designId: "d1", filename: "about.html", content: aboutHtml },
+    ]);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].fileId).toBe("f2");
+  });
+});
+
+describe("entriesForComponent", () => {
+  const entries = scanComponentLibrary([
+    { id: "f1", designId: "d1", filename: "index.html", content: indexHtml },
+  ]);
+
+  it("filters to a single component name", () => {
+    const matches = entriesForComponent(entries, "PrimaryButton");
+    expect(matches.map((m) => m.nodeId)).toEqual(["btn1", "btn2"]);
+  });
+
+  it("excludes the given (fileId, nodeId) pair", () => {
+    const matches = entriesForComponent(entries, "PrimaryButton", {
+      fileId: "f1",
+      nodeId: "btn1",
+    });
+    expect(matches.map((m) => m.nodeId)).toEqual(["btn2"]);
+  });
+});
+
+describe("summarizeComponentLibrary", () => {
+  it("aggregates one row per component name, sorted alphabetically, with a sample instance", () => {
+    const entries = scanComponentLibrary([
+      { id: "f1", designId: "d1", filename: "index.html", content: indexHtml },
+      { id: "f2", designId: "d1", filename: "about.html", content: aboutHtml },
+    ]);
+    const summary = summarizeComponentLibrary(entries);
+
+    expect(summary.map((s) => s.name)).toEqual([
+      "Card",
+      "PrimaryButton",
+      "SecondaryButton",
+    ]);
+    const primary = summary.find((s) => s.name === "PrimaryButton");
+    expect(primary?.instanceCount).toBe(2);
+    expect(primary?.sampleNodeId).toBe("btn1");
+    expect(primary?.sampleFileId).toBe("f1");
+  });
+});
diff --git a/templates/design/shared/component-library.ts b/templates/design/shared/component-library.ts
new file mode 100644
index 0000000000..54c2f7be69
--- /dev/null
+++ b/templates/design/shared/component-library.ts
@@ -0,0 +1,161 @@
+/**
+ * Component library scan — cross-file component instance discovery.
+ *
+ * `index-components` (and `get-component-details`) only ever look at ONE
+ * design file at a time (the active file, or an explicit `fileId`).
+ * `component_index` metadata is therefore scoped to whichever file was last
+ * indexed, and its `runtimeSelectors` do not reliably span every screen in a
+ * multi-file design.
+ *
+ * "Go to main component" and "Swap instance" both need to find OTHER
+ * instances of a component name that may live on a different screen (design
+ * file) than the one currently open. This module scans a caller-supplied set
+ * of already-fetched design files (any order the caller wants — typically
+ * `createdAt` ascending, oldest/"most original" first) and returns every
+ * component instance found across all of them, in that same order.
+ *
+ * Pure — no DB / IO. Callers fetch file rows (respecting `accessFilter`) and
+ * pass the rows in here.
+ */
+
+import {
+  buildCodeLayerProjection,
+  type CodeLayerSource,
+} from "./code-layer.js";
+import { componentNameFor, isComponentInstance } from "./component-model.js";
+
+export interface ComponentLibraryFile {
+  id: string;
+  designId: string;
+  filename: string;
+  content: string | null;
+}
+
+export interface ComponentLibraryEntry {
+  /** Component name from `data-agent-native-component`. */
+  name: string;
+  fileId: string;
+  filename: string;
+  /** `data-agent-native-node-id` (or fallback) of the instance root. */
+  nodeId: string;
+  /** CSS selector that addresses this instance on its screen. */
+  selector: string;
+}
+
+/**
+ * Scan every file for component instances, preserving the caller's file
+ * order and each file's document order. Files with empty/missing content are
+ * skipped rather than throwing.
+ */
+export function scanComponentLibrary(
+  files: ComponentLibraryFile[],
+): ComponentLibraryEntry[] {
+  const entries: ComponentLibraryEntry[] = [];
+
+  for (const file of files) {
+    const html = file.content ?? "";
+    if (!html) continue;
+
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+
+    const projection = buildCodeLayerProjection(html, {
+      source: codeLayerSource,
+    });
+
+    for (const node of projection.nodes) {
+      if (!isComponentInstance(node)) continue;
+      const name = componentNameFor(node);
+      if (!name) continue;
+
+      // `node.id` is an ephemeral id scoped to this one projection call — it
+      // is NOT the same as the durable `data-agent-native-node-id` attribute
+      // stamped into the HTML (see `ensureCodeLayerNodeIdsInHtml`). Callers
+      // that navigate to / re-select this entry on a LATER read (a different
+      // projection call — e.g. after a `navigate` round-trip) need the stable
+      // attribute value, not this run's ephemeral id, so prefer it here and
+      // only fall back to `node.id` for the rare case a component-annotated
+      // node hasn't been stamped with a durable id yet.
+      const nodeId =
+        node.dataAttributes["data-agent-native-node-id"] ?? node.id;
+
+      entries.push({
+        name,
+        fileId: file.id,
+        filename: file.filename,
+        nodeId,
+        selector: node.selector,
+      });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Filter a scanned library to instances of one component name, optionally
+ * excluding a specific (fileId, nodeId) — typically the instance the caller
+ * is acting on, so it doesn't get offered back as its own "main"/swap
+ * source.
+ */
+export function entriesForComponent(
+  entries: ComponentLibraryEntry[],
+  name: string,
+  exclude?: { fileId: string; nodeId: string },
+): ComponentLibraryEntry[] {
+  return entries.filter((entry) => {
+    if (entry.name !== name) return false;
+    if (
+      exclude &&
+      entry.fileId === exclude.fileId &&
+      entry.nodeId === exclude.nodeId
+    ) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Aggregate scanned entries into one row per distinct component name — the
+ * shape the Swap Instance picker needs (a name to pick, a count, and a
+ * representative instance to source markup/props from).
+ */
+export interface ComponentLibrarySummary {
+  name: string;
+  instanceCount: number;
+  sampleFileId: string;
+  sampleFilename: string;
+  sampleNodeId: string;
+  sampleSelector: string;
+}
+
+export function summarizeComponentLibrary(
+  entries: ComponentLibraryEntry[],
+): ComponentLibrarySummary[] {
+  const byName = new Map<string, ComponentLibrarySummary>();
+
+  for (const entry of entries) {
+    const existing = byName.get(entry.name);
+    if (existing) {
+      existing.instanceCount += 1;
+      continue;
+    }
+    byName.set(entry.name, {
+      name: entry.name,
+      instanceCount: 1,
+      sampleFileId: entry.fileId,
+      sampleFilename: entry.filename,
+      sampleNodeId: entry.nodeId,
+      sampleSelector: entry.selector,
+    });
+  }
+
+  return Array.from(byName.values()).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+}
diff --git a/templates/design/shared/db-conflict.ts b/templates/design/shared/db-conflict.ts
new file mode 100644
index 0000000000..71cce47888
--- /dev/null
+++ b/templates/design/shared/db-conflict.ts
@@ -0,0 +1,27 @@
+/**
+ * True when `err` is a UNIQUE / PRIMARY KEY constraint violation from either
+ * supported driver (Postgres 23505, SQLite SQLITE_CONSTRAINT_UNIQUE /
+ * _PRIMARYKEY). Shared by any action that inserts a row guarded by a
+ * best-effort unique index and needs to recover from a losing race instead of
+ * failing outright — see `design_files_design_filename_unique_idx` in
+ * `server/plugins/db.ts` for the index this is meant to catch a conflict
+ * against, and `add-localhost-screens.ts` / `present-design-variants.ts` for
+ * the adopt-the-winning-row recovery pattern built on top of this check.
+ */
+export function isUniqueConstraintViolation(err: unknown): boolean {
+  const e = err as { code?: unknown; message?: unknown } | null;
+  if (e?.code === "23505") return true;
+  const code = String(e?.code ?? "");
+  if (
+    code === "SQLITE_CONSTRAINT_PRIMARYKEY" ||
+    code === "SQLITE_CONSTRAINT_UNIQUE"
+  ) {
+    return true;
+  }
+  const msg = String(e?.message ?? "").toLowerCase();
+  return (
+    msg.includes("unique constraint") ||
+    msg.includes("primary key constraint") ||
+    msg.includes("duplicate key")
+  );
+}
diff --git a/templates/design/shared/design-source-capabilities.ts b/templates/design/shared/design-source-capabilities.ts
index 1d43ad75a0..a264cf204e 100644
--- a/templates/design/shared/design-source-capabilities.ts
+++ b/templates/design/shared/design-source-capabilities.ts
@@ -7,7 +7,8 @@
  *
  * Relation to `source-mode.ts`:
  * - `DesignBridgeOperation` ("select" | "resolveNodeToFile" | "readFile" |
- *   "applyEdit" | "writeFile" | "captureSnapshot" | "captureState") describes
+ *   "applyEdit" | "writeFile" | "captureSnapshot" | "captureState" |
+ *   "listFiles") describes
  *   the low-level bridge RPC surface.
  * - `DesignCapabilityName` below is the *higher-level* capability vocabulary
  *   that UI panels and agent actions read.  Several capabilities build on one
diff --git a/templates/design/shared/figma-url.spec.ts b/templates/design/shared/figma-url.spec.ts
new file mode 100644
index 0000000000..51335d56d1
--- /dev/null
+++ b/templates/design/shared/figma-url.spec.ts
@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  isFigmaBranchUrl,
+  parseFigmaFileKey,
+  parseFigmaNodeId,
+  parseFigmaUrl,
+} from "./figma-url";
+
+describe("parseFigmaFileKey", () => {
+  it("accepts a raw Figma file key", () => {
+    expect(parseFigmaFileKey("abcDEF_12345")).toBe("abcDEF_12345");
+  });
+
+  it("extracts design, file, and proto URL keys", () => {
+    expect(
+      parseFigmaFileKey("https://www.figma.com/design/abcDEF12345/App"),
+    ).toBe("abcDEF12345");
+    expect(
+      parseFigmaFileKey("https://www.figma.com/file/xyz98765432/System"),
+    ).toBe("xyz98765432");
+    expect(
+      parseFigmaFileKey("https://www.figma.com/proto/protoKey123/Flow"),
+    ).toBe("protoKey123");
+  });
+
+  it("resolves /branch/:branchKey/ to the branch key, not the parent file key", () => {
+    expect(
+      parseFigmaFileKey(
+        "https://www.figma.com/design/parentKey123/App/branch/branchKey456/App-Branch",
+      ),
+    ).toBe("branchKey456");
+  });
+
+  it("resolves a branch URL with a node-id query param to the branch key", () => {
+    expect(
+      parseFigmaFileKey(
+        "https://www.figma.com/design/parentKey123/App/branch/branchKey456/App-Branch?node-id=1-2",
+      ),
+    ).toBe("branchKey456");
+  });
+
+  it("returns null for invalid input", () => {
+    expect(parseFigmaFileKey("https://example.com/nope")).toBeNull();
+    expect(parseFigmaFileKey("")).toBeNull();
+    expect(parseFigmaFileKey(undefined)).toBeNull();
+  });
+});
+
+describe("isFigmaBranchUrl", () => {
+  it("detects branch URLs", () => {
+    expect(
+      isFigmaBranchUrl(
+        "https://www.figma.com/design/parentKey123/App/branch/branchKey456/App-Branch",
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false for non-branch URLs and raw keys", () => {
+    expect(
+      isFigmaBranchUrl("https://www.figma.com/design/abcDEF12345/App"),
+    ).toBe(false);
+    expect(isFigmaBranchUrl("abcDEF12345")).toBe(false);
+    expect(isFigmaBranchUrl(undefined)).toBe(false);
+  });
+});
+
+describe("parseFigmaNodeId", () => {
+  it("passes through an already-normalized colon node id", () => {
+    expect(parseFigmaNodeId("1:2")).toBe("1:2");
+  });
+
+  it("converts dash form to colon form", () => {
+    expect(parseFigmaNodeId("1-2")).toBe("1:2");
+  });
+
+  it("extracts and converts node-id from a query param", () => {
+    expect(
+      parseFigmaNodeId(
+        "https://www.figma.com/design/abcDEF12345/App?node-id=12-345",
+      ),
+    ).toBe("12:345");
+  });
+
+  it("handles an already-encoded node-id query param", () => {
+    expect(
+      parseFigmaNodeId(
+        "https://www.figma.com/design/abcDEF12345/App?node-id=12%3A345",
+      ),
+    ).toBe("12:345");
+  });
+
+  it("converts grouped instance-swap ids (semicolon separated)", () => {
+    expect(parseFigmaNodeId("12-345;678-901")).toBe("12:345;678:901");
+  });
+
+  it("preserves a leading instance-override marker", () => {
+    expect(parseFigmaNodeId("I12-345;678-901")).toBe("I12:345;678:901");
+  });
+
+  it("returns null when no node-id is present", () => {
+    expect(
+      parseFigmaNodeId("https://www.figma.com/design/abcDEF12345/App"),
+    ).toBeNull();
+    expect(parseFigmaNodeId("")).toBeNull();
+    expect(parseFigmaNodeId(undefined)).toBeNull();
+  });
+});
+
+describe("parseFigmaUrl", () => {
+  it("parses fileKey, nodeId, and isBranch together", () => {
+    expect(
+      parseFigmaUrl(
+        "https://www.figma.com/design/parentKey123/App/branch/branchKey456/App-Branch?node-id=1-2",
+      ),
+    ).toEqual({ fileKey: "branchKey456", nodeId: "1:2", isBranch: true });
+  });
+
+  it("parses a plain design URL without a branch", () => {
+    expect(
+      parseFigmaUrl(
+        "https://www.figma.com/design/abcDEF12345/App?node-id=10-20",
+      ),
+    ).toEqual({ fileKey: "abcDEF12345", nodeId: "10:20", isBranch: false });
+  });
+});
diff --git a/templates/design/shared/figma-url.ts b/templates/design/shared/figma-url.ts
new file mode 100644
index 0000000000..be14f115ee
--- /dev/null
+++ b/templates/design/shared/figma-url.ts
@@ -0,0 +1,149 @@
+/**
+ * Shared Figma URL / node-id parsing helpers.
+ *
+ * Figma file URLs come in a few shapes:
+ *   https://www.figma.com/design/<fileKey>/<name>
+ *   https://www.figma.com/file/<fileKey>/<name>            (legacy)
+ *   https://www.figma.com/proto/<fileKey>/<name>            (prototype share link)
+ *   https://www.figma.com/design/<fileKey>/<name>/branch/<branchKey>/<name>
+ *
+ * The branch shape is the important gotcha: a branch is a *separate* file for
+ * REST API purposes. `/v1/files/:fileKey` etc. must be called with the
+ * **branch key**, not the parent file key that appears earlier in the path —
+ * calling with the parent key silently returns the parent file's content,
+ * not the branch the user is actually looking at. See
+ * https://developers.figma.com/docs/rest-api/ (branches share the same file
+ * shape as regular files once you have the branch's own key).
+ *
+ * `node-id` is carried as a query param and Figma writes it with dashes
+ * (`1-2`) even though the REST API's node ids use colons (`1:2`). Grouped /
+ * instance-swap node ids can look like `1:2;3:4` — only the plain
+ * `<number>-<number>` shape needs dash-to-colon conversion; anything already
+ * containing a colon is passed through untouched.
+ */
+
+const FIGMA_FILE_KEY_RE = /^[A-Za-z0-9_-]{8,}$/;
+const FILE_PATH_SEGMENTS = ["design", "file", "proto"] as const;
+
+export interface ParsedFigmaUrl {
+  /** Effective file key to use for REST API calls (branch key when present). */
+  fileKey: string | null;
+  /** Node id in REST API colon form (e.g. "1:2"), or null when absent. */
+  nodeId: string | null;
+  /** True when the URL pointed at a branch and fileKey is that branch's key. */
+  isBranch: boolean;
+}
+
+function candidateFileKey(value: string): string | null {
+  return FIGMA_FILE_KEY_RE.test(value) ? value : null;
+}
+
+/**
+ * Extract the effective Figma file key from a raw file key or a Figma URL.
+ * Resolves `/branch/:branchKey/` to the branch key when present, since a
+ * branch is a distinct file from the REST API's point of view.
+ */
+export function parseFigmaFileKey(input: string | undefined): string | null {
+  const value = input?.trim();
+  if (!value) return null;
+
+  const direct = candidateFileKey(value);
+  if (direct) return direct;
+
+  try {
+    const url = new URL(value);
+    const parts = url.pathname.split("/").filter(Boolean);
+
+    const branchIndex = parts.indexOf("branch");
+    if (branchIndex >= 0) {
+      const branchKey = candidateFileKey(parts[branchIndex + 1] ?? "");
+      if (branchKey) return branchKey;
+    }
+
+    for (const segment of FILE_PATH_SEGMENTS) {
+      const index = parts.indexOf(segment);
+      if (index >= 0) {
+        const key = candidateFileKey(parts[index + 1] ?? "");
+        if (key) return key;
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/** True when the given file URL points at a branch (not the main file). */
+export function isFigmaBranchUrl(input: string | undefined): boolean {
+  const value = input?.trim();
+  if (!value) return false;
+  try {
+    const url = new URL(value);
+    return url.pathname.split("/").filter(Boolean).includes("branch");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalize a raw node-id-ish string to the REST API's colon form. Accepts:
+ *   "1:2"          -> "1:2"        (already normalized)
+ *   "1-2"          -> "1:2"        (dash form, as seen in `node-id` query params)
+ *   "1-2;3-4"      -> "1:2;3:4"    (instance-swap grouped ids)
+ *   "I1:2;3:4"     -> "I1:2;3:4"   (already normalized, leading instance marker)
+ */
+function normalizeNodeIdToken(token: string): string | null {
+  const trimmed = token.trim();
+  if (!trimmed) return null;
+  // Already colon form (optionally prefixed with "I" for instance overrides).
+  if (/^I?\d+:\d+$/.test(trimmed)) return trimmed;
+  // Dash form -> colon form.
+  if (/^I?\d+-\d+$/.test(trimmed)) return trimmed.replace("-", ":");
+  return null;
+}
+
+function normalizeNodeId(raw: string): string | null {
+  const decoded = (() => {
+    try {
+      return decodeURIComponent(raw);
+    } catch {
+      return raw;
+    }
+  })();
+  const parts = decoded
+    .split(";")
+    .map((part) => normalizeNodeIdToken(part))
+    .filter((part): part is string => part !== null);
+  return parts.length > 0 ? parts.join(";") : null;
+}
+
+/**
+ * Extract a Figma node id from a `node-id` query param or a raw id string,
+ * converting Figma's URL dash form (`1-2`) to the REST API's colon form
+ * (`1:2`).
+ */
+export function parseFigmaNodeId(input: string | undefined): string | null {
+  const value = input?.trim();
+  if (!value) return null;
+
+  const direct = normalizeNodeId(value);
+  if (direct) return direct;
+
+  try {
+    const url = new URL(value);
+    const nodeParam = url.searchParams.get("node-id");
+    if (nodeParam) return normalizeNodeId(nodeParam);
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/** Parse a Figma URL (or bare file key) into its effective file key and node id. */
+export function parseFigmaUrl(input: string | undefined): ParsedFigmaUrl {
+  const fileKey = parseFigmaFileKey(input);
+  const nodeId = parseFigmaNodeId(input);
+  return { fileKey, nodeId, isBranch: isFigmaBranchUrl(input) };
+}
diff --git a/templates/design/shared/pen-path.test.ts b/templates/design/shared/pen-path.test.ts
index 62cd8b8287..ca0f51e523 100644
--- a/templates/design/shared/pen-path.test.ts
+++ b/templates/design/shared/pen-path.test.ts
@@ -241,6 +241,25 @@ describe("pen path helpers", () => {
       expect(snapped).toEqual({ x: 100, y: 0 });
     });
 
+    it("snaps to the nearest anchor when multiple anchors are within the hit radius", () => {
+      const path = appendPenNode(
+        appendPenNode(null, createCornerNode({ x: 0, y: 0 })),
+        createCornerNode({ x: 100, y: 0 }),
+      );
+
+      // (55, 0) is 55px from the first anchor and 45px from the second —
+      // both within the 60px hit radius, but the second is closer. The
+      // first anchor happens to come first in node order, so a naive
+      // "first match wins" scan (rather than nearest-match, as
+      // hitTestPenAnchor already does) would incorrectly snap there
+      // instead.
+      const snapped = snapPenAnchorPoint({ x: 55, y: 0 }, path, {
+        hitRadius: 60,
+        zoom: 50,
+      });
+      expect(snapped).toEqual({ x: 100, y: 0 });
+    });
+
     it("does not snap to an anchor outside the hit radius", () => {
       const path = appendPenNode(null, createCornerNode({ x: 0, y: 0 }));
       const snapped = snapPenAnchorPoint({ x: 50, y: 50 }, path, {
diff --git a/templates/design/shared/pen-path.ts b/templates/design/shared/pen-path.ts
index 169f0934bc..61fd42ab48 100644
--- a/templates/design/shared/pen-path.ts
+++ b/templates/design/shared/pen-path.ts
@@ -115,13 +115,22 @@ export function snapPenAnchorPoint(
   path: PenPath | null,
   options: { hitRadius: number; zoom: number },
 ): PenPoint {
-  const existingAnchor = path?.nodes.find(
-    (node) =>
-      Math.hypot(node.point.x - point.x, node.point.y - point.y) <=
-      options.hitRadius,
-  );
-  if (existingAnchor) {
-    return { ...existingAnchor.point };
+  // Nearest anchor within radius wins (matching hitTestPenAnchor), not the
+  // first one found in node order — two anchors can easily both sit within
+  // the hit radius (e.g. a tightly drawn shape), and a "first match" scan
+  // would snap to whichever happens to have the lower node index rather than
+  // the one actually closest to the cursor.
+  let nearestAnchor: PenPoint | null = null;
+  let nearestDistance = Infinity;
+  for (const node of path?.nodes ?? []) {
+    const distance = Math.hypot(node.point.x - point.x, node.point.y - point.y);
+    if (distance <= options.hitRadius && distance < nearestDistance) {
+      nearestDistance = distance;
+      nearestAnchor = node.point;
+    }
+  }
+  if (nearestAnchor) {
+    return { ...nearestAnchor };
   }
 
   if (options.zoom >= 100) {
diff --git a/templates/design/shared/source-mode.ts b/templates/design/shared/source-mode.ts
index 8b5fd45f40..8f28a6f34e 100644
--- a/templates/design/shared/source-mode.ts
+++ b/templates/design/shared/source-mode.ts
@@ -97,6 +97,7 @@ export const DESIGN_BRIDGE_OPERATIONS = [
   "writeFile",
   "captureSnapshot",
   "captureState",
+  "listFiles",
 ] as const;
 
 export type DesignBridgeOperation = (typeof DESIGN_BRIDGE_OPERATIONS)[number];
diff --git a/templates/plan/app/components/plan/CanvasArea.tsx b/templates/plan/app/components/plan/CanvasArea.tsx
index a7d9c214fa..bbf448577c 100644
--- a/templates/plan/app/components/plan/CanvasArea.tsx
+++ b/templates/plan/app/components/plan/CanvasArea.tsx
@@ -41,8 +41,6 @@ const useIsomorphicLayoutEffect =
 const DEFAULT_VIEW = { zoom: 0.72, pan: { x: 96, y: 64 } };
 const MIN_ZOOM = 0.18;
 const MAX_ZOOM = 2.4;
-/** Notched mouse-wheel fixed-ratio step (design-canvas.jsx feel). */
-const WHEEL_ZOOM_STEP = 0.16;
 /** Trackpad pinch sensitivity. */
 const PINCH_ZOOM_SENSITIVITY = 0.01;
 /** Base CSS grid cell, scaled by zoom. */
@@ -534,9 +532,11 @@ export function CanvasArea({
     [buildMarkupContext, onCanvasMarkupCreate, pendingMarkup],
   );
 
-  // Wheel: cursor-over-canvas never scrolls the page. Notched wheel zooms with
-  // a fixed ratio per click; ctrl/cmd/alt (or trackpad pinch) zoom at the
-  // cursor; everything else pans.
+  // Wheel: cursor-over-canvas never scrolls the page. Match Figma's input
+  // contract: unmodified wheel/trackpad gestures always pan, while an explicit
+  // ctrl/cmd modifier (including the ctrlKey emitted by trackpad pinch) zooms
+  // at the cursor. Never infer zoom intent from the delta shape — trackpad pan
+  // momentum can look exactly like a notched mouse wheel near a canvas edge.
   useEffect(() => {
     const element = viewportRef.current;
     if (!element) return;
@@ -559,24 +559,12 @@ export function CanvasArea({
       const deltaX = event.deltaX * lineScale;
       const deltaY = event.deltaY * lineScale;
 
-      // Notched mouse wheel: line-mode, or large integer pixel deltas with no
-      // horizontal component (Chrome/Safari). Fixed-ratio step per click.
-      const isNotchedWheel =
-        event.deltaMode !== 0 ||
-        (event.deltaX === 0 &&
-          Number.isInteger(event.deltaY) &&
-          Math.abs(event.deltaY) >= 40);
-
-      if (event.ctrlKey || event.metaKey || event.altKey) {
+      if (event.ctrlKey || event.metaKey) {
         // Trackpad pinch / explicit zoom modifier — smooth exponential.
         zoomByFactor(Math.exp(-deltaY * PINCH_ZOOM_SENSITIVITY), anchor);
         return;
       }
-      if (isNotchedWheel) {
-        zoomByFactor(Math.exp(-Math.sign(deltaY) * WHEEL_ZOOM_STEP), anchor);
-        return;
-      }
-      // Trackpad two-finger scroll → pan.
+      // Mouse wheel / trackpad two-finger scroll -> pan.
       updateView((current) => ({
         ...current,
         pan: {
diff --git a/templates/plan/changelog/2026-07-09-canvas-panning-now-keeps-zoom-fixed-even-at-the-edges.md b/templates/plan/changelog/2026-07-09-canvas-panning-now-keeps-zoom-fixed-even-at-the-edges.md
new file mode 100644
index 0000000000..358b1e4551
--- /dev/null
+++ b/templates/plan/changelog/2026-07-09-canvas-panning-now-keeps-zoom-fixed-even-at-the-edges.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Canvas panning now keeps zoom fixed, even at the edges.
diff --git a/templates/plan/e2e/canvas-interactions.spec.ts b/templates/plan/e2e/canvas-interactions.spec.ts
index 610a8b3eba..44c2a11e38 100644
--- a/templates/plan/e2e/canvas-interactions.spec.ts
+++ b/templates/plan/e2e/canvas-interactions.spec.ts
@@ -579,44 +579,87 @@ test("canvas comment pins preserve zoom and follow later pan", async ({
   ).toBeLessThan(18);
 });
 
-test("wheel over the canvas zooms (and never scrolls the page)", async ({
+test("unmodified wheel pans to the canvas edge without changing zoom", async ({
   page,
 }) => {
   const planId = await createPlan(
     page,
     richBoard(`wheel-${Date.now()}`),
-    "wheel-zoom",
+    "wheel-pan",
   );
   await openCanvas(page, planId, ["ab-dash"]);
 
   const before = await worldTransform(page);
+  const zoomTextBefore = await page.locator(ZOOM_PCT).textContent();
   const vp = await boxOf(page, VIEWPORT);
   const cx = vp!.left + vp!.width / 2;
   const cy = vp!.top + vp!.height / 2;
   await page.mouse.move(cx, cy);
-  // Notched wheel up == zoom in. deltaY -120 mimics a mouse wheel click.
-  await page.mouse.wheel(0, -120);
-  await page.mouse.wheel(0, -120);
-  await page.waitForTimeout(150);
-  const afterUp = await worldTransform(page);
-  expect(afterUp!.scale, "wheel up should zoom the canvas in").toBeGreaterThan(
-    before!.scale + 0.01,
-  );
 
-  await page.mouse.wheel(0, 120);
+  // A large, axis-aligned integer delta is a valid trackpad/mouse pan tick.
+  // It used to be misclassified as a notched-wheel zoom.
   await page.mouse.wheel(0, 120);
   await page.waitForTimeout(150);
-  const afterDown = await worldTransform(page);
+  const afterPan = await worldTransform(page);
   expect(
-    afterDown!.scale,
-    "wheel down should zoom the canvas back out",
-  ).toBeLessThan(afterUp!.scale - 0.01);
+    Math.abs(afterPan!.ty - before!.ty),
+    "unmodified wheel should pan the canvas",
+  ).toBeGreaterThan(40);
+  expect(
+    Math.abs(afterPan!.scale - before!.scale),
+    "unmodified wheel pan must preserve zoom",
+  ).toBeLessThan(0.001);
+
+  // Push well beyond the finite pan range, then keep pushing at the clamp.
+  // Edge pressure must never be reinterpreted as zoom.
+  await page.mouse.wheel(0, 20_000);
+  await page.waitForTimeout(150);
+  const atEdge = await worldTransform(page);
+  await page.mouse.wheel(0, 20_000);
+  await page.waitForTimeout(150);
+  const beyondEdge = await worldTransform(page);
+  expect(
+    Math.abs(atEdge!.scale - before!.scale),
+    "reaching the canvas edge must preserve zoom",
+  ).toBeLessThan(0.001);
+  expect(
+    Math.abs(beyondEdge!.scale - before!.scale),
+    "continued panning at the canvas edge must preserve zoom",
+  ).toBeLessThan(0.001);
+  expect(
+    Math.abs(beyondEdge!.ty - atEdge!.ty),
+    "pan should remain clamped at the canvas edge",
+  ).toBeLessThan(1);
+  await expect(page.locator(ZOOM_PCT)).toHaveText(zoomTextBefore ?? "");
 
   // The page itself must not have scrolled (wheel is captured by the canvas).
   const scrollY = await page.evaluate(() => window.scrollY);
   expect(scrollY, "wheel over the canvas must not scroll the page").toBe(0);
 });
 
+test("modifier wheel zooms at the cursor", async ({ page }) => {
+  const planId = await createPlan(
+    page,
+    richBoard(`modifier-wheel-${Date.now()}`),
+    "modifier-wheel-zoom",
+  );
+  await openCanvas(page, planId, ["ab-dash"]);
+
+  const before = await worldTransform(page);
+  const vp = await boxOf(page, VIEWPORT);
+  const cx = vp!.left + vp!.width / 2;
+  const cy = vp!.top + vp!.height / 2;
+  await page.mouse.move(cx, cy);
+  await page.keyboard.down("Control");
+  await page.mouse.wheel(0, -80);
+  await page.keyboard.up("Control");
+  await page.waitForTimeout(150);
+  const after = await worldTransform(page);
+  expect(after!.scale, "ctrl/cmd wheel should zoom the canvas").toBeGreaterThan(
+    before!.scale + 0.01,
+  );
+});
+
 /* -------------------------------------------------------------------------- */
 /* Labels + section headers scale WITH the board (no inverse counter-scale)   */
 /* -------------------------------------------------------------------------- */
diff --git a/templates/slides/actions/index-design-system-with-builder.ts b/templates/slides/actions/index-design-system-with-builder.ts
index c74d0d3382..03579c1cae 100644
--- a/templates/slides/actions/index-design-system-with-builder.ts
+++ b/templates/slides/actions/index-design-system-with-builder.ts
@@ -13,8 +13,23 @@ import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-sys
 
 const codeFileSchema = z.object({
   filename: z.string().trim().min(1).describe("File name or relative path"),
-  content: z.string().describe("Raw text content of the code/design file"),
+  content: z
+    .string()
+    .describe(
+      "File content. Text files (code, CSS, markdown, JSON, SVG): raw text. " +
+        "Binary files -- most importantly `.fig` (a zip/kiwi binary container, " +
+        'never valid text) -- MUST be base64-encoded with encoding: "base64"; ' +
+        "sending raw/binary-as-string content with the default utf8 encoding " +
+        "corrupts the file before it reaches Builder.",
+    ),
   mimeType: z.string().trim().optional().describe("Optional MIME type"),
+  encoding: z
+    .enum(["utf8", "base64"])
+    .optional()
+    .describe(
+      "Encoding of `content`. Defaults to utf8. Set to base64 for `.fig` and " +
+        "other binary files.",
+    ),
 });
 
 export default defineAction({
diff --git a/templates/slides/app/context/DeckContext.persistence.test.ts b/templates/slides/app/context/DeckContext.persistence.test.ts
index fa41176355..cbbbf1c7e1 100644
--- a/templates/slides/app/context/DeckContext.persistence.test.ts
+++ b/templates/slides/app/context/DeckContext.persistence.test.ts
@@ -3,15 +3,49 @@ import { act, renderHook, waitFor } from "@testing-library/react";
 import { createElement, type ReactNode } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { DeckProvider, useDecks, type Deck, type Slide } from "./DeckContext";
+import {
+  DeckProvider,
+  hasUncommittedDeckChanges,
+  mergeServerAddedSlides,
+  useDecks,
+  type Deck,
+  type Slide,
+} from "./DeckContext";
 
 class MockEventSource {
   static lastInstance: MockEventSource | null = null;
+  static instances: MockEventSource[] = [];
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSED = 2;
+
   onmessage: ((event: MessageEvent) => void) | null = null;
-  close = vi.fn();
+  onopen: (() => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+  readyState: number = MockEventSource.CONNECTING;
+  close = vi.fn(() => {
+    this.readyState = MockEventSource.CLOSED;
+  });
 
   constructor(public url: string) {
     MockEventSource.lastInstance = this;
+    MockEventSource.instances.push(this);
+  }
+
+  /** Simulate the browser successfully (re)establishing the connection. */
+  simulateOpen() {
+    this.readyState = MockEventSource.OPEN;
+    this.onopen?.();
+  }
+
+  /**
+   * Simulate a FATAL SSE error: a non-2xx HTTP response (or bad
+   * content-type). Per the EventSource spec this closes the connection and
+   * the browser does NOT retry on its own — readyState becomes CLOSED.
+   */
+  simulateFatalError() {
+    this.readyState = MockEventSource.CLOSED;
+    this.onerror?.(new Event("error"));
   }
 }
 
@@ -19,7 +53,7 @@ function wrapper({ children }: { children: ReactNode }) {
   return createElement(DeckProvider, null, children);
 }
 
-function setupFetch() {
+function setupFetch(options?: { hangPut?: boolean }) {
   let resolveCreate: (response: Response) => void = () => {};
   let accessibleDeck: Deck | null = null;
   const fetchMock = vi.fn((url: string | URL | Request, init?: RequestInit) => {
@@ -30,6 +64,28 @@ function setupFetch() {
           ? url.toString()
           : url.url;
 
+    // Legacy full-replace PUT. When `hangPut` is set, the request never
+    // resolves on its own — it only rejects when its AbortSignal fires, which
+    // is exactly what `fetchWithTimeout` does after the timeout. This lets a
+    // test prove the timeout drains `inFlightSaves` instead of wedging it.
+    if (init?.method === "PUT" && href.includes("/api/decks/")) {
+      if (options?.hangPut) {
+        return new Promise<Response>((_resolve, reject) => {
+          const signal = init?.signal;
+          if (signal) {
+            signal.addEventListener("abort", () => {
+              reject(
+                Object.assign(new Error("Aborted"), { name: "AbortError" }),
+              );
+            });
+          }
+        });
+      }
+      return Promise.resolve(
+        new Response(JSON.stringify({ ok: true }), { status: 200 }),
+      );
+    }
+
     if (init?.method === "POST" && href.endsWith("/api/decks")) {
       return new Promise<Response>((resolve) => {
         resolveCreate = resolve;
@@ -37,8 +93,9 @@ function setupFetch() {
     }
 
     if (href.includes("/_agent-native/actions/list-decks")) {
+      const decks = accessibleDeck ? [accessibleDeck] : [];
       return Promise.resolve(
-        new Response(JSON.stringify({ count: 0, decks: [] }), {
+        new Response(JSON.stringify({ count: decks.length, decks }), {
           status: 200,
         }),
       );
@@ -102,6 +159,7 @@ describe("DeckContext deck creation persistence", () => {
     vi.restoreAllMocks();
     vi.unstubAllGlobals();
     MockEventSource.lastInstance = null;
+    MockEventSource.instances = [];
   });
 
   it("awaits the in-flight create request instead of polling for the new deck", async () => {
@@ -725,4 +783,405 @@ describe("DeckContext deck creation persistence", () => {
       "<h1>Before</h1>",
     );
   });
+
+  describe("SSE reconnect and resync", () => {
+    it("reconnects after a fatal SSE error and closes the old connection (no leak)", async () => {
+      window.history.pushState({}, "", "/");
+      setupFetch();
+      const { result } = renderHook(() => useDecks(), { wrapper });
+      await waitFor(() => expect(result.current.loading).toBe(false));
+
+      const first = MockEventSource.lastInstance;
+      expect(first).toBeTruthy();
+
+      vi.useFakeTimers();
+      act(() => {
+        first!.simulateFatalError();
+      });
+
+      // A fatal error (readyState CLOSED) is not retried by the browser —
+      // our own reconnect must close the dead connection immediately...
+      expect(first!.close).toHaveBeenCalled();
+      // ...but must not hammer a new connection into existence right away.
+      expect(MockEventSource.instances.length).toBe(1);
+
+      // Just under the first backoff delay: still no reconnect.
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(999);
+      });
+      expect(MockEventSource.instances.length).toBe(1);
+
+      // Crossing the delay reconnects with a brand-new EventSource instance.
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(1);
+      });
+      expect(MockEventSource.instances.length).toBe(2);
+      expect(MockEventSource.instances[1]).not.toBe(first);
+    });
+
+    it("bounds SSE reconnect backoff at a maximum delay across repeated failures", async () => {
+      window.history.pushState({}, "", "/");
+      setupFetch();
+      const { result } = renderHook(() => useDecks(), { wrapper });
+      await waitFor(() => expect(result.current.loading).toBe(false));
+
+      vi.useFakeTimers();
+      let current = MockEventSource.lastInstance!;
+      // Base 1s, doubling, capped at 30s — the last two deltas repeat the cap.
+      const expectedDelays = [1000, 2000, 4000, 8000, 16000, 30000, 30000];
+      for (const delay of expectedDelays) {
+        act(() => {
+          current.simulateFatalError();
+        });
+        await act(async () => {
+          await vi.advanceTimersByTimeAsync(delay - 1);
+        });
+        const countBeforeCap = MockEventSource.instances.length;
+        await act(async () => {
+          await vi.advanceTimersByTimeAsync(1);
+        });
+        expect(MockEventSource.instances.length).toBe(countBeforeCap + 1);
+        current = MockEventSource.instances.at(-1)!;
+      }
+    });
+
+    it("stops reconnect attempts after unmount", async () => {
+      window.history.pushState({}, "", "/");
+      setupFetch();
+      const { result, unmount } = renderHook(() => useDecks(), { wrapper });
+      await waitFor(() => expect(result.current.loading).toBe(false));
+
+      const first = MockEventSource.lastInstance!;
+      vi.useFakeTimers();
+      act(() => {
+        first.simulateFatalError();
+      });
+      expect(first.close).toHaveBeenCalled();
+
+      unmount();
+
+      // Advance well past the reconnect delay and the backoff cap.
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(60_000);
+      });
+
+      // The pending reconnect timer was cleared by the effect's cleanup, so
+      // no new connection was created after unmount.
+      expect(MockEventSource.instances.length).toBe(1);
+    });
+
+    it("issues a full resync on reconnect, so slides added while disconnected appear in state", async () => {
+      window.history.pushState({}, "", "/deck/resync-deck");
+      const initial: Deck = {
+        id: "resync-deck",
+        title: "Resync Deck",
+        createdAt: "2026-07-09T00:00:00.000Z",
+        updatedAt: "2026-07-09T00:00:00.000Z",
+        slides: [
+          {
+            id: "slide-1",
+            content: "<h1>One</h1>",
+            notes: "",
+            layout: "title",
+          },
+        ],
+      };
+      const { setAccessibleDeck } = setupFetch();
+      const { result } = renderHook(() => useDecks(), { wrapper });
+      await waitFor(() => expect(result.current.loading).toBe(false));
+
+      setAccessibleDeck(initial);
+      await act(async () => {
+        await result.current.reloadDecks();
+      });
+      await waitFor(() =>
+        expect(result.current.getDeck("resync-deck")?.slides.length).toBe(1),
+      );
+
+      const source = MockEventSource.lastInstance!;
+      act(() => {
+        source.simulateOpen();
+      });
+
+      // The agent adds a slide server-side WHILE this tab is about to lose
+      // its SSE connection. notifyClients() is fire-and-forget with no
+      // backlog, so no event for this write will ever reach a client that
+      // reconnects after it was broadcast — only a resync recovers it.
+      const withNewSlide: Deck = {
+        ...initial,
+        updatedAt: "2026-07-09T00:05:00.000Z",
+        slides: [
+          ...initial.slides,
+          {
+            id: "slide-2",
+            content: "<h1>Added while disconnected</h1>",
+            notes: "",
+            layout: "content",
+          },
+        ],
+      };
+      setAccessibleDeck(withNewSlide);
+
+      vi.useFakeTimers();
+      act(() => {
+        source.simulateFatalError();
+      });
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(1000);
+      });
+      const reconnected = MockEventSource.instances.at(-1)!;
+      expect(reconnected).not.toBe(source);
+
+      // Switch back to real timers before using testing-library's `waitFor`,
+      // which polls on its own timer and does not advance fake timers itself.
+      vi.useRealTimers();
+
+      act(() => {
+        reconnected.simulateOpen();
+      });
+
+      await waitFor(() =>
+        expect(result.current.getDeck("resync-deck")?.slides.length).toBe(2),
+      );
+      expect(result.current.getDeck("resync-deck")?.slides[1]?.content).toBe(
+        "<h1>Added while disconnected</h1>",
+      );
+    });
+
+    it("resync surfaces agent-added slides even when the deck is dirty, without clobbering local edits", async () => {
+      // This is the regression test for the real production incident: the poll
+      // and the resync used to bail entirely on `hasUncommittedDeckChanges`, so
+      // a dirty (or wedged-save) deck stayed permanently blind to agent-added
+      // slides. Here the deck is dirty at reconnect AND the server has both an
+      // added slide and a conflicting edit to the existing slide.
+      window.history.pushState({}, "", "/deck/dirty-deck");
+      const initial: Deck = {
+        id: "dirty-deck",
+        title: "Dirty Deck",
+        createdAt: "2026-07-09T00:00:00.000Z",
+        updatedAt: "2026-07-09T00:00:00.000Z",
+        slides: [
+          {
+            id: "slide-1",
+            content: "<h1>Local one</h1>",
+            notes: "",
+            layout: "title",
+          },
+        ],
+      };
+      const { setAccessibleDeck } = setupFetch();
+      const { result } = renderHook(() => useDecks(), { wrapper });
+      await waitFor(() => expect(result.current.loading).toBe(false));
+
+      setAccessibleDeck(initial);
+      await act(async () => {
+        await result.current.reloadDecks();
+      });
+      await waitFor(() =>
+        expect(result.current.getDeck("dirty-deck")?.slides.length).toBe(1),
+      );
+
+      // Human is mid-edit: the exact state that used to suppress the refetch.
+      act(() => {
+        result.current.markDeckDirty("dirty-deck");
+      });
+
+      const source = MockEventSource.lastInstance!;
+      act(() => {
+        source.simulateOpen();
+      });
+
+      // Agent adds slide-2 AND rewrites slide-1 server-side while we're dirty.
+      const serverVersion: Deck = {
+        ...initial,
+        updatedAt: "2026-07-09T00:05:00.000Z",
+        slides: [
+          {
+            id: "slide-1",
+            content: "<h1>SERVER rewrote one</h1>",
+            notes: "",
+            layout: "title",
+          },
+          {
+            id: "slide-2",
+            content: "<h1>Agent added</h1>",
+            notes: "",
+            layout: "content",
+          },
+        ],
+      };
+      setAccessibleDeck(serverVersion);
+
+      vi.useFakeTimers();
+      act(() => {
+        source.simulateFatalError();
+      });
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(1000);
+      });
+      const reconnected = MockEventSource.instances.at(-1)!;
+      vi.useRealTimers();
+
+      act(() => {
+        reconnected.simulateOpen();
+      });
+
+      await waitFor(() =>
+        expect(result.current.getDeck("dirty-deck")?.slides.length).toBe(2),
+      );
+      const deck = result.current.getDeck("dirty-deck")!;
+      // Agent addition surfaced despite the dirty deck...
+      expect(deck.slides[1]?.content).toBe("<h1>Agent added</h1>");
+      // ...but the locally-edited slide-1 was NOT clobbered by server content.
+      expect(deck.slides[0]?.content).toBe("<h1>Local one</h1>");
+    });
+  });
+
+  describe("save-hang timeout drains inFlightSaves", () => {
+    it("aborts a stalled full-replace PUT so inFlightSaves drains and the open deck refetches", async () => {
+      window.history.pushState({}, "", "/deck/hang-deck");
+      const initial: Deck = {
+        id: "hang-deck",
+        title: "Hang Deck",
+        createdAt: "2026-07-09T00:00:00.000Z",
+        updatedAt: "2026-07-09T00:00:00.000Z",
+        slides: [
+          {
+            id: "slide-1",
+            content: "<h1>One</h1>",
+            notes: "",
+            layout: "title",
+          },
+        ],
+      };
+      const { setAccessibleDeck } = setupFetch({ hangPut: true });
+      const { result } = renderHook(() => useDecks(), { wrapper });
+      await waitFor(() => expect(result.current.loading).toBe(false));
+
+      setAccessibleDeck(initial);
+      await act(async () => {
+        await result.current.reloadDecks();
+      });
+      await waitFor(() =>
+        expect(result.current.getDeck("hang-deck")?.slides.length).toBe(1),
+      );
+
+      // Establish the initial SSE connection so a later reconnect is treated as
+      // a RE-connect (which resyncs), not the first connect (which does not).
+      const firstSource = MockEventSource.lastInstance!;
+      act(() => {
+        firstSource.simulateOpen();
+      });
+
+      vi.useFakeTimers();
+      // A local edit via setDeckSlides enqueues the legacy full-replace PUT.
+      // After the 500ms debounce it moves into inFlightSaves — then hangs.
+      act(() => {
+        result.current.setDeckSlides("hang-deck", [
+          {
+            id: "slide-1",
+            content: "<h1>Edited locally</h1>",
+            notes: "",
+            layout: "title",
+          },
+        ]);
+      });
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(500);
+      });
+
+      // In flight and hanging. Probe the pendingSaves/inFlightSaves branch of
+      // hasUncommittedDeckChanges directly by passing an EMPTY dirty set.
+      expect(hasUncommittedDeckChanges("hang-deck", new Set())).toBe(true);
+
+      // Advance past the 60s raw-fetch timeout: the AbortController fires, the
+      // PUT rejects, and the save's `finally` deletes the inFlightSaves entry.
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(60_000);
+      });
+      expect(hasUncommittedDeckChanges("hang-deck", new Set())).toBe(false);
+
+      // With the leak drained, an agent-added slide must now reach the open
+      // deck (it was permanently suppressed while inFlightSaves was wedged).
+      const agentVersion: Deck = {
+        ...initial,
+        updatedAt: "2026-07-09T00:10:00.000Z",
+        slides: [
+          {
+            id: "slide-1",
+            content: "<h1>Edited locally</h1>",
+            notes: "",
+            layout: "title",
+          },
+          {
+            id: "slide-2",
+            content: "<h1>Agent added post-hang</h1>",
+            notes: "",
+            layout: "content",
+          },
+        ],
+      };
+      setAccessibleDeck(agentVersion);
+
+      act(() => {
+        firstSource.simulateFatalError();
+      });
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(1000);
+      });
+      const reconnected = MockEventSource.instances.at(-1)!;
+      vi.useRealTimers();
+
+      act(() => {
+        reconnected.simulateOpen();
+      });
+
+      await waitFor(() =>
+        expect(result.current.getDeck("hang-deck")?.slides.length).toBe(2),
+      );
+      expect(result.current.getDeck("hang-deck")?.slides[1]?.content).toBe(
+        "<h1>Agent added post-hang</h1>",
+      );
+    });
+  });
+
+  describe("mergeServerAddedSlides", () => {
+    const slide = (id: string, content: string): Slide => ({
+      id,
+      content,
+      notes: "",
+      layout: "content",
+    });
+    const deckOf = (slides: Slide[]): Deck => ({
+      id: "d",
+      title: "t",
+      createdAt: "",
+      updatedAt: "",
+      slides,
+    });
+
+    it("adds server-only slides in server order without touching local content", () => {
+      const local = deckOf([slide("a", "LOCAL a")]);
+      const server = deckOf([slide("a", "SERVER a"), slide("b", "b")]);
+      const merged = mergeServerAddedSlides(local, server);
+      expect(merged.slides.map((s) => s.id)).toEqual(["a", "b"]);
+      expect(merged.slides[0]?.content).toBe("LOCAL a"); // local preserved
+      expect(merged.slides[1]?.content).toBe("b");
+    });
+
+    it("returns the same local reference when nothing was added", () => {
+      const local = deckOf([slide("a", "a")]);
+      const server = deckOf([slide("a", "SERVER a")]);
+      expect(mergeServerAddedSlides(local, server)).toBe(local);
+    });
+
+    it("never drops a local-only (unsaved) slide", () => {
+      const local = deckOf([slide("a", "a"), slide("local-only", "x")]);
+      const server = deckOf([slide("a", "a"), slide("b", "b")]);
+      const merged = mergeServerAddedSlides(local, server);
+      expect([...merged.slides.map((s) => s.id)].sort()).toEqual(
+        ["a", "b", "local-only"].sort(),
+      );
+    });
+  });
 });
diff --git a/templates/slides/app/context/DeckContext.tsx b/templates/slides/app/context/DeckContext.tsx
index 83cbd93f00..7afe1e2100 100644
--- a/templates/slides/app/context/DeckContext.tsx
+++ b/templates/slides/app/context/DeckContext.tsx
@@ -191,6 +191,11 @@ const DeckContext = createContext<DeckContextType | null>(null);
 
 const OPEN_DECK_FALLBACK_POLL_MS = 5_000;
 const DECK_LIST_FALLBACK_POLL_MS = 15_000;
+// Bounded exponential backoff for SSE reconnect after a fatal error (e.g. a
+// non-2xx response, which EventSource treats as terminal and never retries
+// on its own — see the SSE effect below). Doubles from BASE up to MAX.
+const SSE_RECONNECT_BASE_MS = 1_000;
+const SSE_RECONNECT_MAX_MS = 30_000;
 
 type DeckListActionResult = {
   decks?: unknown[];
@@ -236,6 +241,30 @@ const saveStateListeners = new Set<() => void>();
 // Ops are appended by enqueueDeckOp and drained when the debounce fires.
 const pendingOpsQueue = new Map<string, GranularOp[]>();
 
+// Every raw deck fetch (the legacy full-replace PUT, the create POST) MUST be
+// bounded. Without a timeout, a stalled connection leaves the awaited promise
+// forever pending, so the `finally` that drains `inFlightSaves` /
+// `pendingCreateIdsRef` never runs — wedging the deck id in a set that
+// `hasUncommittedDeckChanges` reads, which permanently suppresses the poll's
+// and the SSE resync's open-deck refetch (the editor goes blind to agent edits
+// until a full page reload). Matches the granular `patch-deck` path, which is
+// already bounded at 60s by `actionFetch`'s DEFAULT_ACTION_TIMEOUT_MS.
+const RAW_DECK_FETCH_TIMEOUT_MS = 60_000;
+
+async function fetchWithTimeout(
+  input: string,
+  init: RequestInit = {},
+  timeoutMs = RAW_DECK_FETCH_TIMEOUT_MS,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(input, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // Cached snapshot for useSyncExternalStore. MUST be stable when the boolean
 // is unchanged or React will infinite-loop (it compares snapshots with
 // Object.is — a fresh object literal every call schedules a new update,
@@ -311,9 +340,12 @@ function enqueueDeckOp(deckId: string, op: GranularOp) {
       if (ops.length === 0) return;
 
       if (ops[0].op === "full-replace") {
-        // Legacy full-deck PUT — used by undo/redo and setDeckSlides
+        // Legacy full-deck PUT — used by undo/redo and setDeckSlides.
+        // Bounded so a stalled PUT can't wedge `inFlightSaves` forever (its
+        // `finally` cleanup below only runs once this await settles; an
+        // AbortError from the timeout is a rejection that still reaches it).
         const deck = ops[0].deck;
-        await fetch(`${appBasePath()}/api/decks/${deckId}`, {
+        await fetchWithTimeout(`${appBasePath()}/api/decks/${deckId}`, {
           method: "PUT",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(deck),
@@ -738,7 +770,11 @@ async function deleteDeckFromAPI(id: string): Promise<void> {
 }
 
 async function createDeckOnAPI(deck: Deck): Promise<void> {
-  const res = await fetch(`${appBasePath()}/api/decks`, {
+  // Bounded so a stalled create response can't leave the deck id in
+  // `pendingCreateIdsRef` forever (cleared only in the caller's `.finally`,
+  // which needs this promise to settle). A wedged pending-create id would
+  // otherwise suppress the open-deck refetch just like a wedged save.
+  const res = await fetchWithTimeout(`${appBasePath()}/api/decks`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(deck),
@@ -778,6 +814,57 @@ export function hasUncommittedDeckChanges(
   );
 }
 
+/**
+ * Additive, content-preserving reconcile of a server deck snapshot onto the
+ * local copy — used when the open deck has uncommitted local edits, where a
+ * wholesale adopt would clobber the user's in-progress typing.
+ *
+ * The concern the "uncommitted changes" guard originally addressed (don't
+ * overwrite local edits with slightly-stale server state) is legitimate for
+ * slide BODIES, but it must not make the client permanently blind to the
+ * agent ADDING slides — that is the production staleness bug. So we split the
+ * two concerns:
+ *   - never overwrite the content of a slide that exists locally, and
+ *   - never drop a local-only slide (an unsaved local add), but
+ *   - always surface server slides that are missing locally (agent additions),
+ *     positioned to follow the server's ordering.
+ *
+ * Removals and content changes to slides that exist on both sides are left to
+ * the clean-deck path (`applyRemoteDeckUpdate`), which runs once local edits
+ * settle. This merge is intentionally conservative: it can only ADD slides, so
+ * it can never destroy local work, yet it always heals an empty/stale rail.
+ *
+ * Returns the same `local` reference when nothing was added, so callers can
+ * cheaply detect "no change".
+ */
+export function mergeServerAddedSlides(local: Deck, server: Deck): Deck {
+  const localIds = new Set(local.slides.map((s) => s.id));
+  const additions = server.slides.filter((s) => !localIds.has(s.id));
+  if (additions.length === 0) return local;
+
+  // Walk the server order, emitting local slides with their local (possibly
+  // dirty) content and inserting server-only additions in place. Any local
+  // slide not present on the server (an unsaved local add) is carried over at
+  // the end so we never drop unsaved local work.
+  const localById = new Map(local.slides.map((s) => [s.id, s]));
+  const emitted = new Set<string>();
+  const merged: Slide[] = [];
+  for (const s of server.slides) {
+    const localSlide = localById.get(s.id);
+    merged.push(localSlide ?? s);
+    emitted.add(s.id);
+  }
+  for (const s of local.slides) {
+    if (!emitted.has(s.id)) {
+      merged.push(s);
+      emitted.add(s.id);
+    }
+  }
+  // Keep local scalar fields (title/tweaks/etc. may be locally edited); only
+  // the slide set is reconciled here.
+  return { ...local, slides: merged };
+}
+
 export const defaultSlideContent: Record<SlideLayout, string> = {
   title: `<div class="fmd-slide" style="padding: 80px 110px; justify-content: space-between;">
   <div>
@@ -980,6 +1067,109 @@ export function DeckProvider({ children }: { children: ReactNode }) {
     [],
   );
 
+  // Re-fetch the deck list and diff it against local state (added/removed
+  // decks). Shared by the fallback poll and the SSE resync-on-reconnect path
+  // below so both pull from one implementation of "what changed".
+  const refetchDeckListIfChanged = useCallback(async () => {
+    const fresh = await fetchDecksFromAPI();
+    // A null result means the fetch failed (network error or non-2xx). Skip
+    // the diff so we don't wipe local state on a transient failure.
+    if (fresh === null) return;
+    const pending = pendingCreateIdsRef.current;
+    const currentDecks = decksRef.current;
+    const currentIds = new Set(currentDecks.map((d) => d.id));
+    const freshIds = new Set(fresh.map((d) => d.id));
+    // Check if deck list changed (added or removed). Optimistic decks still
+    // in flight are preserved (not treated as removed).
+    const added = fresh.filter((d) => !currentIds.has(d.id));
+    const removed = currentDecks.filter(
+      (d) => !freshIds.has(d.id) && !pending.has(d.id),
+    );
+    if (added.length === 0 && removed.length === 0) return;
+    lastExternalUpdateRef.current = Date.now();
+    setDecks((prev) => {
+      const prevIds = new Set(prev.map((d) => d.id));
+      // Only add decks that aren't already in prev (prevents duplicates when
+      // the closure's deck snapshot is stale compared to `prev`).
+      let next = prev.filter((d) => freshIds.has(d.id) || pending.has(d.id));
+      for (const a of added) {
+        if (!prevIds.has(a.id)) next = [...next, a];
+      }
+      return next;
+    });
+  }, []);
+
+  // Re-fetch the currently-open deck's full slide data and reconcile it.
+  //
+  // We ALWAYS fetch — never gate on pending-create or uncommitted-edits state.
+  // Gating the fetch was the liveness bug: a wedged `pendingSaves` /
+  // `inFlightSaves` / `pendingCreateIdsRef` entry (or a legitimately dirty
+  // deck) would make the editor permanently blind to agent-added slides.
+  //
+  // How we APPLY the result depends on whether there are local edits to
+  // protect:
+  //   - Clean deck → adopt the server snapshot wholesale (handles content
+  //     changes, removals, and reorders too), exactly as before.
+  //   - Dirty deck / unsaved local create → additive merge only: surface
+  //     agent-added slides without ever overwriting or dropping local slides.
+  const refetchOpenDeckIfChanged = useCallback(
+    async (currentOpenId: string) => {
+      const serverDeck = await fetchDeckFromAPI(currentOpenId);
+      // Null means 404 (row not created yet), a transient failure, or a
+      // still-pending create — nothing authoritative to reconcile.
+      if (!serverDeck) return;
+      const clientDeck = decksRef.current.find((d) => d.id === currentOpenId);
+
+      const hasLocalEdits =
+        pendingCreateIdsRef.current.has(currentOpenId) ||
+        hasUncommittedDeckChanges(currentOpenId, dirtyDeckIdsRef.current);
+
+      if (hasLocalEdits && clientDeck) {
+        // Content-preserving: only ADD server slides missing locally.
+        const merged = mergeServerAddedSlides(clientDeck, serverDeck);
+        if (merged === clientDeck) return; // nothing new to surface
+        lastExternalUpdateRef.current = Date.now();
+        setDecks((prev) => {
+          const idx = prev.findIndex((d) => d.id === currentOpenId);
+          if (idx < 0) return prev;
+          const next = [...prev];
+          next[idx] = merged;
+          return next;
+        });
+        return;
+      }
+
+      const changed =
+        !clientDeck ||
+        clientDeck.updatedAt !== serverDeck.updatedAt ||
+        clientDeck.slides.length !== serverDeck.slides.length;
+      if (!changed) return;
+      lastExternalUpdateRef.current = Date.now();
+      applyRemoteDeckUpdate(serverDeck);
+    },
+    [applyRemoteDeckUpdate],
+  );
+
+  /**
+   * Full resync of authoritative deck/slide state from the server. The SSE
+   * channel (`notifyClients` server-side) is fire-and-forget to whatever
+   * connections are live at broadcast time — there is no backlog or replay,
+   * so any event emitted while this tab was disconnected is gone forever.
+   * Call this whenever the SSE connection (re)establishes after a drop so
+   * agent writes made during the gap show up without requiring a full page
+   * reload.
+   */
+  const resyncDeckState = useCallback(async () => {
+    try {
+      await refetchDeckListIfChanged();
+    } catch {}
+    const currentOpenId = currentOpenDeckIdFromWindow();
+    if (!currentOpenId) return;
+    try {
+      await refetchOpenDeckIfChanged(currentOpenId);
+    } catch {}
+  }, [refetchDeckListIfChanged, refetchOpenDeckIfChanged]);
+
   const resetDeckBaseline = useCallback((nextDecks: Deck[]) => {
     setDecks(nextDecks);
     // A baseline reset (initial mount, route change, or access reload) starts a
@@ -1053,79 +1243,29 @@ export function DeckProvider({ children }: { children: ReactNode }) {
 
     async function poll() {
       if (stopped || isHidden()) return;
-      try {
-        const now = Date.now();
-        const currentOpenId = readOpenDeckId();
-        const pending = pendingCreateIdsRef.current;
+      const now = Date.now();
+      const currentOpenId = readOpenDeckId();
 
+      try {
         if (
           !currentOpenId ||
           now - lastListFetchAt >= DECK_LIST_FALLBACK_POLL_MS
         ) {
           lastListFetchAt = now;
-          const fresh = await fetchDecksFromAPI();
-          // A null result means the fetch failed (network error or non-2xx).
-          // Skip the diff so we don't wipe local state on a transient failure
-          // — otherwise the user's open deck disappears and they're bounced
-          // back to the empty "Create your first deck" screen until the next
-          // poll succeeds.
-          if (fresh !== null) {
-            const currentDecks = decksRef.current;
-            const currentIds = new Set(currentDecks.map((d) => d.id));
-            const freshIds = new Set(fresh.map((d) => d.id));
-            // Check if deck list changed (added or removed). Optimistic decks
-            // still in flight are preserved (not treated as removed).
-            const added = fresh.filter((d) => !currentIds.has(d.id));
-            const removed = currentDecks.filter(
-              (d) => !freshIds.has(d.id) && !pending.has(d.id),
-            );
-            if (added.length > 0 || removed.length > 0) {
-              lastExternalUpdateRef.current = Date.now();
-              setDecks((prev) => {
-                const prevIds = new Set(prev.map((d) => d.id));
-                let next = prev.filter(
-                  (d) => freshIds.has(d.id) || pending.has(d.id),
-                );
-                // Only add decks that aren't already in prev (prevents duplicates
-                // when the closure's deck snapshot is stale compared to `prev`).
-                for (const a of added) {
-                  if (!prevIds.has(a.id)) next = [...next, a];
-                }
-                return next;
-              });
-            }
-          }
+          // A failed fetch (network error or non-2xx) is swallowed inside
+          // refetchDeckListIfChanged — skip the diff so we don't wipe local
+          // state on a transient failure, otherwise the user's open deck
+          // disappears and they're bounced back to the empty "Create your
+          // first deck" screen until the next poll succeeds.
+          await refetchDeckListIfChanged();
         }
 
         // Also re-fetch the currently-open deck so agent-added slides show up.
         // The list endpoint may not include full slide contents, and SSE can
         // miss events if the client reconnects between broadcasts.
-        //
-        // Skip the refetch if a save is pending or in flight — the server's
-        // copy might be a few hundred ms behind the local edits the user is
-        // mid-typing, and overwriting wholesale would briefly revert their
-        // characters before the next save lands. The next poll tick (after
-        // saves settle) catches up.
-        if (
-          currentOpenId &&
-          !pending.has(currentOpenId) &&
-          !hasUncommittedDeckChanges(currentOpenId, dirtyDeckIdsRef.current)
-        ) {
+        if (currentOpenId) {
           try {
-            const serverDeck = await fetchDeckFromAPI(currentOpenId);
-            if (serverDeck) {
-              const clientDeck = decksRef.current.find(
-                (d) => d.id === currentOpenId,
-              );
-              const changed =
-                !clientDeck ||
-                clientDeck.updatedAt !== serverDeck.updatedAt ||
-                clientDeck.slides.length !== serverDeck.slides.length;
-              if (changed) {
-                lastExternalUpdateRef.current = Date.now();
-                applyRemoteDeckUpdate(serverDeck);
-              }
-            }
+            await refetchOpenDeckIfChanged(currentOpenId);
           } catch {}
         }
       } catch {}
@@ -1160,7 +1300,7 @@ export function DeckProvider({ children }: { children: ReactNode }) {
       window.removeEventListener("focus", pollNow);
       document.removeEventListener("visibilitychange", handleVisibilityChange);
     };
-  }, [applyRemoteDeckUpdate, loading]);
+  }, [refetchDeckListIfChanged, refetchOpenDeckIfChanged, loading]);
 
   // The dirty-deck set is now only used as a sentinel that "something changed
   // for this deck". Ops are enqueued directly in each mutation handler below;
@@ -1184,11 +1324,53 @@ export function DeckProvider({ children }: { children: ReactNode }) {
     }
   }, [decks, loading]);
 
-  // Listen for file changes via SSE (so agent edits show up in real-time)
+  // Listen for deck changes via SSE (so agent edits show up in real-time).
+  //
+  // EventSource auto-reconnects on its own ONLY for network-level drops
+  // (readyState stays CONNECTING while it retries). A non-2xx HTTP response
+  // — e.g. a transient 503 during a cold start — is FATAL per spec: the
+  // browser sets readyState CLOSED and never retries. Without our own
+  // reconnect logic, a single 503 permanently kills live updates for the
+  // rest of the tab's life (the rail goes stale until a manual reload).
+  //
+  // We reconnect manually with bounded exponential backoff, and because
+  // notifyClients() on the server has no backlog/replay (fire-and-forget to
+  // whatever connections are live at broadcast time — see
+  // server/handlers/decks.ts), every reconnect after the first triggers a
+  // full resync via resyncDeckState() so agent writes made during the gap
+  // aren't silently lost.
   useEffect(() => {
     if (isEmbedAuthActive()) return;
-    const evtSource = new EventSource(`${appBasePath()}/api/decks/events`);
-    evtSource.onmessage = async (event) => {
+    let stopped = false;
+    let es: EventSource | null = null;
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+    let retryCount = 0;
+    let hasConnectedOnce = false;
+
+    const isHidden = () =>
+      typeof document !== "undefined" && document.visibilityState === "hidden";
+
+    const clearReconnectTimer = () => {
+      if (reconnectTimer) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+      }
+    };
+
+    const scheduleReconnect = () => {
+      if (stopped || reconnectTimer || isHidden()) return;
+      const delay = Math.min(
+        SSE_RECONNECT_BASE_MS * 2 ** retryCount,
+        SSE_RECONNECT_MAX_MS,
+      );
+      retryCount += 1;
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        connect();
+      }, delay);
+    };
+
+    const handleMessage = async (event: MessageEvent) => {
       try {
         const data = JSON.parse(event.data);
         if (data.type === "deck-deleted" && data.deckId) {
@@ -1211,8 +1393,67 @@ export function DeckProvider({ children }: { children: ReactNode }) {
         }
       } catch {}
     };
-    return () => evtSource.close();
-  }, [applyRemoteDeckUpdate]);
+
+    const connect = () => {
+      if (stopped || isHidden()) return;
+      // Never leak the previous connection.
+      if (es) {
+        es.close();
+        es = null;
+      }
+      const next = new EventSource(`${appBasePath()}/api/decks/events`);
+      es = next;
+      next.onmessage = handleMessage;
+      next.onopen = () => {
+        retryCount = 0;
+        // Every reconnect after the first can have missed broadcasts made
+        // while we were disconnected — the SSE channel has no backlog, so
+        // resync authoritative state instead of trusting the stream alone
+        // to have caught us up.
+        if (hasConnectedOnce) {
+          void resyncDeckState();
+        }
+        hasConnectedOnce = true;
+      };
+      next.onerror = () => {
+        if (es !== next) return;
+        if (next.readyState === EventSource.CLOSED) {
+          // Fatal per spec (non-2xx status, bad content-type, etc.) — the
+          // browser will not retry on its own. Reconnect ourselves.
+          next.close();
+          es = null;
+          scheduleReconnect();
+        }
+        // readyState === CONNECTING means the browser is already retrying a
+        // network-level drop on its own; onopen above resyncs once that
+        // succeeds.
+      };
+    };
+
+    const handleVisibilityChange = () => {
+      if (isHidden()) {
+        clearReconnectTimer();
+        return;
+      }
+      retryCount = 0;
+      if (!es || es.readyState === EventSource.CLOSED) {
+        connect();
+      }
+    };
+
+    connect();
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+
+    return () => {
+      stopped = true;
+      clearReconnectTimer();
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      if (es) {
+        es.close();
+        es = null;
+      }
+    };
+  }, [applyRemoteDeckUpdate, resyncDeckState]);
 
   // Flush pending (debounced) saves before the tab is hidden or unloaded so the
   // last ~500ms of edits aren't lost on close/navigation. `pagehide` is the
diff --git a/templates/slides/changelog/2026-07-09-fixed-the-slide-rail-going-permanently-stale-during-a-long-a.md b/templates/slides/changelog/2026-07-09-fixed-the-slide-rail-going-permanently-stale-during-a-long-a.md
new file mode 100644
index 0000000000..61d9088e08
--- /dev/null
+++ b/templates/slides/changelog/2026-07-09-fixed-the-slide-rail-going-permanently-stale-during-a-long-a.md
@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Fixed the slide rail going permanently stale during a long agent run if the live-update connection dropped, so new slides now show up without needing a page reload