@agent-native/core 0.128.3 → 0.129.0

package/corpus/templates/content/actions/_builder-docs-client.ts

@@ -194,19 +194,43 @@ async function postBuilderMcp(args: {
   endpoint: string;
   privateKey: string;
   payload: Record<string, unknown>;
-  sessionId?: string | null;
+  connection?: BuilderMcpConnection;
+  modernClientName?: string;
   fetchImpl: FetchLike;
 }) {
+  const method =
+    typeof args.payload.method === "string" ? args.payload.method : "";
+  const modernClientName =
+    args.modernClientName ??
+    (args.connection?.protocolVersion === "2026-07-28"
+      ? "agent-native-content-builder-mdx"
+      : undefined);
+  const payload = modernClientName
+    ? withModernBuilderMcpEnvelope(args.payload, modernClientName)
+    : args.payload;
   const headers: Record<string, string> = {
     accept: "application/json, text/event-stream",
     authorization: `Bearer ${args.privateKey}`,
     "content-type": "application/json",
   };
-  if (args.sessionId) headers["mcp-session-id"] = args.sessionId;
+  if (args.connection?.sessionId) {
+    headers["mcp-session-id"] = args.connection.sessionId;
+  }
+  if (modernClientName) {
+    headers["mcp-protocol-version"] = "2026-07-28";
+    headers["mcp-method"] = method;
+    const params = args.payload.params as Record<string, unknown> | undefined;
+    if (typeof params?.name === "string") {
+      headers["mcp-name"] = params.name;
+    }
+    if (method === "resources/read" && typeof params?.uri === "string") {
+      headers["mcp-name"] = params.uri;
+    }
+  }
   const response = await args.fetchImpl(args.endpoint, {
     method: "POST",
     headers,
-    body: JSON.stringify(args.payload),
+    body: JSON.stringify(payload),
   });
   const text = await response.text();
   if (!response.ok) {
@@ -218,44 +242,141 @@ async function postBuilderMcp(args: {
   };
 }
 
+interface BuilderMcpConnection {
+  protocolVersion: "2026-07-28" | "2025-11-25" | "2024-11-05";
+  sessionId: string | null;
+}
+
+function withModernBuilderMcpEnvelope(
+  payload: Record<string, unknown>,
+  clientName: string,
+): Record<string, unknown> {
+  const params =
+    payload.params &&
+    typeof payload.params === "object" &&
+    !Array.isArray(payload.params)
+      ? (payload.params as Record<string, unknown>)
+      : {};
+  const meta =
+    params._meta &&
+    typeof params._meta === "object" &&
+    !Array.isArray(params._meta)
+      ? (params._meta as Record<string, unknown>)
+      : {};
+  return {
+    ...payload,
+    params: {
+      ...params,
+      _meta: {
+        ...meta,
+        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+        "io.modelcontextprotocol/clientInfo": {
+          name: clientName,
+          version: "0.1.0",
+        },
+        "io.modelcontextprotocol/clientCapabilities": {},
+      },
+    },
+  };
+}
+
 async function initializeBuilderMcp(args: {
   endpoint: string;
   privateKey: string;
   fetchImpl: FetchLike;
 }) {
-  const initialized = await postBuilderMcp({
-    endpoint: args.endpoint,
-    privateKey: args.privateKey,
-    fetchImpl: args.fetchImpl,
-    payload: {
-      jsonrpc: "2.0",
-      id: 1,
-      method: "initialize",
-      params: {
-        protocolVersion: "2024-11-05",
-        capabilities: {},
-        clientInfo: {
-          name: "agent-native-content-builder-mdx",
-          version: "0.1.0",
-        },
-      },
-    },
-  });
-  const sessionId = initialized.sessionId;
-  if (sessionId) {
-    await postBuilderMcp({
+  try {
+    const discovered = await postBuilderMcp({
       endpoint: args.endpoint,
       privateKey: args.privateKey,
       fetchImpl: args.fetchImpl,
-      sessionId,
       payload: {
         jsonrpc: "2.0",
-        method: "notifications/initialized",
+        id: 1,
+        method: "server/discover",
         params: {},
       },
-    }).catch(() => null);
+    });
+    const result = discovered.json.result;
+    if (
+      result &&
+      typeof result === "object" &&
+      Array.isArray((result as Record<string, unknown>).supportedVersions) &&
+      (
+        (result as Record<string, unknown>).supportedVersions as unknown[]
+      ).includes("2026-07-28")
+    ) {
+      return {
+        protocolVersion: "2026-07-28",
+        sessionId: null,
+      } satisfies BuilderMcpConnection;
+    }
+  } catch (error) {
+    // A legacy server may reject server/discover before initialize.
+    if (
+      !(error instanceof Error) ||
+      !/HTTP (?:400|404|405)\./.test(error.message)
+    ) {
+      throw error;
+    }
+  }
+
+  const initializeLegacyProtocol = async (
+    protocolVersion: "2025-11-25" | "2024-11-05",
+  ) => {
+    const initialized = await postBuilderMcp({
+      endpoint: args.endpoint,
+      privateKey: args.privateKey,
+      fetchImpl: args.fetchImpl,
+      payload: {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion,
+          capabilities: {},
+          clientInfo: {
+            name: "agent-native-content-builder-mdx",
+            version: "0.1.0",
+          },
+        },
+      },
+    });
+    if (initialized.json.error) {
+      throw new Error(
+        `Builder MCP initialize rejected protocol ${protocolVersion}.`,
+      );
+    }
+    const sessionId = initialized.sessionId;
+    if (sessionId) {
+      await postBuilderMcp({
+        endpoint: args.endpoint,
+        privateKey: args.privateKey,
+        fetchImpl: args.fetchImpl,
+        connection: { protocolVersion, sessionId },
+        payload: {
+          jsonrpc: "2.0",
+          method: "notifications/initialized",
+          params: {},
+        },
+      }).catch(() => null);
+    }
+    return {
+      protocolVersion,
+      sessionId,
+    } satisfies BuilderMcpConnection;
+  };
+
+  try {
+    return await initializeLegacyProtocol("2025-11-25");
+  } catch (error) {
+    const isProtocolRejection =
+      error instanceof Error &&
+      (/HTTP (?:400|404|405|422)\./.test(error.message) ||
+        error.message.includes("initialize rejected protocol"));
+    if (!isProtocolRejection) throw error;
+    return await initializeLegacyProtocol("2024-11-05");
   }
-  return sessionId;
 }
 
 function fullEntryFromToolResponse(value: unknown, model: string) {
@@ -363,7 +484,7 @@ async function readFullBuilderDocsEntryViaMcp(args: {
   privateKey: string;
 }) {
   const endpoint = builderMcpEndpoint();
-  const sessionId = await initializeBuilderMcp({
+  const connection = await initializeBuilderMcp({
     endpoint,
     privateKey: args.privateKey,
     fetchImpl: args.fetchImpl,
@@ -372,7 +493,7 @@ async function readFullBuilderDocsEntryViaMcp(args: {
     endpoint,
     privateKey: args.privateKey,
     fetchImpl: args.fetchImpl,
-    sessionId,
+    connection,
     payload: {
       jsonrpc: "2.0",
       id: `builder-mdx-${args.model}-${args.entryId}`,

package/corpus/templates/content/actions/stage-builder-source-bulk-update.ts

@@ -39,6 +39,7 @@ const supportedBulkPropertyTypes = new Set<DocumentPropertyType>([
   "url",
   "email",
   "phone",
+  "files_media",
 ]);
 
 function parseSourceValues(
@@ -577,7 +578,9 @@ const fieldSchema = z.object({
         .passthrough(),
       z.null(),
     ])
-    .describe("Value to set on the mapped Builder-backed field."),
+    .describe(
+      "Value to set on the mapped Builder-backed field. Builder File fields accept one http(s) URL as a string or one-item array; no media-picker upload is required.",
+    ),
 });
 
 export const stageBuilderSourceBulkUpdateSchema = z
@@ -645,7 +648,7 @@ export { stageBuilderSourceBulkUpdateWithDeps };
 
 export default defineAction({
   description:
-    "Preview or stage one bounded bulk update across selected source-backed Builder CMS rows. This only stages local reviewable diffs; Builder writeback still goes through the existing review and execution actions.",
+    "Preview or stage one bounded bulk update across selected source-backed Builder CMS rows, including Builder File fields backed by Content Files & media properties. This only stages local reviewable diffs; Builder writeback still goes through the existing review and execution actions.",
   schema: stageBuilderSourceBulkUpdateSchema,
   run: async (
     args: StageBuilderSourceBulkUpdateRequest,

package/corpus/templates/content/app/root.tsx

@@ -1,4 +1,3 @@
-import { AgentSidebar } from "@agent-native/core/client/agent-chat";
 import { configureTracking } from "@agent-native/core/client/analytics";
 import { appPath } from "@agent-native/core/client/api-path";
 import {
@@ -34,7 +33,14 @@ import {
   IconSun,
 } from "@tabler/icons-react";
 import { useTheme } from "next-themes";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import {
+  lazy,
+  Suspense,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
 import {
   Links,
   Meta,
@@ -119,6 +125,11 @@ export function shouldRevalidate({
 // Pass args to match content's 3-way theme-cycle UX (no disableTransitionOnChange).
 const THEME_INIT_SCRIPT = getThemeInitScript("system", true);
 
+const LazyAgentSidebar = lazy(async () => {
+  const { AgentSidebar } = await import("@agent-native/core/client/agent-chat");
+  return { default: AgentSidebar };
+});
+
 const DEFAULT_LOADER_DATA: RootLoaderData = {
   locale: "en-US",
   preference: { locale: "system" },
@@ -509,19 +520,29 @@ function PublicAgentShell({ children }: { children: React.ReactNode }) {
   }
 
   return (
-    <AgentSidebar
-      position="right"
-      defaultOpen={false}
-      defaultSidebarWidth={420}
-      emptyStateText={t("chat.publicEmptyState")}
-      suggestions={[
-        t("chat.publicSuggestionSummary"),
-        t("chat.publicSuggestionTakeaways"),
-        t("chat.publicSuggestionActionPlan"),
-      ]}
+    <Suspense
+      fallback={
+        <div className="flex min-w-0 flex-1 h-screen overflow-hidden">
+          <div className="flex min-w-0 flex-1 flex-col overflow-auto">
+            {content}
+          </div>
+        </div>
+      }
     >
-      {content}
-    </AgentSidebar>
+      <LazyAgentSidebar
+        position="right"
+        defaultOpen={false}
+        defaultSidebarWidth={420}
+        emptyStateText={t("chat.publicEmptyState")}
+        suggestions={[
+          t("chat.publicSuggestionSummary"),
+          t("chat.publicSuggestionTakeaways"),
+          t("chat.publicSuggestionActionPlan"),
+        ]}
+      >
+        {content}
+      </LazyAgentSidebar>
+    </Suspense>
   );
 }
 

package/corpus/templates/content/changelog/2026-07-28-builder-backed-files-media-fields-now-accept-direct-file-url.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Builder-backed Files & media fields now accept direct file URLs in bulk updates.

package/corpus/templates/content/changelog/2026-07-28-builder-content-reads-now-negotiate-the-newest-mcp-protocol-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-28
+---
+
+Builder content reads now negotiate the newest MCP protocol while remaining compatible with legacy servers.

package/corpus/templates/content/changelog/2026-07-28-public-content-pages-load-faster-before-the-optional-ask-sid.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-28
+---
+
+Public content pages load faster before the optional Ask sidebar appears

package/corpus/templates/design/.agents/skills/security/SKILL.md

@@ -163,7 +163,9 @@ private UI after the shell loads. See the `authentication` skill and
 proves *someone* is signed in. To restrict an operation to some teammates, set
 `authorize` on the `defineAction`. It wraps `run`, so it applies at every
 dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
-`needsApproval`, which is honoured only in the agent loop.
+`needsApproval`, which is honored by the agent loop and MCP 2026 hosts that
+support elicitation, but is not an authorization boundary for every dispatch
+site.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -203,7 +205,16 @@ export default defineAction({
 });
 ```
 
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
+When the gate is truthy and the call is not yet approved, the agent loop emits
+an `approval_required` event and **stops the turn — `run()` never executes**.
+The human approves via the chat UI's Approve affordance, which re-issues the
+turn with the call's stable `approvalKey`; only then does the action run. MCP
+2026 hosts receive an `input_required` approval request bound to the exact
+caller, action, and arguments. The signed response state is backed by a durable,
+single-use grant, so denial, expiry, replay, missing host support, or invalid
+state fails closed before `run()`. A predicate gates conditionally (e.g. only
+external recipients) and **fails closed** — a throw is treated as "approval
+required".
 
 Rules:
 

package/corpus/templates/design/.agents/skills/visual-edit/SKILL.md

@@ -27,10 +27,18 @@ exported instructions only, with no MCP connector registration.
 
 ## Put Design Beside The Chat
 
-After `open-visual-edit` returns `openUrl`, open that URL in the coding host's
-inline browser when one is available. This is the preferred working surface:
-the user can keep Design's canvas beside the conversation, inspect the same
-screens as the agent, and iterate without switching apps.
+Prefer the interactive MCP App returned by `open-visual-edit` when the coding
+host renders it. The user gets the Design canvas beside the conversation, and
+**Apply design updates** can submit the bounded source-edit handoff back to the
+current host conversation through the standard MCP Apps message bridge. The
+host may ask the user to confirm the current conversation or choose a new one.
+
+Otherwise, after `open-visual-edit` returns `openUrl`, open that URL in the
+coding host's inline browser when one is available. This still keeps Design
+beside the conversation, but an ordinary browser page has no trusted path into
+the host's current composer. In that fallback surface, **Apply design updates**
+uses Design's local agent; use **Copy prompt to your agent** to hand the same
+structured edit batch to the coding agent.
 
 - In Codex Desktop, use the in-app Browser tool to open `openUrl`. The built-in
   browser is the right surface for localhost and public pages that should stay
@@ -42,14 +50,13 @@ screens as the agent, and iterate without switching apps.
   sessions may not expose one. If the inline surface is unavailable or disabled,
   return the normal **Open design** link instead of claiming it opened.
 
-Prefer the host's browser/preview tool over telling the user to press a keyboard
-shortcut. Keep the canvas pane beside chat when the host supports rearrangeable
-panes.
+Prefer the MCP App surface for a connected Design plugin, then the host's
+browser/preview tool as the universal fallback. Keep the canvas beside chat
+when the host supports rearrangeable panes.
 
-Inside Design, use **Show/Hide UI** from the `Cmd+K` menu or press
-`Cmd+Shift+\` on Apple platforms / `Ctrl+Shift+\` elsewhere to toggle all
-editing chrome so only the canvas remains. The same action is available from
-Design's empty-canvas context menu.
+Inside Design, use **Show/Hide UI** from the `Cmd+K` menu or press Figma's
+`Shift+\` shortcut to toggle all editing chrome so only the canvas remains.
+The same action is available from Design's empty-canvas context menu.
 
 ## Core Model
 
@@ -57,8 +64,16 @@ Design's empty-canvas context menu.
 - Each screen keeps URL metadata: `connectionId`, `routeId`, `path`,
   `url`, `bridgeUrl`, title, and viewport size.
 - Localhost Edit mode renders the running app through the local bridge as a live
-  iframe with the same editor bridge used by HTML designs. It is not a frozen
-  static DOM snapshot.
+  iframe with the same editor bridge used by HTML designs. It is never a frozen
+  static DOM snapshot. Editing is direct DOM manipulation against that live
+  document; the parallel `/snapshot` fetch feeds the editable source model only
+  and must never be rendered in the frame.
+- A viewer holding the connection's `previewToken` gets the proxied
+  `/live-edit` document with editor chrome. A viewer without one — a signed-out
+  session, a public link, or an inline browser with no cookies — gets the plain
+  dev-server URL: still live, but with no editor chrome, no layers, and no
+  editing. If the canvas looks right but selection and the layers panel do
+  nothing, the frame is unbridged; sign in rather than assuming Design is broken.
 - The live editor is same-origin through the local bridge proxy. This boots
   CSR apps and root-relative assets, but it is still a localhost editing proxy:
   app-origin cookies, WebSockets/HMR, SSE, and non-GET app API calls may need a
@@ -336,9 +351,11 @@ Fallback, only when `open-visual-edit` is unavailable:
 ## Applying Visual Edits Back To Source
 
 Canvas edits on a localhost screen do not write source as you make them. They
-accumulate as pending edits and the editor shows an "Apply with Design agent"
-button in the bottom-right corner of the canvas. Clicking it hands a structured
-prompt to the Design agent chat, which performs the real source write.
+accumulate as pending edits and the editor shows an **Apply design updates**
+button on the canvas. In an MCP App, clicking it hands the bounded structured
+prompt to the current host coding conversation. In an ordinary browser or
+standalone Design page, it falls back to the local Design agent. The dropdown's
+**Copy prompt to your agent** action is the universal manual fallback.
 
 - Style, text, and drag/drop structure edits all collect into the same pending
   batch, so the user can make several changes and apply once.
@@ -410,6 +427,9 @@ the connected app's text/code files through the bridge
 - The Design editor opens in overview mode.
 - Every requested screen renders the intended localhost URL, showing real app
   content rather than an endless loading spinner.
+- The screen iframe carries a `src`, not a `srcdoc`. A localhost screen with a
+  `srcdoc` is a bug, not a slow load — check it in the browser devtools before
+  reporting the canvas as working.
 - Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.
 - A query/path edit changes only the target screen's URL metadata and iframe.
 - The Code tab shows a local-files root for the connection and opens its files.

package/corpus/templates/design/.generated/bridge/editor-chrome.generated.ts

@@ -3152,6 +3152,9 @@ export const editorChromeBridgeScript: string = `"use strict";
         return true;
       }
       if (/^Arrow/.test(key || "")) return !e.altKey;
+      if (!primary && !e.altKey && e.shiftKey && e.code === "Backslash") {
+        return true;
+      }
       if (primary) {
         return [
           "z",
@@ -3185,9 +3188,7 @@ export const editorChromeBridgeScript: string = `"use strict";
         // 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+Shift+\\ — minimize UI (onToggleUi). Keep the Shift gate
-        // here so the iframe never intercepts a desktop host's bare Cmd/Ctrl+\\.
-        e.shiftKey && normalized === "\\\\" || // Cmd/Ctrl+Alt+B detach instance / Cmd/Ctrl+Alt+K create component
+        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 is left alone — the host has no bare-primary binding for it.
         e.altKey && (normalized === "b" || normalized === "k") || // Ctrl+Alt+H / Ctrl+Alt+T — distribute horizontal / tidy up
@@ -8245,6 +8246,44 @@ export const editorChromeBridgeScript: string = `"use strict";
     });
     window.addEventListener("scroll", scheduleRefreshOverlays, true);
     window.addEventListener("resize", scheduleRefreshOverlays);
+    function isNativeInteractionNetExempt(target) {
+      return isOverlayElement(target) || isEditorTypingTarget(target) || !!activeDragCancel;
+    }
+    function interceptNativeInteractionNet(e) {
+      if (readOnly) return;
+      var target = e.target && e.target.nodeType === 1 ? e.target : null;
+      if (isNativeInteractionNetExempt(target)) return;
+      stopNativeInteraction(e);
+    }
+    [
+      "click",
+      "auxclick",
+      "dblclick",
+      "mousedown",
+      "mouseup",
+      "pointerdown",
+      "pointerup",
+      "submit"
+    ].forEach(function(type) {
+      document.addEventListener(type, interceptNativeInteractionNet, true);
+    });
+    function isFocusedActivationTarget(target) {
+      return !!(target && target.closest && target.closest(
+        'a[href], button, summary, input[type="submit"], input[type="button"], input[type="reset"], input[type="image"], [role="button"], [role="link"]'
+      ));
+    }
+    document.addEventListener(
+      "keydown",
+      function(e) {
+        if (readOnly) return;
+        if (e.key !== "Enter" && !(e.key === " " && e.code === "Space")) return;
+        var target = e.target && e.target.nodeType === 1 ? e.target : null;
+        if (isNativeInteractionNetExempt(target)) return;
+        if (!isFocusedActivationTarget(target)) return;
+        stopNativeInteraction(e);
+      },
+      true
+    );
     applyEditorChromeScale();
     if (runtimeLayerSnapshotEnabled && typeof MutationObserver !== "undefined" && document.body) {
       var runtimeLayerObserver = new MutationObserver(function(mutations) {

package/corpus/templates/design/actions/open-visual-edit.ts

@@ -303,7 +303,8 @@ export default defineAction({
     compactCatalog: true,
     resource: embedApp({
       title: "Local visual edit",
-      description: "Open local URL-backed screens in Design overview mode.",
+      description:
+        "Review local URL-backed screens and hand pending source edits back to the host coding agent.",
       iframeTitle: "Agent-Native Design",
       openLabel: "Open overview",
       height: 680,

package/corpus/templates/design/app/components/design/CanvasContextMenu.tsx

@@ -52,7 +52,7 @@ import type { CanvasLayerHitCandidate } from "./types";
 // EMPTY canvas (no selection):
 //   Paste here
 //   [sep]
-//   Show/Hide UI ⇧⌘\ · Show/Hide comments ⇧C
+//   Show/Hide UI ⇧\ · Show/Hide comments ⇧C
 //
 // Real Figma has no Duplicate/Delete/Select-all/Zoom items on either canvas
 // menu (all keyboard-only there) — those are intentionally NOT rendered here
@@ -461,7 +461,7 @@ const DEFAULT_SHORTCUTS: CanvasContextMenuShortcuts = {
   rotateClockwise: "",
   flipHorizontal: "⇧H",
   flipVertical: "⇧V",
-  toggleUi: "⇧⌘\\",
+  toggleUi: "⇧\\",
   toggleComments: "⇧C",
 };
 

package/corpus/templates/design/app/components/design/DesignCanvas.tsx

@@ -1398,10 +1398,6 @@ export function DesignCanvas({
     bridgeUrl,
     liveEditBridgeKey,
   );
-  const hasLiveEditExternalFrame =
-    sourceType === "localhost" && Boolean(bridgeUrl && rawExternalPreviewUrl);
-  const hasAuthenticatedLiveEditExternalFrame =
-    hasLiveEditExternalFrame && Boolean(previewToken);
   const usesLiveEditInjectedBridge =
     sourceType === "localhost" &&
     Boolean(bridgeUrl && previewToken && rawExternalPreviewUrl);
@@ -1440,12 +1436,15 @@ export function DesignCanvas({
   // bridge, so crossing that boundary must use the latest persisted `content`
   // or native hover/focus/pressed behavior would run against the stale HTML
   // from before the inspector edits.
-  const iframeRenderContent =
-    !hasAuthenticatedLiveEditExternalFrame && activeExternalSnapshotHtml
-      ? activeExternalSnapshotHtml
-      : interactMode
-        ? content
-        : renderedContent;
+  //
+  // A localhost screen NEVER renders `activeExternalSnapshotHtml`. The snapshot
+  // is the editable source model only. Rendering it produced a frame that looked
+  // exactly like the running app but was a corpse: no live DOM to manipulate,
+  // layers parsed from frozen HTML, and every edit applied to markup the app had
+  // already moved past — a failure indistinguishable from success. A viewer with
+  // no bridge entitlement gets the real dev-server URL instead (see
+  // externalPreviewUrl below), which is live even without editor chrome.
+  const iframeRenderContent = interactMode ? content : renderedContent;
 
   const desktopNativeSnapshot = useDesktopDesignNativePreview({
     iframeRef,
@@ -1476,13 +1475,13 @@ export function DesignCanvas({
     editMode,
     hasLiveEditorBridge: usesLiveEditEditorBridge,
   });
+  // Null only while an entitled viewer's keyed bridge is still registering, so
+  // the frame mounts once directly at the proxied document (resolveLiveEditPreviewUrl's
+  // flash/state-loss note). A viewer with no previewToken has no bridge to wait
+  // for, so it loads the dev server directly rather than degrading to a snapshot.
   const externalPreviewUrl =
     liveEditExternalPreviewUrl ??
-    (hasLiveEditExternalFrame
-      ? null
-      : activeExternalSnapshotHtml
-        ? null
-        : rawExternalPreviewUrl);
+    (usesLiveEditInjectedBridge ? null : rawExternalPreviewUrl);
   const runtimeVerificationUrl = useMemo(() => {
     if (!runtimeVerificationRequest || !externalPreviewUrl) return null;
     return externalPreviewUrl;