@agent-native/core 0.85.6 → 0.85.7

package/corpus/templates/design/app/components/design/inspector/ImageFillControls.tsx

@@ -264,11 +264,18 @@ export function ImageFillControls({
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [urlDraft, setUrlDraft] = useState(value.url);
   const urlDraftRef = useRef(value.url);
+  // Guard re-syncing the draft from an external value change while the field
+  // is focused (mirrors ScrubInput's `focused` pattern): without this, an
+  // incoming prop update while the user is mid-typing a URL — e.g. a
+  // selection-driven re-render, or another control committing a sibling
+  // style in the same patch — clobbers their in-progress keystrokes.
+  const [focused, setFocused] = useState(false);
 
   useEffect(() => {
+    if (focused) return;
     urlDraftRef.current = value.url;
     setUrlDraft(value.url);
-  }, [value.url]);
+  }, [focused, value.url]);
 
   const commitUrl = () => {
     onChange({ ...value, url: urlDraftRef.current.trim() });
@@ -352,7 +359,11 @@ export function ImageFillControls({
             urlDraftRef.current = event.target.value;
             setUrlDraft(event.target.value);
           }}
-          onBlur={commitUrl}
+          onFocus={() => setFocused(true)}
+          onBlur={() => {
+            setFocused(false);
+            commitUrl();
+          }}
           onKeyDown={(event) => {
             if (event.key === "Enter") {
               event.preventDefault();

package/corpus/templates/design/app/components/design/inspector/ScrubInput.tsx

@@ -28,6 +28,10 @@ import {
 
 type ScrubInputIcon = (props: { className?: string }) => ReactNode;
 
+/** Cumulative pointer movement (px) required before a label pointerdown→move
+ * is treated as a scrub drag rather than jitter during a plain click. */
+const DRAG_THRESHOLD_PX = 3;
+
 export interface ScrubInputChangeMeta {
   source: "commit" | "keyboard" | "scrub";
   expression?: string;
@@ -127,7 +131,10 @@ export function ScrubInput({
 
     draftRef.current = parsed.normalized;
     setDraft(parsed.normalized);
-    if (parsed.value !== value) {
+    // From a mixed selection every explicitly typed value must commit, even
+    // when it equals the placeholder `value` prop (e.g. typing "0"): the
+    // selected objects hold differing values, so "no change" is meaningless.
+    if (parsed.value !== value || mixed) {
       onChange(parsed.value, { source: "commit", expression: currentDraft });
     }
   };
@@ -135,12 +142,28 @@ export function ScrubInput({
   const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
     if (event.key === "ArrowUp" || event.key === "ArrowDown") {
       event.preventDefault();
+      // Mixed selection: the `value` prop is only a placeholder (typically 0),
+      // so stepping from it would snap every selected object to a value the
+      // user never chose. Require an explicit typed value first — typing then
+      // committing applies to all, which is the design-editor convention.
+      if (mixed) return;
       const direction = event.key === "ArrowUp" ? 1 : -1;
       // getScrubStepFromEvent handles shiftKey (×10) and altKey (÷10).
       // Cmd (metaKey) mirrors Shift for ×10 — editor convention on macOS.
       const baseStep = getScrubStepFromEvent(event, step);
       const cmdMultiplier = event.metaKey && !event.shiftKey ? 10 : 1;
-      setNextValue(value + direction * baseStep * cmdMultiplier, {
+      // Step from the currently typed draft, not the last-committed `value`
+      // prop — otherwise an in-progress, uncommitted edit (typed but not yet
+      // blurred/entered) is silently discarded the moment an arrow key is
+      // pressed. Parse the draft the same way commitDraft does, falling back
+      // to `value` only when the draft doesn't parse (e.g. empty/invalid).
+      const draftParsed = parseScrubExpression(
+        draftRef.current,
+        value,
+        options,
+      );
+      const base = draftParsed ? draftParsed.value : value;
+      setNextValue(base + direction * baseStep * cmdMultiplier, {
         source: "keyboard",
       });
       return;
@@ -179,8 +202,25 @@ export function ScrubInput({
 
   const handlePointerMove = (event: PointerEvent<HTMLLabelElement>) => {
     if (!dragging || dragRef.current.pointerId !== event.pointerId) return;
+    // Mixed selection: scrubbing has no meaningful base value (the `value`
+    // prop is a placeholder), so committing drag deltas would snap every
+    // selected object to a step-from-0 value. Keep the drag inert; releasing
+    // without a committed drag focuses the input so the user can type an
+    // explicit value that then applies to all.
+    if (mixed) return;
     const incr = event.clientX - dragRef.current.prevX;
     if (incr === 0) return;
+    // Require a small cumulative movement before treating this as a real
+    // drag. Without a threshold, ordinary mouse jitter between pointerdown
+    // and pointerup (a couple of px is common on real hardware even for a
+    // plain click) sets hasDragged=true on the very first move event, which
+    // makes endDrag skip its "focus the input for typing" path even though
+    // the user only meant to click.
+    const cumulativeDelta = Math.abs(event.clientX - dragRef.current.startX);
+    if (!dragRef.current.hasDragged && cumulativeDelta < DRAG_THRESHOLD_PX) {
+      dragRef.current.prevX = event.clientX;
+      return;
+    }
     dragRef.current.prevX = event.clientX;
     dragRef.current.hasDragged = true;
     // Use incremental deltas from the last move so that clamped/rounded values

package/corpus/templates/design/app/components/design/inspector/scrub-input-utils.ts

@@ -17,6 +17,11 @@ type Token =
   | { type: "operator"; value: MathOperator };
 
 const NUMBER_CHAR_PATTERN = /[0-9.]/;
+// Comma is only treated as a digit character while scanning a number token
+// (see tokenizeExpression) so a locale-style decimal comma ("12,5") parses as
+// 12.5, without swallowing the "," that a caller might use to separate
+// distinct expressions elsewhere.
+const NUMBER_OR_COMMA_CHAR_PATTERN = /[0-9.,]/;
 
 export function parseScrubExpression(
   input: string,
@@ -157,8 +162,12 @@ function tokenizeExpression(expression: string): Token[] {
     if (NUMBER_CHAR_PATTERN.test(char) || signedNumber) {
       const start = index;
       index += 1;
-      while (NUMBER_CHAR_PATTERN.test(expression[index] ?? "")) index += 1;
-      const value = Number(expression.slice(start, index));
+      // Allow a single comma decimal separator within this number token
+      // ("12,5" → 12.5), matching common European locale input. A second
+      // comma/period is left for the caller's Number() parse to reject.
+      while (NUMBER_OR_COMMA_CHAR_PATTERN.test(expression[index] ?? ""))
+        index += 1;
+      const value = Number(expression.slice(start, index).replace(",", "."));
       if (!Number.isFinite(value)) return [];
       tokens.push({ type: "number", value });
       previousWasOperator = false;

package/corpus/templates/design/app/components/design/types.ts

@@ -18,6 +18,22 @@ export interface ElementInfo {
   selector?: string;
   classes: string[];
   computedStyles: Record<string, string>;
+  /**
+   * Raw authored `el.style` values (not computed) for a bounded set of
+   * layout-relevant properties: position, left, right, top, bottom, width,
+   * height, transform, whiteSpace. Populated on SELECTION payloads only
+   * (not hover). Optional because older/hover payloads omit it — callers
+   * must fall back to computedStyles-based inference when absent.
+   */
+  inlineStyles?: Record<string, string>;
+  /**
+   * Value of the element's `data-an-primitive` attribute (e.g. "text",
+   * "rectangle", "frame", "ellipse") when present. Canvas-drawn primitives —
+   * including T-tool text, which is a plain `div` — carry this marker so the
+   * inspector can identify them without relying on tagName alone. Optional
+   * because older payloads and non-primitive/source-backed elements omit it.
+   */
+  primitiveKind?: string;
   portableStyleSnapshot?: PortableStyleSnapshot;
   boundingRect: { x: number; y: number; width: number; height: number };
   textContent?: string;

package/corpus/templates/design/app/components/visual-editor/CanvasCommentPins.tsx

@@ -340,16 +340,34 @@ export function CanvasCommentPins({
     const ro = new ResizeObserver(bump);
     ro.observe(canvas);
 
-    // Scroll listeners on the canvas's scrollable ancestor(s) and window cover
-    // both page-level scrolling and container-level panning.
-    const scrollTarget =
-      canvas.closest<HTMLElement>("[class*='overflow']") ?? window;
-    scrollTarget.addEventListener("scroll", bump, { passive: true });
+    // Scroll listeners on every scrollable ancestor and the window cover both
+    // page-level scrolling and container-level panning. Walk the ancestor
+    // chain with getComputedStyle instead of a class-name heuristic so
+    // inline-styled, nested, and multiple scroll containers are all covered.
+    const isScrollable = (value: string) =>
+      value === "auto" || value === "scroll" || value === "overlay";
+    const scrollTargets: Array<HTMLElement | Window> = [];
+    for (let el: HTMLElement | null = canvas; el; el = el.parentElement) {
+      const style = getComputedStyle(el);
+      if (
+        isScrollable(style.overflow) ||
+        isScrollable(style.overflowX) ||
+        isScrollable(style.overflowY)
+      ) {
+        scrollTargets.push(el);
+      }
+    }
+    scrollTargets.push(window);
+    for (const target of scrollTargets) {
+      target.addEventListener("scroll", bump, { passive: true });
+    }
     window.addEventListener("resize", bump, { passive: true });
 
     return () => {
       ro.disconnect();
-      scrollTarget.removeEventListener("scroll", bump);
+      for (const target of scrollTargets) {
+        target.removeEventListener("scroll", bump);
+      }
       window.removeEventListener("resize", bump);
     };
   }, [canvasEl]);

package/corpus/templates/design/app/components/visual-editor/DrawOverlay.tsx

@@ -158,6 +158,10 @@ export function DrawOverlay({
     value: string;
   } | null>(null);
   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 drawing = useRef(false);
   const canvasSizeRef = useRef({ w: 0, h: 0 });
@@ -252,6 +256,7 @@ export function DrawOverlay({
       const rect = canvasRef.current?.getBoundingClientRect();
       if (!rect) return;
       if (textMode) {
+        cancelingTextRef.current = false;
         setTextInput({
           xFrac: (e.clientX - rect.left) / rect.width,
           yFrac: (e.clientY - rect.top) / rect.height,
@@ -708,6 +713,12 @@ export function DrawOverlay({
                   )
                 }
                 onBlur={() => {
+                  // Escape unmounts the input, which fires this blur — skip
+                  // the commit for a cancelled annotation.
+                  if (cancelingTextRef.current) {
+                    cancelingTextRef.current = false;
+                    return;
+                  }
                   if (textInput.value.trim()) commitTextAnnotation();
                 }}
                 onKeyDown={(e) => {
@@ -715,7 +726,10 @@ export function DrawOverlay({
                     e.preventDefault();
                     commitTextAnnotation();
                   }
-                  if (e.key === "Escape") setTextInput(null);
+                  if (e.key === "Escape") {
+                    cancelingTextRef.current = true;
+                    setTextInput(null);
+                  }
                 }}
                 className="h-7 w-48 border-primary bg-background text-sm"
                 autoFocus

package/corpus/templates/design/app/hooks/useDesignHotkeys.ts

@@ -7,6 +7,9 @@ export type DesignHotkeyTool =
   | "move"
   | "frame"
   | "rectangle"
+  | "line"
+  | "arrow"
+  | "ellipse"
   | "text"
   | "pen"
   | "hand"
@@ -33,6 +36,11 @@ export interface DesignHotkeyTabDetails extends DesignHotkeyDetails {
   backwards: boolean;
 }
 
+export interface DesignHotkeyOpacityDetails extends DesignHotkeyDetails {
+  /** 1-100. Digit "1".."9" (no modifier) map to 10-90; "0" maps to 100. */
+  opacity: number;
+}
+
 export type DesignHotkeyTarget = Window | Document | HTMLElement;
 export type DesignHotkeyHandler = (details: DesignHotkeyDetails) => void;
 export type DesignHotkeyToolHandler = (
@@ -43,6 +51,9 @@ export type DesignHotkeyNudgeHandler = (
   details: DesignHotkeyNudgeDetails,
 ) => void;
 export type DesignHotkeyTabHandler = (details: DesignHotkeyTabDetails) => void;
+export type DesignHotkeyOpacityHandler = (
+  details: DesignHotkeyOpacityDetails,
+) => void;
 
 export interface UseDesignHotkeysProps {
   enabled?: boolean;
@@ -55,6 +66,9 @@ export interface UseDesignHotkeysProps {
   onMoveTool?: DesignHotkeyHandler;
   onFrameTool?: DesignHotkeyHandler;
   onRectangleTool?: DesignHotkeyHandler;
+  onLineTool?: DesignHotkeyHandler;
+  onArrowTool?: DesignHotkeyHandler;
+  onEllipseTool?: DesignHotkeyHandler;
   onTextTool?: DesignHotkeyHandler;
   onPenTool?: DesignHotkeyHandler;
   onHandTool?: DesignHotkeyHandler;
@@ -88,6 +102,17 @@ export interface UseDesignHotkeysProps {
   onZoomReset?: DesignHotkeyHandler;
   onZoomToFit?: DesignHotkeyHandler;
   onZoomToSelection?: DesignHotkeyHandler;
+  /** Figma's Shift+0 — zoom to 100%. Distinct from onZoomReset (Cmd+0). */
+  onZoomTo100?: DesignHotkeyHandler;
+  /** Figma's Cmd+Alt+K — create component from the current selection. */
+  onCreateComponent?: 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
+   * handler / its own guard) and the event isn't a modifier combo or an
+   * editable-target keystroke (already filtered by ignoreEditableTargets).
+   */
+  onOpacityChange?: DesignHotkeyOpacityHandler;
 }
 
 const TOOL_SHORTCUTS: Record<
@@ -97,6 +122,8 @@ const TOOL_SHORTCUTS: Record<
   v: { tool: "move", handler: "onMoveTool" },
   f: { tool: "frame", handler: "onFrameTool" },
   r: { tool: "rectangle", handler: "onRectangleTool" },
+  o: { tool: "ellipse", handler: "onEllipseTool" },
+  l: { tool: "line", handler: "onLineTool" },
   t: { tool: "text", handler: "onTextTool" },
   p: { tool: "pen", handler: "onPenTool" },
   h: { tool: "hand", handler: "onHandTool" },
@@ -104,6 +131,17 @@ const TOOL_SHORTCUTS: Record<
   k: { tool: "scale", handler: "onScaleTool" },
 };
 
+// H1: shift+key variants of a base tool shortcut (Figma muscle-memory), e.g.
+// Shift+L selects the arrow tool while plain L selects the line tool. Keyed
+// by the same lowercased key as TOOL_SHORTCUTS; only consulted when
+// event.shiftKey is true so it never shadows the unshifted binding.
+const SHIFT_TOOL_SHORTCUTS: Record<
+  string,
+  { tool: DesignHotkeyTool; handler: keyof UseDesignHotkeysProps }
+> = {
+  l: { tool: "arrow", handler: "onArrowTool" },
+};
+
 const ARROW_DIRECTIONS: Record<string, DesignHotkeyDirection> = {
   ArrowUp: "up",
   ArrowRight: "right",
@@ -255,6 +293,18 @@ function handleDesignHotkey(
     return true;
   };
 
+  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.
+    const shiftToolShortcut = SHIFT_TOOL_SHORTCUTS[key];
+    if (shiftToolShortcut) {
+      return runTool(
+        shiftToolShortcut.tool,
+        props[shiftToolShortcut.handler] as DesignHotkeyHandler | undefined,
+      );
+    }
+  }
+
   if (!primary && !event.altKey && !event.shiftKey) {
     const toolShortcut = TOOL_SHORTCUTS[key];
     if (toolShortcut) {
@@ -319,6 +369,11 @@ function handleDesignHotkey(
   if (primary && key === "-") return run(props.onZoomOut);
   if (primary && key === "0") return run(props.onZoomReset);
 
+  // H2: Cmd+Alt+K — create component from the current selection.
+  if (primary && event.altKey && key === "k") {
+    return run(props.onCreateComponent);
+  }
+
   const digit = digitFromEvent(event);
   if (event.shiftKey && !primary && digit === "1") {
     return run(props.onZoomToFit);
@@ -326,6 +381,28 @@ function handleDesignHotkey(
   if (event.shiftKey && !primary && digit === "2") {
     return run(props.onZoomToSelection);
   }
+  // H2: Shift+0 — zoom to 100%. Distinct from Cmd+0 (onZoomReset above).
+  if (event.shiftKey && !primary && !event.altKey && digit === "0") {
+    return run(props.onZoomTo100);
+  }
+
+  // H2: plain digit 1-9/0 (no modifier) — set selection opacity. Figma maps
+  // 1-9 to 10%-90% and 0 to 100%. Only handled when nothing else claimed the
+  // digit (e.g. Shift+1/Shift+2 zoom above) and no modifier is held; the
+  // caller supplies onOpacityChange only when a layer is selected and canvas
+  // has focus, so an absent handler naturally no-ops here.
+  if (
+    !primary &&
+    !event.altKey &&
+    !event.shiftKey &&
+    digit &&
+    props.onOpacityChange
+  ) {
+    const opacity = digit === "0" ? 100 : Number(digit) * 10;
+    prevent();
+    props.onOpacityChange({ ...details, opacity });
+    return true;
+  }
 
   if (primary && key === "]") {
     return event.altKey ? run(props.onBringToFront) : run(props.onBringForward);

package/corpus/templates/design/app/i18n/zh-TW.ts

@@ -499,6 +499,7 @@ const messages = {
       propsPasted: "屬性已貼上",
       primitiveInsertFailed: "無法將該圖層新增到畫面",
       layerMoveFailed: "無法移動該圖層",
+      layerRenameSelectLayer: "在面板中連按兩下圖層即可重新命名",
       duplicateElementFailed: "無法複製該元素",
       saveCopyError: "無法儲存這個設計的副本",
       auditRunFailed: "無法執行設計稽核",

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

@@ -511,6 +511,8 @@ const enUS = {
       propsPasted: "Properties pasted",
       primitiveInsertFailed: "Could not add that layer to the screen",
       layerMoveFailed: "Could not move that layer",
+      layerRenameSelectLayer:
+        "Double-click the layer in the panel to rename it",
       duplicateElementFailed: "Could not duplicate that element",
       saveCopyError: "Could not save a copy of this design",
       auditRunFailed: "Unable to run design audit",
@@ -8228,6 +8230,7 @@ const designCanvasFeatureOverrides = {
         propsPasted: "属性已粘贴",
         primitiveInsertFailed: "无法将该图层添加到画面",
         layerMoveFailed: "无法移动该图层",
+        layerRenameSelectLayer: "双击面板中的图层即可重命名",
         duplicateElementFailed: "无法复制该元素",
       },
     },
@@ -8288,6 +8291,8 @@ const designCanvasFeatureOverrides = {
         propsPasted: "Propiedades pegadas",
         primitiveInsertFailed: "No se pudo añadir esa capa a la pantalla",
         layerMoveFailed: "No se pudo mover esa capa",
+        layerRenameSelectLayer:
+          "Haz doble clic en la capa del panel para renombrarla",
         duplicateElementFailed: "No se pudo duplicar ese elemento",
       },
     },
@@ -8348,6 +8353,8 @@ const designCanvasFeatureOverrides = {
         propsPasted: "Propriétés collées",
         primitiveInsertFailed: "Impossible d’ajouter ce calque à l’écran",
         layerMoveFailed: "Impossible de déplacer ce calque",
+        layerRenameSelectLayer:
+          "Double-cliquez sur le calque dans le panneau pour le renommer",
         duplicateElementFailed: "Impossible de dupliquer cet élément",
       },
     },
@@ -8409,6 +8416,8 @@ const designCanvasFeatureOverrides = {
         primitiveInsertFailed:
           "Diese Ebene konnte nicht zur Ansicht hinzugefügt werden",
         layerMoveFailed: "Diese Ebene konnte nicht verschoben werden",
+        layerRenameSelectLayer:
+          "Doppelklicken Sie auf die Ebene im Panel, um sie umzubenennen",
         duplicateElementFailed: "Dieses Element konnte nicht dupliziert werden",
       },
     },
@@ -8469,6 +8478,8 @@ const designCanvasFeatureOverrides = {
         propsPasted: "プロパティを貼り付けました",
         primitiveInsertFailed: "そのレイヤーを画面に追加できませんでした",
         layerMoveFailed: "そのレイヤーを移動できませんでした",
+        layerRenameSelectLayer:
+          "パネル内のレイヤーをダブルクリックすると名前を変更できます",
         duplicateElementFailed: "その要素を複製できませんでした",
       },
     },
@@ -8529,6 +8540,8 @@ const designCanvasFeatureOverrides = {
         propsPasted: "속성이 붙여넣어짐",
         primitiveInsertFailed: "해당 레이어를 화면에 추가할 수 없습니다",
         layerMoveFailed: "해당 레이어를 이동할 수 없습니다",
+        layerRenameSelectLayer:
+          "패널에서 레이어를 더블클릭하면 이름을 바꿀 수 있습니다",
         duplicateElementFailed: "해당 요소를 복제할 수 없습니다",
       },
     },
@@ -8589,6 +8602,8 @@ const designCanvasFeatureOverrides = {
         propsPasted: "Propriedades coladas",
         primitiveInsertFailed: "Não foi possível adicionar essa camada à tela",
         layerMoveFailed: "Não foi possível mover essa camada",
+        layerRenameSelectLayer:
+          "Clique duas vezes na camada no painel para renomeá-la",
         duplicateElementFailed: "Não foi possível duplicar esse elemento",
       },
     },
@@ -8649,6 +8664,7 @@ const designCanvasFeatureOverrides = {
         propsPasted: "गुण चिपकाए गए",
         primitiveInsertFailed: "उस परत को स्क्रीन में नहीं जोड़ा जा सका",
         layerMoveFailed: "उस परत को स्थानांतरित नहीं किया जा सका",
+        layerRenameSelectLayer: "नाम बदलने के लिए पैनल में परत पर डबल-क्लिक करें",
         duplicateElementFailed: "उस तत्व की प्रतिलिपि नहीं बनाई जा सकी",
       },
     },
@@ -8709,6 +8725,8 @@ const designCanvasFeatureOverrides = {
         propsPasted: "تم لصق الخصائص",
         primitiveInsertFailed: "تعذرت إضافة تلك الطبقة إلى الشاشة",
         layerMoveFailed: "تعذر نقل تلك الطبقة",
+        layerRenameSelectLayer:
+          "انقر نقرًا مزدوجًا فوق الطبقة في اللوحة لإعادة تسميتها",
         duplicateElementFailed: "تعذّر تكرار هذا العنصر",
       },
     },

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

@@ -1,3 +1,5 @@
+import type { PortableStyleSnapshot } from "@/components/design/types";
+
 export interface ImportResult {
   designId?: string;
   files?: Array<{ id: string; filename: string }>;
@@ -43,3 +45,96 @@ export function importResultSummary(
   if (count === 1) return `Imported ${result!.files![0]!.filename}.`;
   return `Imported ${count} screens.`;
 }
+
+// --- Cross-tab / system-clipboard round-trip (U4/U6) ---
+//
+// The in-memory clipboard refs (copiedLayerEntriesRef etc.) never survive a
+// tab switch, a page reload, or a copy made in another window, and pasting
+// from the OS clipboard after copying elsewhere silently reuses the stale
+// in-memory entries instead. To fix that, every copy embeds a serialized
+// marker comment in the text actually written to navigator.clipboard, and
+// paste parses that marker back out of the live clipboard content so a
+// cross-tab paste (or a same-tab paste after an external copy) round-trips
+// the original entries instead of just raw concatenated HTML.
+
+export interface DesignClipboardLayerEntry {
+  html: string;
+  rootNodeId?: string;
+  sourceFileId: string;
+  portableStyleSnapshot?: PortableStyleSnapshot;
+}
+
+export interface DesignClipboardScreenEntry {
+  filename: string;
+  fileType?: string;
+  content: string;
+  canvasFrame?: {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+  };
+}
+
+export interface DesignClipboardPayload {
+  version: 1;
+  entries: DesignClipboardLayerEntry[];
+  screens?: DesignClipboardScreenEntry[];
+}
+
+const CLIPBOARD_MARKER_PREFIX = "agent-native-clipboard-v1:";
+
+function encodeClipboardMarkerData(payload: DesignClipboardPayload): string {
+  // btoa is UTF-16-unsafe for non-Latin1 text; encodeURIComponent first so
+  // arbitrary copied HTML (emoji, non-Latin scripts, etc.) round-trips.
+  return btoa(encodeURIComponent(JSON.stringify(payload)));
+}
+
+function decodeClipboardMarkerData(
+  data: string,
+): DesignClipboardPayload | null {
+  try {
+    const json = decodeURIComponent(atob(data));
+    const parsed = JSON.parse(json) as unknown;
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      (parsed as { version?: unknown }).version !== 1 ||
+      !Array.isArray((parsed as { entries?: unknown }).entries)
+    ) {
+      return null;
+    }
+    return parsed as DesignClipboardPayload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Appends an invisible marker comment (safe inside HTML and plain text alike)
+ * encoding the full clipboard payload after the human-visible clipboard text.
+ */
+export function serializeDesignClipboardPayload(
+  visibleText: string,
+  payload: DesignClipboardPayload,
+): string {
+  const marker = `<!--${CLIPBOARD_MARKER_PREFIX}${encodeClipboardMarkerData(payload)}-->`;
+  return `${visibleText}\n${marker}`;
+}
+
+/**
+ * Extracts a previously-serialized payload from clipboard text, if present.
+ * Returns null for clipboard content that was never written by this app (a
+ * plain copy from elsewhere, or another app's clipboard payload).
+ */
+export function parseDesignClipboardMarker(
+  text: string | null | undefined,
+): DesignClipboardPayload | null {
+  if (!text) return null;
+  const markerIndex = text.lastIndexOf(`<!--${CLIPBOARD_MARKER_PREFIX}`);
+  if (markerIndex === -1) return null;
+  const start = markerIndex + 4 + CLIPBOARD_MARKER_PREFIX.length;
+  const end = text.indexOf("-->", start);
+  if (end === -1) return null;
+  return decodeClipboardMarkerData(text.slice(start, end));
+}