@agent-native/core 0.84.24 → 0.84.27

package/corpus/core/src/client/sse-event-processor.ts

@@ -150,9 +150,10 @@ export const SSE_ACTION_PREPARATION_STALL_TIMEOUT_MS = 90_000;
 
 type ActivityTrailEntry = AgentActivityTrailEntry;
 
-type PreparingActionState = {
-  tool?: string;
+type PreparingActionEntry = {
+  tool: string;
   startedAt?: number;
+  lastProgressBytes?: number;
   /**
    * Timestamp of the last real streaming progress for the in-preparation tool
    * input. The server emits a throttled `activity` heartbeat per
@@ -165,6 +166,10 @@ type PreparingActionState = {
   lastProgressAt?: number;
 };
 
+type PreparingActionState = {
+  entries?: Map<string, PreparingActionEntry>;
+};
+
 function formatProgressBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -185,8 +190,15 @@ function isPreparingActionActivity(ev: SSEEvent): boolean {
   return label.startsWith("preparing ") && label.includes(" action");
 }
 
-function isProgressEvent(ev: SSEEvent): boolean {
-  return ev.type !== "stream_keepalive";
+function isMeaningfulProgressEvent(
+  ev: SSEEvent,
+  actionPreparationProgress?: boolean,
+): boolean {
+  if (ev.type === "stream_keepalive") return false;
+  if (ev.type === "activity" && isPreparingActionActivity(ev)) {
+    return actionPreparationProgress === true;
+  }
+  return true;
 }
 
 function baseActivityLabel(ev: SSEEvent, tool?: string): string {
@@ -258,19 +270,42 @@ function updatePreparingActionState(
   state: PreparingActionState,
   ev: SSEEvent,
   now: number,
-) {
+): boolean | undefined {
   if (ev.type === "activity" && isPreparingActionActivity(ev)) {
     const tool = ev.tool?.trim() || undefined;
-    if (!tool) return;
-    if (state.tool !== tool || state.startedAt === undefined) {
-      state.tool = tool;
-      state.startedAt = now;
+    if (!tool) return false;
+    const key = ev.id?.trim() || tool;
+    const entries = state.entries ?? new Map<string, PreparingActionEntry>();
+    state.entries = entries;
+    let entry = entries.get(key);
+    if (!entry) {
+      entry = {
+        tool,
+        startedAt: now,
+        lastProgressAt: undefined,
+        lastProgressBytes: undefined,
+      };
+      entries.set(key, entry);
     }
-    // Every tool-input activity is a throttled proof the model is still
-    // streaming this action's argument. Treat it as progress so large inputs
-    // that take many seconds/minutes to stream are NOT flagged as stalled.
-    state.lastProgressAt = now;
-    return;
+    const progressBytes = activityProgressBytes(ev);
+    const previousBytes = entry.lastProgressBytes ?? 0;
+    if (progressBytes !== undefined) {
+      entry.lastProgressBytes = Math.max(previousBytes, progressBytes);
+    }
+    if (!ev.id?.trim()) {
+      if (progressBytes !== undefined && progressBytes > 0) {
+        entry.lastProgressAt = now;
+        return true;
+      }
+      return false;
+    }
+    if (progressBytes !== undefined && progressBytes > previousBytes) {
+      // A byte increase is proof the model is still streaming this action's
+      // argument. Repeated zero-byte prep activity is only a heartbeat.
+      entry.lastProgressAt = now;
+      return true;
+    }
+    return false;
   }
 
   if (
@@ -282,10 +317,19 @@ function updatePreparingActionState(
     ev.type === "error" ||
     ev.type === "missing_api_key"
   ) {
-    state.tool = undefined;
-    state.startedAt = undefined;
-    state.lastProgressAt = undefined;
+    if (ev.type === "tool_start" || ev.type === "tool_done") {
+      const tool = ev.tool?.trim();
+      const id = ev.id?.trim();
+      for (const [key, entry] of state.entries ?? []) {
+        if ((id && key === id) || (!id && entry.tool === tool)) {
+          state.entries?.delete(key);
+        }
+      }
+    } else {
+      state.entries?.clear();
+    }
   }
+  return undefined;
 }
 
 function hasStalledPreparingAction(state: PreparingActionState, now: number) {
@@ -294,11 +338,16 @@ function hasStalledPreparingAction(state: PreparingActionState, now: number) {
   // streaming for a long time. `lastProgressAt` advances on every delta
   // heartbeat, so an actively-streaming large output keeps resetting this and
   // survives; a genuinely stuck prep (keepalive-only, no deltas) trips it.
-  return (
-    state.tool !== undefined &&
-    state.lastProgressAt !== undefined &&
-    now - state.lastProgressAt >= SSE_ACTION_PREPARATION_STALL_TIMEOUT_MS
-  );
+  for (const entry of state.entries?.values() ?? []) {
+    if (
+      entry.startedAt !== undefined &&
+      now - (entry.lastProgressAt ?? entry.startedAt) >=
+        SSE_ACTION_PREPARATION_STALL_TIMEOUT_MS
+    ) {
+      return true;
+    }
+  }
+  return false;
 }
 
 async function readChunkWithProgressTimeout(
@@ -1193,11 +1242,15 @@ export async function* readSSEStream(
           continue;
         }
         const now = Date.now();
-        if (isProgressEvent(ev)) {
+        const actionPreparationProgress = updatePreparingActionState(
+          preparingActionState,
+          ev,
+          now,
+        );
+        if (isMeaningfulProgressEvent(ev, actionPreparationProgress)) {
           sawProgressEvent = true;
           lastMeaningfulEventAt = now;
         }
-        updatePreparingActionState(preparingActionState, ev, now);
 
         // Track sequence number for reconnection
         if (ev.seq !== undefined && onSeq) {
@@ -1355,11 +1408,15 @@ export async function readSSEStreamRaw(
           continue;
         }
         const now = Date.now();
-        if (isProgressEvent(ev)) {
+        const actionPreparationProgress = updatePreparingActionState(
+          preparingActionState,
+          ev,
+          now,
+        );
+        if (isMeaningfulProgressEvent(ev, actionPreparationProgress)) {
           sawProgressEvent = true;
           lastMeaningfulEventAt = now;
         }
-        updatePreparingActionState(preparingActionState, ev, now);
 
         if (ev.seq !== undefined && onSeq) {
           onSeq(ev.seq);

package/corpus/core/src/client/tool-display.ts

@@ -1,5 +1,5 @@
 const TOOL_DISPLAY_NAMES: Record<string, string> = {
-  "delete-file": "delete screen",
+  "delete-file": "remove screen",
   "get-design-snapshot": "get screen snapshot",
   "edit-design": "edit screen",
 };

package/corpus/core/src/sharing/actions/set-resource-visibility.ts

@@ -16,9 +16,9 @@ import {
 
 export default defineAction({
   description:
-    "Change the coarse visibility of a shareable resource: 'private' keeps it owner-only, 'org' shares it with all members of the owner's organization, 'public' makes it accessible to anyone with the link. Owner or admin role required.",
-  // (audit H5) Visibility changes are admin-tier and can flip a private
-  // resource org-wide or public. Refuse from the tools iframe bridge.
+    "Change the coarse visibility of a shareable resource: 'private' keeps it owner-only, 'org' shares it with all members of the owner's organization, 'public' makes it accessible to anyone with the link. Visibility changes require owner or admin role.",
+  // (audit H5) Visibility changes can flip a private resource org-wide or
+  // public. Refuse from the tools iframe bridge.
   toolCallable: false,
   mcpApp: {
     compactCatalog: true,

package/corpus/templates/clips/.agents/skills/video-sharing/SKILL.md

@@ -184,8 +184,10 @@ These endpoints follow the same access model as `/api/public-recording`:
   raw provider URLs.
 
 The share popover's "Share with agents" field should copy the agent context URL,
-not raw transcript text. The context response points agents at the transcript and
-frame APIs so they can fetch only the visual context they need.
+not raw transcript text. Its "Copy agent prompt" field may wrap that URL with
+instructions to fetch transcripts, frames, and browser diagnostics, but it should
+still point agents at the context response so they can fetch only the visual
+context they need.
 
 ## View counting
 

package/corpus/templates/clips/app/components/player/share-dialog.tsx

@@ -324,6 +324,9 @@ function LinkTab({
     ? tokenizedAgentContextUrl
     : publicAgentContextUrl;
   const agentShareDisabled = isPending || !isPublic || !agentContextUrl;
+  const agentPrompt = agentContextUrl
+    ? t("shareDialog.agentPrompt", { agentContextUrl })
+    : "";
 
   return (
     <div className="space-y-4">
@@ -351,6 +354,12 @@ function LinkTab({
         disabled={agentShareDisabled}
       />
 
+      <CopyField
+        label={t("shareDialog.copyAgentPrompt")}
+        value={agentPrompt}
+        disabled={agentShareDisabled}
+      />
+
       {isPublic && hasPassword ? (
         <p className="text-xs text-muted-foreground">
           {t("shareDialog.agentTokenDescription")}

package/corpus/templates/clips/app/i18n/ar-SA.ts

@@ -415,6 +415,9 @@ const messages = {
     embed: "تضمين",
     shareLink: "رابط المشاركة",
     shareWithAgents: "شارك مع الوكلاء",
+    copyAgentPrompt: "نسخ مطالبة الوكيل",
+    agentPrompt:
+      "اجلب عنوان URL لسياق وكيل Clips هذا: {{agentContextUrl}}. استخدم transcript.segments للسياق المنطوق، واجلب recommendedFrames أو عناوين URL الخاصة بواجهة API للإطارات لرؤية الشاشة، وتحقق من browserDiagnostics إن وجدت لسجلات وحدة التحكم المنقحة وبيانات طلبات fetch/XHR الوصفية.",
     agentTokenDescription:
       "يستخدم هذا الوكيل URL رمزًا مميزًا قصير العمر، بحيث يمكن للعملاء قراءة المقطع دون الكشف عن كلمة المرور.",
     gifPreview: "معاينة GIF",

package/corpus/templates/clips/app/i18n/de-DE.ts

@@ -432,6 +432,9 @@ const messages = {
     embed: "Einbetten",
     shareLink: "Teillink",
     shareWithAgents: "Mit Agenten teilen",
+    copyAgentPrompt: "Agent-Prompt kopieren",
+    agentPrompt:
+      "Rufe diese Clips-Agent-Kontext-URL ab: {{agentContextUrl}}. Verwende transcript.segments fuer den gesprochenen Kontext, rufe recommendedFrames oder die Frame-API-URLs ab, um den Bildschirm zu sehen, und pruefe browserDiagnostics, falls vorhanden, fuer redigierte Konsolenprotokolle und fetch/XHR-Anfragemetadaten.",
     agentTokenDescription:
       "Dieser Agent URL verwendet ein kurzlebiges Token, sodass Agenten den Clip lesen können, ohne das Passwort preiszugeben.",
     gifPreview: "GIF-Vorschau",

package/corpus/templates/clips/app/i18n/en-US.ts

@@ -415,6 +415,9 @@ const messages = {
     embed: "Embed",
     shareLink: "Share link",
     shareWithAgents: "Share with agents",
+    copyAgentPrompt: "Copy agent prompt",
+    agentPrompt:
+      "Fetch this Clips agent context URL: {{agentContextUrl}}. Use transcript.segments for spoken context, fetch recommendedFrames or the frame API URLs to see the screen, and check browserDiagnostics if present for redacted console logs and fetch/XHR request metadata.",
     agentTokenDescription:
       "This agent URL uses a short-lived token, so agents can read the clip without exposing the password.",
     gifPreview: "GIF preview",

package/corpus/templates/clips/app/i18n/es-ES.ts

@@ -427,6 +427,9 @@ const messages = {
     embed: "Insertar",
     shareLink: "Enlace para compartir",
     shareWithAgents: "Compartir con agentes",
+    copyAgentPrompt: "Copiar indicación para agente",
+    agentPrompt:
+      "Obtén esta URL de contexto para agentes de Clips: {{agentContextUrl}}. Usa transcript.segments para el contexto hablado, obtén recommendedFrames o las URLs de la API de fotogramas para ver la pantalla y revisa browserDiagnostics si está presente para ver registros de consola redactados y metadatos de solicitudes fetch/XHR.",
     agentTokenDescription:
       "Este agente URL utiliza un token de corta duración, por lo que los agentes pueden leer el clip sin exponer la contraseña.",
     gifPreview: "vista previa de GIF",

package/corpus/templates/clips/app/i18n/fr-FR.ts

@@ -427,6 +427,9 @@ const messages = {
     embed: "Intégrer",
     shareLink: "Lien de partage",
     shareWithAgents: "Partager avec les agents",
+    copyAgentPrompt: "Copier le prompt pour agent",
+    agentPrompt:
+      "Récupère cette URL de contexte Clips pour agent : {{agentContextUrl}}. Utilise transcript.segments pour le contexte parlé, récupère recommendedFrames ou les URLs de l'API d'images pour voir l'écran, et consulte browserDiagnostics s'il est présent pour les journaux de console expurgés et les métadonnées de requêtes fetch/XHR.",
     agentTokenDescription:
       "Cet agent URL utilise un jeton de courte durée, afin que les agents puissent lire le clip sans exposer le mot de passe.",
     gifPreview: "aperçu de GIF",

package/corpus/templates/clips/app/i18n/hi-IN.ts

@@ -412,6 +412,9 @@ const messages = {
     embed: "एम्बेड",
     shareLink: "शेयर लिंक",
     shareWithAgents: "एजेंटों के साथ साझा करें",
+    copyAgentPrompt: "एजेंट प्रॉम्प्ट कॉपी करें",
+    agentPrompt:
+      "यह Clips एजेंट संदर्भ URL प्राप्त करें: {{agentContextUrl}}। बोले गए संदर्भ के लिए transcript.segments का उपयोग करें, स्क्रीन देखने के लिए recommendedFrames या फ्रेम API URL प्राप्त करें, और यदि browserDiagnostics मौजूद हो तो संशोधित कंसोल लॉग और fetch/XHR अनुरोध मेटाडेटा जांचें।",
     agentTokenDescription:
       "यह एजेंट URL एक अल्पकालिक टोकन का उपयोग करता है, ताकि एजेंट पासवर्ड उजागर किए बिना क्लिप पढ़ सकें।",
     gifPreview: "GIF पूर्वावलोकन",

package/corpus/templates/clips/app/i18n/ja-JP.ts

@@ -424,6 +424,9 @@ const messages = {
     embed: "埋め込み",
     shareLink: "共有リンク",
     shareWithAgents: "エージェントと共有する",
+    copyAgentPrompt: "エージェント用プロンプトをコピー",
+    agentPrompt:
+      "この Clips エージェントコンテキスト URL を取得してください: {{agentContextUrl}}。音声の文脈には transcript.segments を使い、画面を見るために recommendedFrames またはフレーム API URL を取得し、browserDiagnostics がある場合は、編集済みのコンソールログと fetch/XHR リクエストのメタデータを確認してください。",
     agentTokenDescription:
       "このエージェント URL は有効期間の短いトークンを使用するため、エージェントはパスワードを公開せずにクリップを読み取ることができます。",
     gifPreview: "GIF プレビュー",

package/corpus/templates/clips/app/i18n/ko-KR.ts

@@ -417,6 +417,9 @@ const messages = {
     embed: "임베드",
     shareLink: "공유 링크",
     shareWithAgents: "상담원과 공유",
+    copyAgentPrompt: "에이전트 프롬프트 복사",
+    agentPrompt:
+      "이 Clips 에이전트 컨텍스트 URL을 가져오세요: {{agentContextUrl}}. 말한 내용의 맥락은 transcript.segments를 사용하고, 화면을 보기 위해 recommendedFrames 또는 프레임 API URL을 가져오며, browserDiagnostics가 있으면 수정된 콘솔 로그와 fetch/XHR 요청 메타데이터를 확인하세요.",
     agentTokenDescription:
       "이 에이전트 URL는 수명이 짧은 토큰을 사용하므로 에이전트는 비밀번호를 노출하지 않고도 클립을 읽을 수 있습니다.",
     gifPreview: "GIF 미리보기",

package/corpus/templates/clips/app/i18n/pt-BR.ts

@@ -425,6 +425,9 @@ const messages = {
     embed: "Incorporar",
     shareLink: "Link de compartilhamento",
     shareWithAgents: "Compartilhe com agentes",
+    copyAgentPrompt: "Copiar prompt para agente",
+    agentPrompt:
+      "Busque esta URL de contexto para agentes do Clips: {{agentContextUrl}}. Use transcript.segments para o contexto falado, busque recommendedFrames ou as URLs da API de quadros para ver a tela e confira browserDiagnostics, se presente, para logs de console redigidos e metadados de solicitações fetch/XHR.",
     agentTokenDescription:
       "Este agente URL usa um token de curta duração, para que os agentes possam ler o clipe sem expor a senha.",
     gifPreview: "visualização de GIF",

package/corpus/templates/clips/app/i18n/zh-CN.ts

@@ -399,6 +399,9 @@ const messages = {
     embed: "嵌入",
     shareLink: "分享链接",
     shareWithAgents: "与代理商分享",
+    copyAgentPrompt: "复制代理提示",
+    agentPrompt:
+      "获取这个 Clips 代理上下文 URL：{{agentContextUrl}}。使用 transcript.segments 读取语音上下文，获取 recommendedFrames 或帧 API URL 来查看屏幕，并在 browserDiagnostics 存在时检查经过脱敏的控制台日志和 fetch/XHR 请求元数据。",
     agentTokenDescription:
       "该代理 URL 使用短期令牌，因此代理可以在不暴露密码的情况下读取剪辑。",
     gifPreview: "GIF 预览",

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

@@ -399,6 +399,9 @@ const messages = {
     embed: "嵌入",
     shareLink: "分享連結",
     shareWithAgents: "與 Agent 分享",
+    copyAgentPrompt: "複製 Agent 提示",
+    agentPrompt:
+      "取得這個 Clips Agent 脈絡 URL：{{agentContextUrl}}。使用 transcript.segments 讀取語音脈絡，取得 recommendedFrames 或影格 API URL 來查看螢幕，並在 browserDiagnostics 存在時檢查已遮蔽的主控台記錄和 fetch/XHR 請求中繼資料。",
     agentTokenDescription:
       "此 Agent URL 使用短期權杖，因此 Agent 可以在不暴露密碼的情況下讀取剪輯。",
     gifPreview: "GIF 預覽",

package/corpus/templates/clips/changelog/2026-07-01-shared-clips-can-now-copy-a-ready-to-send-prompt-that-tells-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-01
+---
+
+Shared clips can now copy a ready-to-send prompt that tells agents how to read transcripts, frames, and diagnostics.

package/corpus/templates/design/actions/insert-asset.ts

@@ -57,6 +57,14 @@ function escapeHtml(value: string): string {
     .replace(/"/g, """);
 }
 
+function createInsertedNodeId(prefix: string): string {
+  const random =
+    typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+      ? crypto.randomUUID().replace(/-/g, "").slice(0, 12)
+      : Math.random().toString(36).slice(2, 14);
+  return `inserted-${prefix}-${random}`;
+}
+
 function insertBeforeClosingTag(
   html: string,
   closingTag: "main" | "body",
@@ -70,6 +78,7 @@ function insertBeforeClosingTag(
 function appendAssetMarkup(
   html: string,
   args: z.infer<typeof schemaInput>,
+  nodeId: string,
 ): string {
   const label = args.title?.trim() || args.altText?.trim() || "Generated asset";
   const escapedUrl = escapeHtml(args.assetUrl);
@@ -82,7 +91,7 @@ function appendAssetMarkup(
       ? `<video src="${escapedUrl}" controls class="w-full rounded-xl object-cover"></video>`
       : `<img src="${escapedUrl}" alt="${escapeHtml(args.altText?.trim() || label)}" class="w-full rounded-xl object-cover" />`;
   const snippet = `
-    <section class="mx-auto my-8 max-w-5xl px-4" data-agent-native-asset${assetIdAttr}>
+    <section class="mx-auto my-8 max-w-5xl px-4" data-agent-native-asset data-agent-native-node-id="${escapeHtml(nodeId)}" data-agent-native-layer-name="${escapedLabel}"${assetIdAttr}>
       <figure class="overflow-hidden rounded-2xl border border-slate-200 bg-white shadow-sm">
         ${media}
         <figcaption class="px-4 py-3 text-sm text-slate-600">${escapedLabel}</figcaption>
@@ -191,7 +200,8 @@ export default defineAction({
       // Collab read is best-effort; fall back to stored content.
     }
 
-    const content = appendAssetMarkup(base, args);
+    const insertedNodeId = createInsertedNodeId("asset");
+    const content = appendAssetMarkup(base, args, insertedNodeId);
     const now = new Date().toISOString();
     await db
       .update(schema.designFiles)
@@ -213,6 +223,8 @@ export default defineAction({
       fileId: file.id,
       filename: file.filename,
       inserted: true,
+      insertedNodeId,
+      insertedSelector: `[data-agent-native-node-id="${insertedNodeId}"]`,
       assetId: args.assetId ?? null,
       assetUrl: args.assetUrl,
     };

package/corpus/templates/design/actions/insert-design-native-asset.ts

@@ -50,9 +50,17 @@ function insertBeforeClosingTag(
   return html.replace(pattern, `${snippet}\n</${closingTag}>`);
 }
 
-function nativeSnippet(kind: DesignNativeAssetKind): string {
+function createInsertedNodeId(prefix: string): string {
+  const random =
+    typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+      ? crypto.randomUUID().replace(/-/g, "").slice(0, 12)
+      : Math.random().toString(36).slice(2, 14);
+  return `inserted-${prefix}-${random}`;
+}
+
+function nativeSnippet(kind: DesignNativeAssetKind, nodeId: string): string {
   const attrs = (componentName: string) =>
-    `data-agent-native-native-asset data-agent-native-component="${componentName}" data-agent-native-layer-name="${componentName}"`;
+    `data-agent-native-native-asset data-agent-native-node-id="${nodeId}" data-agent-native-component="${componentName}" data-agent-native-layer-name="${componentName}"`;
   switch (kind) {
     case "section-frame":
       return `
@@ -137,8 +145,9 @@ function nativeSnippet(kind: DesignNativeAssetKind): string {
 function appendNativeAssetMarkup(
   html: string,
   kind: DesignNativeAssetKind,
+  nodeId: string,
 ): string {
-  const snippet = nativeSnippet(kind);
+  const snippet = nativeSnippet(kind, nodeId);
   return (
     insertBeforeClosingTag(html, "main", snippet) ??
     insertBeforeClosingTag(html, "body", snippet) ??
@@ -239,7 +248,8 @@ export default defineAction({
       // Collab read is best-effort; fall back to stored content.
     }
 
-    const content = appendNativeAssetMarkup(base, args.kind);
+    const insertedNodeId = createInsertedNodeId("native");
+    const content = appendNativeAssetMarkup(base, args.kind, insertedNodeId);
     const now = new Date().toISOString();
     await db
       .update(schema.designFiles)
@@ -261,6 +271,8 @@ export default defineAction({
       fileId: file.id,
       filename: file.filename,
       inserted: true,
+      insertedNodeId,
+      insertedSelector: `[data-agent-native-node-id="${insertedNodeId}"]`,
       source: "design-native",
       kind: args.kind,
     };

package/corpus/templates/design/actions/insert-figma-library-asset.ts

@@ -66,6 +66,14 @@ function escapeHtml(value: string): string {
     .replace(/"/g, """);
 }
 
+function createInsertedNodeId(prefix: string): string {
+  const random =
+    typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+      ? crypto.randomUUID().replace(/-/g, "").slice(0, 12)
+      : Math.random().toString(36).slice(2, 14);
+  return `inserted-${prefix}-${random}`;
+}
+
 function insertBeforeClosingTag(
   html: string,
   closingTag: "main" | "body",
@@ -83,6 +91,7 @@ function optionalDataAttribute(name: string, value: string | undefined) {
 function appendFigmaAssetMarkup(
   html: string,
   args: z.infer<typeof schemaInput>,
+  nodeId: string,
 ): string {
   const label = args.name?.trim() || "Figma library asset";
   const description = args.description?.trim();
@@ -90,7 +99,7 @@ function appendFigmaAssetMarkup(
     ? `<a href="${escapeHtml(args.sourceUrl)}" target="_blank" rel="noreferrer" class="text-slate-500 underline decoration-slate-300 underline-offset-2 hover:text-slate-800">Open in Figma</a>`
     : "";
   const snippet = `
-    <section class="mx-auto my-8 max-w-5xl px-4" data-agent-native-asset-source="figma" data-agent-native-figma-asset data-figma-file-key="${escapeHtml(args.fileKey)}"${optionalDataAttribute("data-figma-node-id", args.nodeId)}${optionalDataAttribute("data-figma-component-key", args.componentKey)} data-figma-asset-kind="${escapeHtml(args.kind)}">
+    <section class="mx-auto my-8 max-w-5xl px-4" data-agent-native-asset-source="figma" data-agent-native-figma-asset data-agent-native-node-id="${escapeHtml(nodeId)}" data-agent-native-layer-name="${escapeHtml(label)}" data-figma-file-key="${escapeHtml(args.fileKey)}"${optionalDataAttribute("data-figma-node-id", args.nodeId)}${optionalDataAttribute("data-figma-component-key", args.componentKey)} data-figma-asset-kind="${escapeHtml(args.kind)}">
       <figure class="overflow-hidden rounded-2xl border border-slate-200 bg-white shadow-sm">
         <img src="${escapeHtml(args.renderUrl)}" alt="${escapeHtml(label)}" class="w-full rounded-t-2xl object-contain" />
         <figcaption class="flex flex-wrap items-center gap-x-3 gap-y-1 px-4 py-3 text-sm text-slate-600">
@@ -201,7 +210,8 @@ export default defineAction({
       // Collab read is best-effort; fall back to stored content.
     }
 
-    const content = appendFigmaAssetMarkup(base, args);
+    const insertedNodeId = createInsertedNodeId("figma");
+    const content = appendFigmaAssetMarkup(base, args, insertedNodeId);
     const now = new Date().toISOString();
     await db
       .update(schema.designFiles)
@@ -223,6 +233,8 @@ export default defineAction({
       fileId: file.id,
       filename: file.filename,
       inserted: true,
+      insertedNodeId,
+      insertedSelector: `[data-agent-native-node-id="${insertedNodeId}"]`,
       source: "figma",
       fileKey: args.fileKey,
       nodeId: args.nodeId ?? null,

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

@@ -1775,6 +1775,11 @@ export function DesignCanvas({
   // explicit viewport width (e.g. 390 / 768 / 1280 side-by-side breakpoints).
   const resolvedWidth =
     previewWidthPx != null ? `${previewWidthPx}px` : iframeWidth;
+  const focusScrollSurface = useCallback(() => {
+    const surface = scrollContainerRef.current;
+    if (!surface || document.activeElement === surface) return;
+    surface.focus({ preventScroll: true });
+  }, []);
 
   // Wrap the iframe in a positioned container so DrawOverlay /
   // CanvasCommentPins can absolutely-position themselves on top of the
@@ -1901,6 +1906,9 @@ export function DesignCanvas({
       return (
         <div
           ref={scrollContainerRef}
+          tabIndex={-1}
+          onPointerEnter={focusScrollSurface}
+          onMouseEnter={focusScrollSurface}
           className="relative h-full w-full overflow-hidden"
         >
           {iframeElement}
@@ -1915,6 +1923,9 @@ export function DesignCanvas({
     return (
       <div
         ref={scrollContainerRef}
+        tabIndex={-1}
+        onPointerEnter={focusScrollSurface}
+        onMouseEnter={focusScrollSurface}
         className="relative h-full w-full overflow-hidden"
         style={{
           width: embeddedFrame.displayWidth,
@@ -1945,6 +1956,9 @@ export function DesignCanvas({
   return (
     <div
       ref={scrollContainerRef}
+      tabIndex={-1}
+      onPointerEnter={focusScrollSurface}
+      onMouseEnter={focusScrollSurface}
       className="relative flex-1 h-full overflow-auto"
     >
       {/* Canvas area. "none" mode fills the canvas (responsive preview);