@agent-native/core 0.161.7 → 0.161.9

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;
+}

package/corpus/templates/design/app/lib/embed-chrome.ts

@@ -0,0 +1,70 @@
+/**
+ * Embedded hosts normally supply their own chrome, so the editor hides its
+ * rails. A host that frames only the canvas asks for them back with
+ * `?embedChrome=1`.
+ */
+
+const EMBED_CHROME_QUERY_PARAM = "embedChrome";
+
+const STORAGE_KEY_PREFIX = "agent-native:embed-chrome:";
+
+/**
+ * Scoped to the design being framed: a single origin-wide key would let one
+ * canvas-only embed leave the flag set for the next, host-owned embed in the
+ * same tab, which would then render rails its URL never asked for.
+ */
+function storageKey(win: Window): string {
+  const match = /\/(?:visual-edit|design)\/([^/?#]+)/.exec(
+    win.location.pathname,
+  );
+  return `${STORAGE_KEY_PREFIX}${match?.[1] ?? "unscoped"}`;
+}
+
+// Keyed, not a bare boolean: an SPA navigation to a different design keeps this
+// module alive, and a plain cached `true` would follow the user there.
+let cachedKey: string | null = null;
+let requested = false;
+
+function readFromUrl(win: Window): boolean {
+  try {
+    const value = new URL(win.location.href).searchParams.get(
+      EMBED_CHROME_QUERY_PARAM,
+    );
+    return value === "1" || value === "true";
+    // coercion-ok: an unparsable URL cannot be carrying the flag.
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sticky once seen: the editor rewrites its own URL on the first navigation,
+ * which would otherwise drop the flag and strip the rails mid-session.
+ */
+export function isEmbedChromeRequested(): boolean {
+  if (typeof window === "undefined") return false;
+  const key = storageKey(window);
+  if (cachedKey === key) return requested;
+  cachedKey = key;
+  if (readFromUrl(window)) {
+    requested = true;
+    try {
+      window.sessionStorage?.setItem(key, "1");
+    } catch {
+      // coercion-ok: sandboxed hosts refuse session storage; the module-level
+      // value still covers the single-page boot path.
+    }
+    return true;
+  }
+  try {
+    requested = window.sessionStorage?.getItem(key) === "1";
+  } catch {
+    requested = false;
+  }
+  return requested;
+}
+
+export function _resetEmbedChromeForTests(): void {
+  cachedKey = null;
+  requested = false;
+}

package/corpus/templates/design/app/lib/shell-design.ts

@@ -0,0 +1,113 @@
+/**
+ * Turns a host `design:init` payload into the `DesignData` the editor normally
+ * fetches from `get-design`, so the canvas can run with no design row, no
+ * session and no server writes. The host owns this state; it dies with the tab.
+ */
+
+import {
+  buildShellScreens,
+  type ShellScreensResult,
+} from "@shared/shell-screens";
+
+import type { DesignData, DesignFile } from "@/pages/design-editor/types";
+
+export const SHELL_DESIGN_ID = "shell";
+const SHELL_EPOCH = "1970-01-01T00:00:00.000Z";
+
+export interface ShellDesignInput {
+  previewOrigin: string;
+  routes: Array<{ path: string; title?: string }>;
+  projectId?: string;
+  branchName?: string;
+  builderOrgId?: string;
+  contentId?: string;
+}
+
+export interface ShellDesign {
+  design: DesignData;
+  screens: ShellScreensResult["screens"];
+}
+
+/**
+ * `editor` because the canvas gates click-to-edit on it. Nothing it unlocks can
+ * reach a server: the shell never mounts a save path, so this only opens the
+ * in-memory affordances.
+ */
+const SHELL_ACCESS_ROLE = "editor" as const;
+
+/**
+ * Whether pending edits still describe the app the host is now pointing at. A
+ * new route list is not a change of app; a new origin, branch or project is.
+ */
+export function shellContextChanged(
+  previous: ShellDesignInput,
+  next: ShellDesignInput,
+): boolean {
+  return (
+    previous.previewOrigin !== next.previewOrigin ||
+    previous.branchName !== next.branchName ||
+    previous.projectId !== next.projectId
+  );
+}
+
+export function buildShellDesign(input: ShellDesignInput): ShellDesign {
+  const { screens, placedFrames } = buildShellScreens({
+    previewOrigin: input.previewOrigin,
+    paths: input.routes.map((route) => route.path),
+  });
+
+  // Frame geometry is keyed by fileId, the same shape the persisted canvas uses.
+  const canvasFrames: Record<
+    string,
+    { x: number; y: number; width: number; height: number }
+  > = {};
+  for (const placed of placedFrames) {
+    const { x = 0, y = 0, width, height } = placed.frame;
+    canvasFrames[placed.fileId] = {
+      x,
+      y,
+      width: width ?? 0,
+      height: height ?? 0,
+    };
+  }
+
+  // Fixed, not `Date.now()`: a repeated `design:init` must rebuild an identical
+  // design, or the canvas treats it as a new document and remounts the frames.
+  const now = SHELL_EPOCH;
+  const files: DesignFile[] = screens.map((screen) => ({
+    id: screen.fileId,
+    filename: screen.filename,
+    fileType: "html",
+    content: screen.url,
+    createdAt: now,
+    updatedAt: now,
+  }));
+
+  const design: DesignData = {
+    id: SHELL_DESIGN_ID,
+    title: input.branchName ?? "Design",
+    updatedAt: now,
+    projectType: "prototype",
+    accessRole: SHELL_ACCESS_ROLE,
+    files,
+    data: JSON.stringify({
+      // Without this the editor resolves the design as `inline`, which turns off
+      // the runtime layer projection and leaves the layer tree permanently empty.
+      sourceType: "fusion",
+      canvasFrames,
+      fusionApp: {
+        source: "builder-host",
+        projectId: input.projectId ?? "",
+        branchName: input.branchName ?? "",
+        ...(input.builderOrgId ? { builderOrgId: input.builderOrgId } : {}),
+        ...(input.contentId ? { contentId: input.contentId } : {}),
+        previewUrl: input.previewOrigin,
+        status: "ready",
+        createdAt: now,
+        updatedAt: now,
+      },
+    }),
+  };
+
+  return { design, screens };
+}

package/corpus/templates/design/app/pages/design-editor/code-layer-state.ts

@@ -1293,3 +1293,92 @@ export function parseInlineStyleAttribute(
   }
   return result;
 }
+
+/**
+ * Resolve the selected element against the projection the Layers panel is
+ * actually rendering.
+ *
+ * A running-app screen (fusion / localhost) has TWO projections: the source one
+ * built from `design_files.content` — which for these screens is the route URL,
+ * not markup — and the runtime one built from the live DOM snapshot. The panel
+ * renders the runtime tree (see `shouldUseRuntimeLayerProjection`), and the two
+ * trees mint different node ids, so resolving selection against source returns
+ * an id no rendered row carries: the selected layer never highlights and has to
+ * be found by hand.
+ *
+ * Runtime first, then source, so an inline screen — and a live screen before
+ * its first snapshot arrives — resolves exactly as it did before.
+ */
+export function resolveSelectedCodeLayerNode(args: {
+  selectedElement: ElementInfo | null | undefined;
+  sourceProjection: CodeLayerProjection;
+  runtimeProjection?: CodeLayerProjection | null;
+}): CodeLayerNode | null {
+  if (!args.selectedElement) return null;
+  if (args.runtimeProjection) {
+    const runtimeNode = resolveCodeLayerNodeFromElementInfo(
+      args.runtimeProjection,
+      args.selectedElement,
+    );
+    if (runtimeNode) return runtimeNode;
+  }
+  return resolveCodeLayerNodeFromElementInfo(
+    args.sourceProjection,
+    args.selectedElement,
+  );
+}
+
+/**
+ * The document a keyboard nudge should resolve its intent against.
+ *
+ * Returns "" when a running-app screen has no live snapshot yet, which makes
+ * `resolveElementNudgeIntent` fall back to a plain translate rather than
+ * projecting a route URL as if it were markup.
+ */
+export function nudgeBaseContentForScreen(args: {
+  isRunningApp: boolean;
+  runtimeSnapshotHtml?: string | null;
+  liveSnapshotHtml?: string | null;
+  sourceContent: string;
+}): string {
+  if (!args.isRunningApp) return args.sourceContent;
+  return args.runtimeSnapshotHtml ?? args.liveSnapshotHtml ?? "";
+}
+
+export interface LiveNudgeReorderHandoff {
+  /** Selector the pending-edit pipeline anchors the move against. */
+  anchorSelector: string;
+  placement: "before" | "after";
+  /** Bridge-assigned id for the anchor, when it carries one. */
+  anchorSourceId?: string;
+}
+
+/**
+ * Translate a nudge reorder intent into the arguments a LIVE structure edit
+ * needs, or null when it cannot be expressed as one.
+ *
+ * `resolveElementNudgeIntent` reports the anchor as a PROJECTION node id, but
+ * `recordPendingLiveStructureEdit` addresses the running document by SELECTOR
+ * — the projection ids never reached the live DOM. Returning null (rather than
+ * guessing) makes the caller drop the keypress instead of queueing an edit
+ * that would anchor against nothing.
+ */
+export function liveNudgeReorderHandoff(args: {
+  content: string;
+  anchorNodeId: string;
+  placement: "before" | "after";
+}): LiveNudgeReorderHandoff | null {
+  const projection = buildCodeLayerProjection(args.content);
+  const anchorNode = projection.nodes.find(
+    (node) => node.id === args.anchorNodeId,
+  );
+  const anchorSelector = codeLayerSelectorAliases(anchorNode)[0];
+  if (!anchorSelector) return null;
+  const anchorSourceId =
+    anchorNode?.dataAttributes["data-agent-native-node-id"]?.trim();
+  return {
+    anchorSelector,
+    placement: args.placement,
+    ...(anchorSourceId ? { anchorSourceId } : {}),
+  };
+}

package/corpus/templates/design/app/pages/design-editor/nudge-intent.ts

@@ -23,7 +23,7 @@ export const DEFAULT_NUDGE_AMOUNTS: NudgeAmounts = { small: 1, big: 10 };
 export type FlowAxis = "horizontal" | "vertical";
 
 export interface FlowContainerInfo {
-  kind: "flex" | "grid" | "none";
+  kind: "flex" | "grid" | "block" | "none";
   /** The axis DOM order advances along. */
   axis: FlowAxis;
   /** Visual order runs opposite to DOM order (`*-reverse`). */
@@ -33,6 +33,23 @@ export interface FlowContainerInfo {
   lineLength: number | null;
 }
 
+/**
+ * Normal block flow: children stack vertically in DOM order, so an arrow along
+ * the block axis reorders exactly like a flex column.
+ *
+ * Not inferable from the parent's own markup — a `<div>` with no styles is
+ * block, but so is one the stylesheet turned into a flex container. Only the
+ * browser knows, so this is built from the bridge's rendered `parentDisplay`
+ * rather than from parsed styles.
+ */
+export const BLOCK_FLOW_CONTAINER: FlowContainerInfo = {
+  kind: "block",
+  axis: "vertical",
+  reversed: false,
+  wraps: false,
+  lineLength: null,
+};
+
 export const NO_FLOW_CONTAINER: FlowContainerInfo = {
   kind: "none",
   axis: "horizontal",
@@ -385,6 +402,15 @@ function isRenderedFlowDisplay(display: string | null | undefined): boolean {
   );
 }
 
+/**
+ * Rendered `display` values whose children stack in normal block flow, so DOM
+ * order is visual order. `list-item` covers `<li>`; table and flow-root boxes
+ * lay their children out on their own rules and are deliberately excluded.
+ */
+function isRenderedBlockDisplay(display: string | null | undefined): boolean {
+  return display === "block" || display === "list-item";
+}
+
 export interface ResolveElementNudgeIntentArgs {
   content: string;
   selectedElement: ElementInfo;
@@ -427,7 +453,60 @@ export function resolveElementNudgeIntent(
     (escapesFlow(undefined, node.classes) ? "absolute" : undefined) ??
     args.selectedElement.computedStyles?.position;
 
-  const container = describeFlowContainer(parent);
+  const parsedContainer = describeFlowContainer(parent);
+  // The parser sees only the parent's inline styles and Tailwind utilities, so
+  // a stylesheet-driven layout reads as `none` and every arrow key used to fall
+  // through to a blind translate. Prefer what the browser actually rendered.
+  //
+  // When nothing knows the display, treat it as block: that is the CSS initial
+  // value for the container elements a layer tree contains, and it is also the
+  // case that reaches here from a layers-tree selection, where no bridge
+  // round-trip has happened yet and `parentDisplay` is simply absent. An
+  // element that really is inline or a flex child is handled above — the parser
+  // sees those, and a rendered value always wins over this default.
+  const rendered = args.selectedElement.parentDisplay;
+  // A rendered grid needs its column count to map an arrow onto the next visual
+  // cell, and `display: grid` alone does not carry it. Guessing "flex row" walks
+  // DOM order instead, which is a different element in any multi-column grid.
+  if (
+    parsedContainer.kind === "none" &&
+    !escapesFlow(position) &&
+    (rendered === "grid" || rendered === "inline-grid")
+  ) {
+    return { kind: "none" };
+  }
+  // The rendered axis, which markup alone cannot give: a stylesheet-driven
+  // `flex-direction: column` maps up/down onto DOM order, and assuming a row
+  // reorders on left/right instead.
+  const renderedFlexDirection =
+    args.selectedElement.parentLayout?.flexDirection;
+  if (
+    parsedContainer.kind === "none" &&
+    !escapesFlow(position) &&
+    isRenderedFlowDisplay(rendered) &&
+    !renderedFlexDirection
+  ) {
+    return { kind: "none" };
+  }
+  const container: FlowContainerInfo =
+    parsedContainer.kind === "none" && !escapesFlow(position)
+      ? isRenderedFlowDisplay(rendered)
+        ? {
+            ...NO_FLOW_CONTAINER,
+            kind: "flex",
+            axis: renderedFlexDirection?.startsWith("column")
+              ? "vertical"
+              : "horizontal",
+            reversed: renderedFlexDirection?.endsWith("-reverse") ?? false,
+          }
+        : // `parent` null means the node is a projection root: it has no flow to
+          // reorder within, and the bridge reports `parentDisplay: undefined`
+          // for it exactly as it does for a not-yet-measured selection.
+          isRenderedBlockDisplay(rendered) ||
+            (rendered === undefined && parent !== null)
+          ? BLOCK_FLOW_CONTAINER
+          : parsedContainer
+      : parsedContainer;
   // Flex/grid paint children by `order` and explicit grid placement, not DOM
   // position, so moving the node would write a source change that produces no
   // visible movement.
@@ -444,16 +523,10 @@ export function resolveElementNudgeIntent(
     return { kind: "none" };
   }
 
-  // A `.row { display: flex }` parent parses as no container. Translating
-  // would write left/top onto a flex child and detach it from its
-  // neighbours, so do nothing rather than corrupt the layout.
-  if (
-    container.kind === "none" &&
-    !escapesFlow(position) &&
-    isRenderedFlowDisplay(args.selectedElement.parentDisplay)
-  ) {
-    return { kind: "none" };
-  }
+  // A `.row { display: flex }` parent used to reach here as `none` and get
+  // suppressed. It is now promoted to a flex container above, so a reorder is
+  // attempted instead of the key being swallowed — same protection against
+  // writing left/top onto a flex child, but it does the useful thing.
 
   // Rendered `order` from the bridge sees stylesheet rules that the authored
   // styles above cannot.

package/corpus/templates/design/app/pages/design-editor/pending-edits.ts

@@ -16,6 +16,7 @@ import {
 } from "@shared/responsive-classes";
 import {
   type ElementProvenanceUnavailableReason,
+  isRunningAppSourceType,
   normalizeDesignSourceType,
   type DesignSourceType,
 } from "@shared/source-mode";
@@ -824,11 +825,22 @@ export function formatPendingVisualStylePrompt(args: {
   localhostConnectionId?: string | null;
   edits: readonly PendingVisualStyleEdit[];
   liveEdits?: readonly PendingLiveNonStyleEdit[];
+  /**
+   * A coding agent has the repo and none of the Design source tools, and a
+   * screen's `.html` filename is the editor's own bookkeeping — naming it sends
+   * that agent hunting for a file the project does not contain.
+   */
+  audience?: "design-agent" | "coding-agent";
+  /** Screen id → the route it renders, for naming screens the way the app does. */
+  screenRoutes?: Readonly<Record<string, string>>;
 }): string {
+  const codingAgent = args.audience === "coding-agent";
+  const nameScreen = (screenId: string, filename: string) =>
+    (codingAgent ? args.screenRoutes?.[screenId] : undefined) ?? filename;
   const title = args.designTitle?.trim();
   const editPayload = args.edits.map((edit) => ({
     screenId: edit.screenId,
-    filename: edit.filename,
+    screen: nameScreen(edit.screenId, edit.filename),
     screenName: edit.screenName,
     selector: edit.selector,
     sourceId: edit.sourceId ?? null,
@@ -864,7 +876,7 @@ export function formatPendingVisualStylePrompt(args: {
       return {
         kind: edit.kind,
         screenId: edit.screenId,
-        filename: edit.filename,
+        screen: nameScreen(edit.screenId, edit.filename),
         screenName: edit.screenName,
         selector: edit.selector,
         sourceId: edit.sourceId ?? null,
@@ -887,7 +899,7 @@ export function formatPendingVisualStylePrompt(args: {
       return {
         kind: edit.kind,
         screenId: edit.screenId,
-        filename: edit.filename,
+        screen: nameScreen(edit.screenId, edit.filename),
         screenName: edit.screenName,
         selector: edit.selector,
         sourceId: edit.sourceId ?? null,
@@ -1031,7 +1043,7 @@ export function formatPendingVisualStylePrompt(args: {
     return {
       kind: edit.kind,
       screenId: edit.screenId,
-      filename: edit.filename,
+      screen: nameScreen(edit.screenId, edit.filename),
       screenName: edit.screenName,
       selector: edit.selector,
       sourceId: edit.sourceId ?? null,
@@ -1075,18 +1087,27 @@ export function formatPendingVisualStylePrompt(args: {
     };
   });
 
+  const activeScreenLabel = args.activeFileId
+    ? nameScreen(args.activeFileId, args.activeFilename ?? "")
+    : "";
   return [
-    `Apply these pending live visual edits${title ? ` to "${title}"` : ""}.`,
-    args.designId ? `Design id: "${args.designId}".` : "",
+    codingAgent
+      ? `Apply these visual edits${title ? ` to "${title}"` : ""} by editing the app's source.`
+      : `Apply these pending live visual edits${title ? ` to "${title}"` : ""}.`,
+    codingAgent ? "" : args.designId ? `Design id: "${args.designId}".` : "",
     args.activeFileId
-      ? `Active screen: "${args.activeFilename ?? args.activeFileId}" (${args.activeFileId}).`
+      ? codingAgent
+        ? `Screen: ${activeScreenLabel || "the current route"}.`
+        : `Active screen: "${args.activeFilename ?? args.activeFileId}" (${args.activeFileId}).`
       : "",
-    args.localhostConnectionId
+    args.localhostConnectionId && !codingAgent
       ? `Active localhost connection id: "${args.localhostConnectionId}".`
       : "",
     "",
-    "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, layer-state, and structure changes with focused source edits. Preserve layout, behavior, and unrelated styling.",
-    hasReactSourceAnchors
+    codingAgent
+      ? "These were made against the running app in a visual canvas, so the selectors and node ids below are runtime-only — they do not appear in source. Locate the component that renders each element using its tag, class names and current text, then make the change in that source file. Preserve layout, behavior, and unrelated styling."
+      : "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, layer-state, and structure changes with focused source edits. Preserve layout, behavior, and unrelated styling.",
+    hasReactSourceAnchors && !codingAgent
       ? "React sourceAnchor fields are source provenance; runtime source ids and selectors are correlation hints only. For a single-instance leaf text, literal className/class, or flat literal style-object edit, call apply-visual-edit with source.kind=local-file plus designId, connectionId, the verified project-relative path, and target.sourceAnchor. First omit persist and inspect proposedDiff; then retry with persist=true only when the diff matches the preview. That write still requires human localhost consent and exact version-hash concurrency. Verify every file, line, column, component, and surrounding control flow before editing. Never use a generic AST reparent, group, wrapper, breakpoint, dynamic expression, repeated render, or shared component transform through this path. 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
@@ -1147,11 +1168,15 @@ export function shouldUseRuntimeLayerProjection(args: {
   fallbackSourceType?: DesignSourceType;
   content: string;
 }): boolean {
+  // A running app's live DOM is the ground truth; only inline screens carry
+  // their own source.
   if (
-    resolveOverviewScreenSourceType(
-      args.screen,
-      args.fallbackSourceType ?? "inline",
-    ) !== "localhost"
+    !isRunningAppSourceType(
+      resolveOverviewScreenSourceType(
+        args.screen,
+        args.fallbackSourceType ?? "inline",
+      ),
+    )
   ) {
     return false;
   }
@@ -1185,11 +1210,10 @@ export function shouldShowPendingVisualStyleApply(args: {
   const allEdits = [...args.edits, ...(args.liveEdits ?? [])];
   return (
     allEdits.length > 0 &&
-    allEdits.every(
-      (edit) =>
-        normalizeDesignSourceType(
-          args.screenSourceTypes.get(edit.screenId) ?? args.fallbackSourceType,
-        ) === "localhost",
+    allEdits.every((edit) =>
+      isRunningAppSourceType(
+        args.screenSourceTypes.get(edit.screenId) ?? args.fallbackSourceType,
+      ),
     )
   );
 }

package/corpus/templates/design/app/pages/design-editor/screen-command-utils.ts

@@ -1,7 +1,11 @@
 import type { DesignEditorCommand } from "@/hooks/use-navigation-state";
 
 import { queryUniqueSelector } from "./dom-utils";
-import { normalizeDesignLeftPanel, normalizeDesignTool } from "./tool-state";
+import {
+  normalizeDesignLeftPanel,
+  normalizeDesignMode,
+  normalizeDesignTool,
+} from "./tool-state";
 import { type DesignFile, FOCUSED_SCREEN_ZOOM } from "./types";
 
 export function normalizeScreenTarget(value: string): string {
@@ -45,7 +49,10 @@ export function designEditorCommandFromSearchParams(
   // `single` is the URL spelling for the responsive Interact surface. There
   // is no focused editing view, so even an older URL without mode=interact
   // must enter Interact directly instead of reviving the removed Full view.
-  const mode = editorView === "single" ? "interact" : undefined;
+  const mode =
+    editorView === "single"
+      ? (normalizeDesignMode(searchParams.get("mode")) ?? "interact")
+      : undefined;
   if (
     editorView !== "overview" &&
     editorView !== "single" &&

package/corpus/templates/design/app/pages/design-editor/tool-state.ts

@@ -74,6 +74,19 @@ export function normalizeDesignTool(value: unknown): DesignTool | null {
     : null;
 }
 
+const DESIGN_EDITOR_MODES = new Set<EditorMode>([
+  "annotate",
+  "edit",
+  "interact",
+]);
+
+export function normalizeDesignMode(value: unknown): EditorMode | null {
+  return typeof value === "string" &&
+    DESIGN_EDITOR_MODES.has(value as EditorMode)
+    ? (value as EditorMode)
+    : null;
+}
+
 export function isSingleScreenAnnotationTool(tool: DesignTool): boolean {
   return tool === "draw" || tool === "comment";
 }

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

@@ -7,6 +7,7 @@ import {
   getBrowserTabId,
   useSession,
 } from "@agent-native/core/client/hooks";
+import { setAgentNativeApiDisabled } from "@agent-native/core/client/host";
 import { getLocaleInitScript, useT } from "@agent-native/core/client/i18n";
 import {
   CommandMenu,
@@ -36,6 +37,7 @@ import type { LinksFunction } from "react-router";
 import { Layout as AppLayout } from "@/components/layout/Layout";
 import { Toaster } from "@/components/ui/sonner";
 import { AppToolkitProvider } from "@/components/ui/toolkit-provider";
+import { isBuilderHostEmbed } from "@/lib/builder-host-origin";
 import { requestDesignUiToggle } from "@/lib/design-ui-events";
 
 import changelog from "../CHANGELOG.md?raw";
@@ -44,6 +46,11 @@ import { isPublicDesignAppPath } from "./public-routes";
 
 import stylesheet from "./global.css?url";
 
+// Builder frames this canvas with no session of its own, so every
+// `/_agent-native/*` call it makes is an unauthorized one that buries real
+// failures in 401 noise.
+if (isBuilderHostEmbed()) setAgentNativeApiDisabled("builder shell canvas");
+
 configureTracking({
   llmConnectionStatus:
     typeof window === "undefined" ||
@@ -168,6 +175,21 @@ function DesignCommandMenu({
   );
 }
 
+/**
+ * The one toaster: AppProviders renders its own by default, and a second copy
+ * here made every toast appear twice once the two positions stopped coinciding.
+ * Builder's chat covers the left column when it hosts the editor, which would
+ * hide any toast underneath it.
+ */
+function DesignToaster() {
+  return (
+    <Toaster
+      richColors
+      position={isBuilderHostEmbed() ? "bottom-right" : "bottom-left"}
+    />
+  );
+}
+
 function RootContent() {
   const location = useLocation();
   const { session } = useSession();
@@ -191,7 +213,6 @@ function RootContent() {
   return (
     <>
       {hasSession && <DbSyncSetup />}
-      <Toaster richColors position="bottom-left" />
       {hasSession && !isPublicVisualEdit && (
         <DesignCommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen} />
       )}
@@ -210,6 +231,7 @@ export default function Root() {
         queryClient={queryClient}
         isPublicPath={isPublicPath}
         i18n={{ catalog: i18nCatalog, persistPreference: !isPublicPath }}
+        toaster={<DesignToaster />}
       >
         <RootContent />
       </AppProviders>