@agent-native/core 0.161.8 → 0.161.9

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8292
+- template files: 8299

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

@@ -7,6 +7,7 @@ import { useT } from "@agent-native/core/client/i18n";
 import { type ReviewThread } from "@agent-native/core/client/review";
 import type { ReviewComment } from "@agent-native/core/review";
 import { injectDocumentMarkup } from "@agent-native/core/shared";
+import { isLoopbackPreviewAllowed } from "@shared/builder-preview-url";
 import {
   DEFAULT_CANVAS_MAX_ZOOM,
   DEFAULT_CANVAS_MIN_ZOOM,
@@ -39,6 +40,7 @@ import {
 import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
+import { Spinner } from "@/components/ui/spinner";
 // NOTE: This wires up the NEW shared visual-editor DrawOverlay + comment-pin
 // components from `@/components/visual-editor`. The legacy iframe-only
 // DrawOverlay at `./DrawOverlay.tsx` is intentionally NOT used here — both
@@ -150,8 +152,15 @@ function isAllowedFusionOrigin(
   } catch {
     return false;
   }
-  // Only allow secure (https) Builder origins.
-  if (protocol !== "https:") return false;
+  // Only allow secure (https) Builder origins. Loopback is a development-only
+  // exception: without it every bridge message from a local proxy is dropped.
+  if (protocol !== "https:") {
+    const loopbackDev =
+      isLoopbackPreviewAllowed() &&
+      (host === "localhost" || host === "127.0.0.1" || host === "[::1]");
+    if (!loopbackDev) return false;
+    return true;
+  }
   // Exact match against the configured fusion URL's origin.
   if (fusionUrl) {
     try {
@@ -1401,27 +1410,27 @@ export function DesignCanvas({
   );
   const onExternalContentSnapshotRef = useRef(onExternalContentSnapshot);
   const isEmbeddedFrame = Boolean(embeddedFrame);
-  // Resolve the URL to render in the iframe:
-  // 1. When sourceType === "fusion" and fusionUrl is set, prefer the explicit
-  //    Builder-hosted URL over whatever is in `content` (which may still be the
-  //    original inline HTML).
-  // 2. Otherwise fall back to the content-based URL detection (handles the case
-  //    where the branch URL has been written into the design file content, or
-  //    where the localhost URL is the file content).
+  // The screen's own URL wins: it carries the route path and may address the
+  // container through a same-origin proxy. `fusionUrl` only covers fusion
+  // screens whose content is still the original inline HTML.
   const rawExternalPreviewUrl = useMemo(() => {
+    const contentUrl = getExternalPreviewUrl(renderedContent);
+    if (contentUrl) return contentUrl;
     if (sourceType === "fusion" && fusionUrl) {
       try {
         const url = new URL(fusionUrl);
         url.hash = "";
         return url.toString();
       } catch {
-        // fall through to content detection below
+        // coercion-ok: an unparseable URL has no frame to render; the screen
+        // falls back to its own content, as it did before any fusion linkage.
+        return null;
       }
     }
-    return getExternalPreviewUrl(renderedContent);
+    return null;
   }, [fusionUrl, renderedContent, sourceType]);
   const runtimeLayerSnapshotEnabled =
-    sourceType === "localhost" &&
+    (sourceType === "localhost" || sourceType === "fusion") &&
     Boolean(rawExternalPreviewUrl) &&
     Boolean(onRuntimeLayerSnapshot);
   const activeExternalSnapshotHtml =
@@ -1606,6 +1615,117 @@ export function DesignCanvas({
   runtimeReplacementContentRef.current = runtimeReplacementContent;
   runtimeReplacementKeyRef.current = runtimeReplacementKey;
 
+  // A framed container has no dev-server bridge to register the editor chrome
+  // with, so it goes over postMessage to the bootstrap its proxy injects.
+  const containerPreview = useMemo(() => {
+    // Not the localhost live-edit path: there the bridge server injects the
+    // bridge into its own proxied document, so nothing is posted from here.
+    if (usesLiveEditInjectedBridge) return false;
+    if (!externalPreviewUrl || typeof window === "undefined") return false;
+    try {
+      return (
+        new URL(externalPreviewUrl, window.location.href).origin !==
+        window.location.origin
+      );
+      // coercion-ok: an unparseable URL frames nothing to bridge into.
+    } catch {
+      return false;
+    }
+  }, [externalPreviewUrl, usesLiveEditInjectedBridge]);
+  const installedBridgeKeyRef = useRef<string | null>(null);
+  const sendBridgeToContainer = useCallback(() => {
+    if (!containerPreview || !includeLiveEditEditorChrome) {
+      console.log("[design:bridge] install skipped", {
+        containerPreview,
+        includeLiveEditEditorChrome,
+      });
+      return;
+    }
+    const target = iframeRef.current?.contentWindow;
+    if (!target || !externalPreviewUrl) {
+      console.log("[design:bridge] install skipped", {
+        hasTarget: Boolean(target),
+        externalPreviewUrl,
+      });
+      return;
+    }
+    if (installedBridgeKeyRef.current === liveEditBridgeKey) return;
+    let origin: string;
+    try {
+      origin = new URL(externalPreviewUrl, window.location.href).origin;
+      // coercion-ok: without a parseable origin there is nowhere safe to post.
+    } catch {
+      return;
+    }
+    try {
+      // Never "*": the bridge carries editor internals, and the container is
+      // the only window that should receive it.
+      target.postMessage(
+        {
+          type: "agentNative.installBridge",
+          key: liveEditBridgeKey,
+          script: liveEditBridgeScript,
+        },
+        origin,
+      );
+    } catch (error) {
+      // Leave the key unmarked: `bridgeReady` drives the real install, and
+      // marking a failed attempt disables the bridge for the document's life.
+      console.error("[design:bridge] install post threw", origin, error);
+      return;
+    }
+    console.log(
+      "[design:bridge] install posted from",
+      window.location.origin,
+      "to",
+      origin,
+    );
+    installedBridgeKeyRef.current = liveEditBridgeKey;
+  }, [
+    containerPreview,
+    externalPreviewUrl,
+    includeLiveEditEditorChrome,
+    liveEditBridgeKey,
+    liveEditBridgeScript,
+  ]);
+  // The bootstrap announces itself on every document load, which is also how a
+  // reload or in-frame navigation asks for the bridge again.
+  useEffect(() => {
+    if (!containerPreview) return;
+    function onBootstrapMessage(event: MessageEvent) {
+      if (event.source !== iframeRef.current?.contentWindow) return;
+      // A failed install must not read as an installed one, or the retry below
+      // never fires and the canvas silently loses selection and inline editing.
+      if (event.data?.type === "agentNative.bridgeFailed") {
+        installedBridgeKeyRef.current = null;
+        console.error(
+          "[design] editor bridge failed to install in the preview:",
+          event.data?.message,
+        );
+        return;
+      }
+      if (event.data?.type === "agentNative.bridgeRejected") {
+        installedBridgeKeyRef.current = null;
+        console.error(
+          `[design] the preview container refused the editor bridge from ${window.location.origin}. ` +
+            "Containers install it only for https://design.agent-native.com, so selection " +
+            "and inline editing are dead anywhere else.",
+        );
+        return;
+      }
+      if (event.data?.type === "agentNative.bridgeInstalled") {
+        console.log("[design:bridge] installed", event.data?.key);
+        return;
+      }
+      if (event.data?.type !== "agentNative.bridgeReady") return;
+      console.log("[design:bridge] container reported ready");
+      installedBridgeKeyRef.current = null;
+      sendBridgeToContainer();
+    }
+    window.addEventListener("message", onBootstrapMessage);
+    return () => window.removeEventListener("message", onBootstrapMessage);
+  }, [containerPreview, sendBridgeToContainer]);
+
   useEffect(() => {
     onExternalContentSnapshotRef.current = onExternalContentSnapshot;
   }, [onExternalContentSnapshot]);
@@ -2336,6 +2456,23 @@ export function DesignCanvas({
   // long tasks. Memoizing on the (already-stable) `srcdoc` reference
   // makes unrelated re-renders skip this entirely.
   const srcdocHash = useMemo(() => contentHash(srcdoc ?? ""), [srcdoc]);
+  /**
+   * A container we framed ourselves is cross-origin, so its messages match
+   * neither `parentOrigin` nor the localhost bridge origin. Without its origin
+   * here every selection, hover and layer message from the editor bridge is
+   * dropped as untrusted while the bootstrap handshake still succeeds.
+   */
+  const canvasBridgeAllowedOrigins = useMemo(
+    () =>
+      [
+        sourceType === "localhost" && bridgeUrl
+          ? originFromUrl(bridgeUrl)
+          : null,
+        externalPreviewUrl ? originFromUrl(externalPreviewUrl) : null,
+      ].filter((origin): origin is string => Boolean(origin)),
+    [bridgeUrl, externalPreviewUrl, sourceType],
+  );
+
   const iframeDocumentIdentity = externalPreviewUrl
     ? `src:${externalPreviewUrl}`
     : waitingForLiveEditBridge
@@ -2345,6 +2482,12 @@ export function DesignCanvas({
     previousIframeDocumentIdentityRef.current = iframeDocumentIdentity;
     bridgeReadyRef.current = false;
   }
+  // Only a URL-backed frame boots: srcdoc paints synchronously, so gating it on
+  // an onLoad that already fired would strand a spinner over finished content.
+  const [previewFrameLoaded, setPreviewFrameLoaded] = useState(false);
+  useEffect(() => {
+    setPreviewFrameLoaded(false);
+  }, [iframeDocumentIdentity]);
   // No snapshot is ever painted over the live frame, not even for the few
   // frames of a document swap. Covering the real iframe with a frozen copy is
   // the same false-success shape as rendering the snapshot outright: when the
@@ -2354,6 +2497,12 @@ export function DesignCanvas({
     usesLiveEditEditorBridge &&
     Boolean(externalPreviewUrl) &&
     readyIframeDocumentIdentity !== iframeDocumentIdentity;
+  // A proxied container paints its own app immediately, so without this the
+  // canvas looks ready while hover, selection and layers are still dead.
+  const sameOriginBridgePending =
+    containerPreview &&
+    includeLiveEditEditorChrome &&
+    readyIframeDocumentIdentity !== iframeDocumentIdentity;
 
   // Listen for messages from the iframe
   useEffect(() => {
@@ -2370,12 +2519,7 @@ export function DesignCanvas({
           origin: e.origin,
           iframeWindow: runtimeVerificationWindow,
           parentOrigin: window.location.origin,
-          allowedOrigins:
-            sourceType === "localhost" && bridgeUrl
-              ? [originFromUrl(bridgeUrl)].filter((origin): origin is string =>
-                  Boolean(origin),
-                )
-              : [],
+          allowedOrigins: canvasBridgeAllowedOrigins,
         });
       if (trustedRuntimeVerificationFrame) {
         if (e.data?.type !== "agent-native:runtime-layer-snapshot") return;
@@ -2402,16 +2546,11 @@ export function DesignCanvas({
         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
-      // arbitrary cross-origin frame), AND we validate the message origin
-      // against a Builder-host allowlist (the configured fusionUrl origin or the
-      // *.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.
+      // A cross-origin fusion frame can never satisfy `origin === parentOrigin`,
+      // so trust there rests on window identity plus a Builder-host allowlist.
+      // A proxied one is same-origin and takes the strict path unchanged.
       const trustedCurrentFrame =
-        sourceType === "fusion"
+        sourceType === "fusion" && e.origin !== window.location.origin
           ? iframeWindow !== null &&
             e.source === iframeWindow &&
             isAllowedFusionOrigin(e.origin, fusionUrl)
@@ -2420,12 +2559,7 @@ export function DesignCanvas({
               origin: e.origin,
               iframeWindow,
               parentOrigin: window.location.origin,
-              allowedOrigins:
-                sourceType === "localhost" && bridgeUrl
-                  ? [originFromUrl(bridgeUrl)].filter(
-                      (origin): origin is string => Boolean(origin),
-                    )
-                  : [],
+              allowedOrigins: canvasBridgeAllowedOrigins,
             });
       const trustedLateLiveEditReady =
         sourceType === "localhost" &&
@@ -2436,9 +2570,7 @@ export function DesignCanvas({
           origin: e.origin,
           iframeWindow: lateReadyRecovery.source,
           parentOrigin: window.location.origin,
-          allowedOrigins: [originFromUrl(bridgeUrl)].filter(
-            (origin): origin is string => Boolean(origin),
-          ),
+          allowedOrigins: canvasBridgeAllowedOrigins,
         });
       const trusted = trustedCurrentFrame || trustedLateLiveEditReady;
       if (!trusted) {
@@ -4445,6 +4577,8 @@ export function DesignCanvas({
           })}
           data-design-preview-iframe
           onLoad={(event) => {
+            setPreviewFrameLoaded(true);
+            sendBridgeToContainer();
             // The bridge logs into the IFRAME console and cannot read
             // import.meta.env, so dev has to switch it on from out here.
             if (!import.meta.env?.DEV) return;
@@ -4478,6 +4612,14 @@ export function DesignCanvas({
           title={t("designEditor.designPreview")}
         />
       )}
+      {externalPreviewUrl && !previewFrameLoaded ? (
+        <div className="pointer-events-none absolute inset-0 z-40 flex items-center justify-center gap-2 bg-background px-2 text-muted-foreground">
+          <Spinner className="size-4 shrink-0" />
+          <span className="truncate !text-[11px] font-medium">
+            {t("multiScreenCanvas.preparingLiveEditor")}
+          </span>
+        </div>
+      ) : null}
       {runtimeVerificationUrl ? (
         <iframe
           key={`${runtimeVerificationUrl}::${runtimeVerificationRequest?.requestId ?? 0}`}
@@ -4573,6 +4715,7 @@ export function DesignCanvas({
       ) : null}
       {waitingForEditableExternalSnapshot ||
       waitingForLiveEditBridge ||
+      sameOriginBridgePending ||
       liveEditDocumentPending ? (
         <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 &&
@@ -4609,7 +4752,7 @@ export function DesignCanvas({
                 {"Retry" /* i18n-ignore local dev bridge retry button */}
               </Button>
             </div>
-          ) : waitingForLiveEditBridge ? (
+          ) : waitingForLiveEditBridge || sameOriginBridgePending ? (
             <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 */

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

@@ -45,6 +45,7 @@ import {
   type PenNode,
   type PenPath,
 } from "@shared/pen-path";
+import { isRunningAppSourceType } from "@shared/source-mode";
 import {
   IconCopy,
   IconDots,
@@ -7998,6 +7999,11 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
     ? canvasFrames.find((entry) => entry.screen.id === singleSelectedFrame.id)
         ?.screen
     : undefined;
+  const singleSelectedFrameIsRunningApp = singleSelectedFrameScreen
+    ? isRunningAppSourceType(
+        getResolvedMetadata(singleSelectedFrameScreen).source,
+      )
+    : false;
   // Overview element selection (a Layers-panel row or an in-canvas click
   // resolving to a specific node) also suppresses the frame box: the parent
   // still carries the screen in `selectedIds` (other UI — z-order, "topmost
@@ -8382,8 +8388,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             onStartRotate={(event) =>
               beginRotate(singleSelectedFrame.id, event)
             }
-            onStartDrag={(event) =>
-              beginFrameDrag(singleSelectedFrame.id, event)
+            onStartDrag={
+              // A running app's frame is dragged by its label. Blanketing its
+              // content with a drag surface would make the app unclickable the
+              // moment it is selected, which is most of the time.
+              singleSelectedFrameIsRunningApp
+                ? undefined
+                : (event) => beginFrameDrag(singleSelectedFrame.id, event)
             }
           />
         ) : null}
@@ -9720,9 +9731,13 @@ const Screen = memo(function Screen({
     !isSelected &&
     !groupSelected &&
     !suppressFrameChromeForChild;
+  // A running app's `content` is its URL, so it never "has child layers" — but
+  // its live DOM does, and that DOM is the only thing there is to select.
   const screenContentInteractive =
     Boolean(screenContent) &&
-    (isSelected || hasScreenChildLayers(screen.content)) &&
+    (isSelected ||
+      isRunningAppSourceType(metadata.source) ||
+      hasScreenChildLayers(screen.content)) &&
     !locked &&
     !penActive &&
     !creationToolActive &&

package/corpus/templates/design/app/components/layout/Layout.tsx

@@ -20,6 +20,7 @@ import { useLocation } from "react-router";
 
 import { useNavigationState } from "@/hooks/use-navigation-state";
 import { DESIGN_CHAT_STORAGE_KEY } from "@/lib/agent-chat";
+import { isBuilderHostEmbed } from "@/lib/builder-host-origin";
 import {
   designEditorRoute,
   isDesignEditorRoute,
@@ -59,7 +60,9 @@ export function Layout({ children }: LayoutProps) {
   const t = useT();
   const { session } = useSession();
   const hasSession = Boolean(session?.email);
-  const embedded = isEmbedAuthActive();
+  // The shell canvas is embedded without a session, so this cannot be the token
+  // check alone or it renders Design's own nav inside Builder.
+  const embedded = isBuilderHostEmbed() || isEmbedAuthActive();
   useNavigationState(hasSession);
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
   const openMobileSidebar = useCallback(() => setMobileSidebarOpen(true), []);

package/corpus/templates/design/app/hooks/use-navigation-state.ts

@@ -12,6 +12,7 @@ export interface NavigationState {
   designSystemId?: string;
   templateId?: string;
   editorView?: "single" | "overview";
+  mode?: "edit" | "annotate" | "interact";
   inspectorTab?: "design" | "comments" | "tweaks" | "code" | "extensions";
   inspector?: "design" | "comments" | "tweaks" | "code" | "extensions";
   leftPanel?:
@@ -152,6 +153,14 @@ function normalizeLeftPanel(
     : undefined;
 }
 
+function normalizeEditorMode(
+  value: unknown,
+): "edit" | "annotate" | "interact" | undefined {
+  return value === "edit" || value === "annotate" || value === "interact"
+    ? value
+    : undefined;
+}
+
 function normalizeDesignTool(value: unknown): string | undefined {
   return typeof value === "string" &&
     DESIGN_EDITOR_TOOLS.includes(value as (typeof DESIGN_EDITOR_TOOLS)[number])
@@ -166,7 +175,7 @@ export function editorPathFromCommand(cmd: NavigationState): string | null {
   const params = new URLSearchParams();
   const editorView = normalizeEditorView(cmd.editorView);
   if (editorView) params.set("view", editorView);
-  if (editorView === "single") params.set("mode", "interact");
+  if (editorView === "single") params.set("mode", cmd.mode ?? "interact");
   const inspectorTab = normalizeInspectorTab(cmd.inspectorTab ?? cmd.inspector);
   if (inspectorTab) params.set("inspector", inspectorTab);
   const leftPanel = normalizeLeftPanel(cmd.leftPanel ?? cmd.panel);
@@ -202,7 +211,7 @@ export function editorCommandFromNavigate(
     path,
   };
   if (editorView) command.editorView = editorView;
-  if (editorView === "single") command.mode = "interact";
+  if (editorView === "single") command.mode = cmd.mode ?? "interact";
   if (inspectorTab) command.inspectorTab = inspectorTab;
   if (leftPanel) command.leftPanel = leftPanel;
   if (cmd.fileId) command.fileId = cmd.fileId;
@@ -244,6 +253,8 @@ export function useNavigationState(enabled = true) {
         state.designId = params.id;
         const editorView = normalizeEditorView(searchParams.get("view"));
         if (editorView) state.editorView = editorView;
+        const mode = normalizeEditorMode(searchParams.get("mode"));
+        if (mode) state.mode = mode;
         const inspectorTab = normalizeInspectorTab(
           searchParams.get("inspector"),
         );

package/corpus/templates/design/app/i18n-data.ts

@@ -1177,6 +1177,7 @@ const enUS = {
   multiScreenCanvas: {
     addBreakpointToAllScreens:
       "Add {{label}} breakpoint ({{width}}px) to all screens",
+    preparingLiveEditor: "Preparing the live editor…",
     duplicate: "Duplicate",
     fork: "Fork",
     fullView: "Full view",
@@ -8054,6 +8055,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "正在準備即時編輯器…",
       addBreakpointToAllScreens:
         "為所有畫面新增 {{label}} 中斷點（{{width}}px）",
       duplicate: "複製",
@@ -8226,6 +8228,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "正在准备实时编辑器…",
       addBreakpointToAllScreens: "为所有画面添加 {{label}} 断点（{{width}}px）",
       duplicate: "复制",
       fork: "分支",
@@ -8398,6 +8401,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "Preparando el editor en vivo…",
       addBreakpointToAllScreens:
         "Añadir punto de ruptura {{label}} ({{width}}px) a todas las pantallas",
       duplicate: "Duplicar",
@@ -8592,6 +8596,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "Préparation de l'éditeur en direct…",
       addBreakpointToAllScreens:
         "Ajouter le point de rupture {{label}} ({{width}}px) à tous les écrans",
       duplicate: "Dupliquer",
@@ -8783,6 +8788,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "Live-Editor wird vorbereitet…",
       addBreakpointToAllScreens:
         "{{label}}-Breakpoint ({{width}}px) zu allen Screens hinzufügen",
       duplicate: "Duplizieren",
@@ -8979,6 +8985,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "ライブエディターを準備しています…",
       addBreakpointToAllScreens:
         "すべての画面に {{label}} ブレークポイント（{{width}}px）を追加",
       duplicate: "複製",
@@ -9170,6 +9177,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "실시간 편집기를 준비하는 중…",
       addBreakpointToAllScreens:
         "모든 화면에 {{label}} 중단점({{width}}px) 추가",
       duplicate: "복제",
@@ -9358,6 +9366,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "Preparando o editor ao vivo…",
       addBreakpointToAllScreens:
         "Adicionar ponto de quebra {{label}} ({{width}}px) a todas as telas",
       duplicate: "Duplicar",
@@ -9546,6 +9555,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "लाइव एडिटर तैयार किया जा रहा है…",
       addBreakpointToAllScreens:
         "सभी स्क्रीन में {{label}} ब्रेकपॉइंट ({{width}}px) जोड़ें",
       duplicate: "डुप्लिकेट",
@@ -9734,6 +9744,7 @@ const designModeFeatureOverrides = {
       },
     },
     multiScreenCanvas: {
+      preparingLiveEditor: "جارٍ تحضير المحرر المباشر…",
       addBreakpointToAllScreens:
         "إضافة نقطة توقف {{label}} ({{width}}px) إلى جميع الشاشات",
       duplicate: "تكرار",

package/corpus/templates/design/app/lib/agent-chat.ts

@@ -5,6 +5,13 @@ import {
   type AgentChatMessage,
   type SendToAgentChatAndConfirmResult,
 } from "@agent-native/core/client/agent-chat";
+import { sendToBuilderChat } from "@agent-native/core/client/host";
+
+import {
+  getVerifiedBuilderHostOrigin,
+  isBuilderHostEmbed,
+} from "./builder-host-origin";
+import { isEmbedChromeRequested } from "./embed-chrome";
 
 export const DESIGN_CHAT_STORAGE_KEY = "design";
 
@@ -39,6 +46,12 @@ export function sendToDesignAgentChatAndConfirm(
 export interface DesignSourceHandoffResult {
   target: "host" | "local";
   delivered: boolean;
+  /**
+   * The host prefilled its composer and the user has not sent it yet. Callers
+   * must not treat this as applied: discarding pending edits here loses work
+   * the agent was never asked to do.
+   */
+  staged?: boolean;
   reason?: string;
   tabId?: string;
 }
@@ -58,6 +71,23 @@ export async function sendDesignSourceHandoffAndConfirm(
   opts: AgentChatMessage,
   options?: { timeoutMs?: number },
 ): Promise<DesignSourceHandoffResult> {
+  // `embedChrome` alone is a display preference any embedder can ask for, so the
+  // shell route is what decides who receives source-edit context. `submit` is
+  // the host's call there, and its composer filling is the delivery evidence.
+  if (isEmbedChromeRequested() && isBuilderHostEmbed()) {
+    const posted = sendToBuilderChat({
+      message: opts.message,
+      context: opts.context,
+      submit: false,
+      targetOrigin: getVerifiedBuilderHostOrigin() ?? undefined,
+    });
+    return {
+      target: "host",
+      delivered: posted,
+      ...(posted ? { staged: true } : { reason: "host-post-failed" }),
+    };
+  }
+
   const hostDelivery = sendMcpAppHostMessage({
     message: opts.message,
     context: opts.context,

package/corpus/templates/design/app/lib/builder-host-chat.ts

@@ -0,0 +1,34 @@
+/**
+ * Hand selection and pending visual edits to the embedding host's chat instead
+ * of the editor's own agent.
+ *
+ * `submit: false` throughout: the host prefills its composer so the user can
+ * say what they actually want before the turn is spent.
+ */
+
+import { sendToBuilderChat } from "@agent-native/core/client/host";
+
+/** The host's chip syntax is attribute-quoted, so a stray `"` truncates it. */
+function chipAttribute(value: string, max: number): string {
+  return value.replace(/\s+/g, " ").replace(/"/g, "'").trim().slice(0, max);
+}
+
+export function builderSelectionChip(args: {
+  label: string;
+  detail: string;
+}): string {
+  return `<chip text="${chipAttribute(args.label, 80)}" detail="${chipAttribute(
+    args.detail,
+    240,
+  )}" />`;
+}
+
+export function sendBuilderSelectionContext(args: {
+  label: string;
+  detail: string;
+}): boolean {
+  return sendToBuilderChat({
+    message: `${builderSelectionChip(args)} `,
+    submit: false,
+  });
+}

package/corpus/templates/design/app/lib/builder-host-origin.ts

@@ -0,0 +1,31 @@
+import { SHELL_CANVAS_PATH } from "@shared/shell-screens";
+
+/**
+ * The parent origin the Builder handshake arrived from, recorded once a
+ * `design:init` message passes the host check.
+ *
+ * Origin sniffing cannot confirm a Builder running on localhost — every local
+ * dev session — so the handshake is the only signal that works in both.
+ */
+let verifiedBuilderHostOrigin: string | null = null;
+
+export function rememberBuilderHostOrigin(origin: string): void {
+  if (origin) verifiedBuilderHostOrigin = origin;
+}
+
+export function getVerifiedBuilderHostOrigin(): string | null {
+  return verifiedBuilderHostOrigin;
+}
+
+/**
+ * True on the host-driven canvas. The route is the whole signal now: there is no
+ * token to inspect, and this picks chrome, never access.
+ */
+export function isBuilderHostEmbed(): boolean {
+  if (typeof window === "undefined") return false;
+  return window.location.pathname === SHELL_CANVAS_PATH;
+}
+
+export function _resetBuilderHostEmbedForTests(): void {
+  verifiedBuilderHostOrigin = null;
+}