@agent-native/toolkit 0.228.0-nightly-20261111212500 → 0.228.0

package/src/app/i18n/catalogs/zh-CN.ts

@@ -45,10 +45,13 @@ const messages: ToolkitAgentChatTranslation = {
   "activity.groupLabel": "智能体活动",
   "activity.agents": "智能体协作",
   "activity.tasks": "智能体任务",
+  "activity.tasksProgress": "{{total}} 项中已完成 {{completed}} 项",
   "agent.started": "开始工作了",
   "agent.resumed": "恢复了工作",
   "agent.messaged": "发送了消息",
   "agent.delegated": "委派了工作",
+  "agent.working": "正在工作",
+  "agent.workedFor": "工作了 {{duration}}",
   "agent.paused": "暂停了工作",
   "agent.queued": "排队中",
   "agent.completed": "已完成",
@@ -422,6 +425,7 @@ const messages: ToolkitAgentChatTranslation = {
   "composer.attachmentTooLarge": "文件超过 8 MB",
   "composer.attachmentNotUtf8": "文件不是 UTF-8 文本",
   "composer.scrollToBottom": "滚动到底部",
+  "composer.skipToMessageBox": "跳到消息输入框",
   "composer.suggestedPrompts": "推荐提示",
   "composer.stopResponse": "停止响应",
   "composer.subAgentReadOnly":
@@ -577,6 +581,7 @@ const messages: ToolkitAgentChatTranslation = {
   "pastedText.remove": "移除粘贴的文本",
   "pastedText.title": "粘贴的文本",
   "voice.dictation.start": "听写（{{shortcut}}）",
+  "voice.dictation.startPlain": "听写",
   "voice.dictation.stopRecording": "停止录音",
   "voice.dictation.transcribing": "正在转写…",
   "voiceMode.errors.channelDisconnected": "实时语音控制通道已断开。",
@@ -3137,6 +3142,14 @@ const messages: ToolkitAgentChatTranslation = {
   "guided.other": "其他…",
   "guided.otherDescription": "准确告诉智能体你的意思。",
   "guided.recommended": "推荐",
+  "guided.question": "问题",
+  "guided.questionProgress": "{{current}}/{{total}}",
+  "guided.questionProgressLabel": "第 {{current}} 个，共 {{total}} 个",
+  "guided.ownResponse": "或者输入你自己的回答",
+  "guided.next": "下一个",
+  "guided.send": "发送",
+  "guided.dismiss": "关闭问题",
+  "guided.chooseFiles": "选择文件…",
   "guided.typeAnswer": "输入你的回答…",
   "guided.typeCustomAnswer": "输入自定义回答…",
   "guided.dropFiles": "将文件拖到此处，或",
@@ -3174,6 +3187,10 @@ const messages: ToolkitAgentChatTranslation = {
   "toolCells.showMoreLines": "再显示 {{count}} 行",
   "toolCells.partial": "部分",
   "toolCells.timedOut": "已超时",
+  "toolCells.exitCode": "退出码 {{code}}",
+  "toolCells.copyOutput": "复制输出",
+  "toolCells.lineAdded": "已添加",
+  "toolCells.lineRemoved": "已删除",
   "codeRequired.requestFailed": "请求失败（{{status}}）",
   "chatFirst.chats": "聊天",
   "chatFirst.noChats": "还没有聊天。",
@@ -3287,6 +3304,7 @@ const messages: ToolkitAgentChatTranslation = {
   "mentions.noCommands": "没有命令",
   "mentions.noMatches": "没有匹配项",
   "queue.dragToReorder": "拖动以重新排序",
+  "queue.attachedImage": "附加的图片",
   "queue.moveUp": "上移",
   "queue.moveDown": "下移",
   "queue.movedToPosition": "已移到第 {{position}} 位，共 {{count}} 位",
@@ -3340,6 +3358,10 @@ const messages: ToolkitAgentChatTranslation = {
   "workSteps.readPagesOther": "阅读了 {{count}} 个网页",
   "workSteps.fetchedOne": "获取了 1 个 URL",
   "workSteps.fetchedOther": "获取了 {{count}} 个 URL",
+  "workSteps.sourcesOne": "使用了 1 个来源",
+  "workSteps.sourcesOther": "使用了 {{count}} 个来源",
+  "workSteps.frameworkFrames": "{{count}} 个框架帧",
+  "workSteps.copyStackTrace": "复制堆栈跟踪",
   "workSteps.readFilesOne": "读取了 1 个文件",
   "workSteps.readFilesOther": "读取了 {{count}} 个文件",
   "workSteps.editedOne": "编辑了 1 个文件",

package/src/app/i18n/catalogs/zh-TW.ts

@@ -46,10 +46,13 @@ const messages: ToolkitAgentChatTranslation = {
   "activity.groupLabel": "代理活動",
   "activity.agents": "代理協作",
   "activity.tasks": "代理任務",
+  "activity.tasksProgress": "{{total}} 項中已完成 {{completed}} 項",
   "agent.started": "開始工作",
   "agent.resumed": "恢復工作",
   "agent.messaged": "傳送了訊息",
   "agent.delegated": "已委派工作",
+  "agent.working": "正在工作",
+  "agent.workedFor": "工作了 {{duration}}",
   "agent.paused": "已暫停工作",
   "agent.queued": "排隊中",
   "agent.completed": "已完成",
@@ -423,6 +426,7 @@ const messages: ToolkitAgentChatTranslation = {
   "composer.attachmentTooLarge": "檔案超過 8 MB",
   "composer.attachmentNotUtf8": "檔案不是 UTF-8 文字",
   "composer.scrollToBottom": "捲動到底部",
+  "composer.skipToMessageBox": "跳至訊息輸入框",
   "composer.suggestedPrompts": "建議提示",
   "composer.stopResponse": "停止回應",
   "composer.subAgentReadOnly":
@@ -578,6 +582,7 @@ const messages: ToolkitAgentChatTranslation = {
   "pastedText.remove": "移除貼上的文字",
   "pastedText.title": "貼上的文字",
   "voice.dictation.start": "聽寫（{{shortcut}}）",
+  "voice.dictation.startPlain": "聽寫",
   "voice.dictation.stopRecording": "停止錄音",
   "voice.dictation.transcribing": "正在轉錄…",
   "voiceMode.errors.channelDisconnected": "即時語音控制頻道已中斷連線。",
@@ -3154,6 +3159,14 @@ const messages: ToolkitAgentChatTranslation = {
   "guided.other": "其他…",
   "guided.otherDescription": "明確告訴代理你的意思。",
   "guided.recommended": "推薦",
+  "guided.question": "問題",
+  "guided.questionProgress": "{{current}}/{{total}}",
+  "guided.questionProgressLabel": "第 {{current}} 個，共 {{total}} 個",
+  "guided.ownResponse": "或輸入你自己的回答",
+  "guided.next": "下一個",
+  "guided.send": "傳送",
+  "guided.dismiss": "關閉問題",
+  "guided.chooseFiles": "選擇檔案…",
   "guided.typeAnswer": "輸入你的回答…",
   "guided.typeCustomAnswer": "輸入自訂回答…",
   "guided.dropFiles": "將檔案拖曳到這裡，或",
@@ -3191,6 +3204,10 @@ const messages: ToolkitAgentChatTranslation = {
   "toolCells.showMoreLines": "再顯示 {{count}} 行",
   "toolCells.partial": "部分",
   "toolCells.timedOut": "已逾時",
+  "toolCells.exitCode": "結束代碼 {{code}}",
+  "toolCells.copyOutput": "複製輸出",
+  "toolCells.lineAdded": "已新增",
+  "toolCells.lineRemoved": "已刪除",
   "codeRequired.requestFailed": "要求失敗（{{status}}）",
   "chatFirst.chats": "聊天",
   "chatFirst.noChats": "還沒有聊天。",
@@ -3304,6 +3321,7 @@ const messages: ToolkitAgentChatTranslation = {
   "mentions.noCommands": "沒有指令",
   "mentions.noMatches": "沒有相符項目",
   "queue.dragToReorder": "拖曳以重新排序",
+  "queue.attachedImage": "附加的圖片",
   "queue.moveUp": "上移",
   "queue.moveDown": "下移",
   "queue.movedToPosition": "已移到第 {{position}} 位，共 {{count}} 位",
@@ -3358,6 +3376,10 @@ const messages: ToolkitAgentChatTranslation = {
   "workSteps.readPagesOther": "閱讀了 {{count}} 個網頁",
   "workSteps.fetchedOne": "擷取了 1 個 URL",
   "workSteps.fetchedOther": "擷取了 {{count}} 個 URL",
+  "workSteps.sourcesOne": "使用了 1 個來源",
+  "workSteps.sourcesOther": "使用了 {{count}} 個來源",
+  "workSteps.frameworkFrames": "{{count}} 個框架堆疊框",
+  "workSteps.copyStackTrace": "複製堆疊追蹤",
   "workSteps.readFilesOne": "讀取了 1 個檔案",
   "workSteps.readFilesOther": "讀取了 {{count}} 個檔案",
   "workSteps.editedOne": "編輯了 1 個檔案",

package/src/app/onboarding/first-run-first-paint.spec.ts

@@ -0,0 +1,39 @@
+// @vitest-environment happy-dom
+
+import { FIRST_RUN_ONBOARDING_COOKIE } from "@agent-native/core/shared/first-run-onboarding";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  FIRST_RUN_PENDING_ATTRIBUTE,
+  getFirstRunFirstPaintScriptBody,
+} from "./first-run-first-paint.js";
+
+function runBootScript() {
+  // The body is inlined into the SSR shell as a classic script.
+  new Function(getFirstRunFirstPaintScriptBody())();
+}
+
+describe("first-run first-paint boot script", () => {
+  afterEach(() => {
+    document.documentElement.removeAttribute(FIRST_RUN_PENDING_ATTRIBUTE);
+    document.cookie = `${FIRST_RUN_ONBOARDING_COOKIE}=; Max-Age=0; path=/`;
+    document.cookie = "other=; Max-Age=0; path=/";
+  });
+
+  it("marks the document while the first-run cookie is present", () => {
+    document.cookie = "other=1; path=/";
+    document.cookie = `${FIRST_RUN_ONBOARDING_COOKIE}=1; path=/`;
+    runBootScript();
+    expect(
+      document.documentElement.hasAttribute(FIRST_RUN_PENDING_ATTRIBUTE),
+    ).toBe(true);
+  });
+
+  it("leaves the document unmarked without the cookie", () => {
+    document.cookie = "other=1; path=/";
+    runBootScript();
+    expect(
+      document.documentElement.hasAttribute(FIRST_RUN_PENDING_ATTRIBUTE),
+    ).toBe(false);
+  });
+});

package/src/app/onboarding/first-run-first-paint.ts

@@ -0,0 +1,24 @@
+import { FIRST_RUN_ONBOARDING_COOKIE } from "@agent-native/core/shared/first-run-onboarding";
+
+/**
+ * Set on <html> before the first paint while the first-run cookie says
+ * onboarding may start. The SSR shell is shared by every visitor, so a
+ * first-paint home is swapped for a plain skeleton by CSS keyed to this
+ * attribute, never by rendering a different tree.
+ */
+export const FIRST_RUN_PENDING_ATTRIBUTE =
+  "data-agent-native-first-run-pending";
+
+export function getFirstRunFirstPaintScriptBody(): string {
+  const entry = JSON.stringify(`${FIRST_RUN_ONBOARDING_COOKIE}=1`);
+  const attribute = JSON.stringify(FIRST_RUN_PENDING_ATTRIBUTE);
+  // An unreadable cookie leaves the attribute unset, which is what the startup
+  // gate does with one too: it skips first run (and logs why).
+  // coercion-ok: an inline pre-paint script has no caller to report to.
+  return `(function(){try{if(document.cookie.split(";").some(function(c){return c.trim()===${entry}}))document.documentElement.setAttribute(${attribute},"")}catch(_){}})();`;
+}
+
+export function clearFirstRunFirstPaint(): void {
+  if (typeof document === "undefined") return;
+  document.documentElement.removeAttribute(FIRST_RUN_PENDING_ATTRIBUTE);
+}

package/src/app/onboarding/first-run-startup-gate.spec.tsx

@@ -29,17 +29,24 @@ vi.mock("@agent-native/core/client/onboarding/use-preview-mode", () => ({
 }));
 
 vi.mock("./FirstRunOnboarding.js", () => ({
-  FirstRunOnboarding: ({ initialFirstRun }: { initialFirstRun?: boolean }) => (
-    <div
-      data-testid="first-run-onboarding"
-      data-initial-first-run={String(initialFirstRun === true)}
-    />
-  ),
+  FirstRunOnboarding: ({ initialFirstRun }: { initialFirstRun?: boolean }) => {
+    const [mountId] = React.useState(() => ++nextOnboardingMountId);
+    return (
+      <div
+        data-testid="first-run-onboarding"
+        data-initial-first-run={String(initialFirstRun === true)}
+        data-mount-id={mountId}
+      />
+    );
+  },
 }));
 
+let nextOnboardingMountId = 0;
+
 import { SessionPreloadContext } from "@agent-native/core/client/use-session";
 import { FIRST_RUN_ONBOARDING_COOKIE } from "@agent-native/core/shared/first-run-onboarding";
 
+import { FIRST_RUN_PENDING_ATTRIBUTE } from "./first-run-first-paint.js";
 import {
   FirstRunOnboardingStartupGate,
   useFirstRunOnboardingGateOwnsSurface,
@@ -97,13 +104,17 @@ describe("FirstRunOnboardingStartupGate", () => {
     container.remove();
     vi.unstubAllGlobals();
     document.cookie = `${FIRST_RUN_ONBOARDING_COOKIE}=; Max-Age=0; path=/`;
+    document.documentElement.removeAttribute(FIRST_RUN_PENDING_ATTRIBUTE);
   });
 
-  it("reserves onboarding ownership while Builder setup runs without mounting the onboarding surface", async () => {
+  it("covers the app while Builder setup defers an eligible first run, without mounting the onboarding surface", async () => {
     mocks.fetchStatus.mockResolvedValue(true);
     await act(async () => {
       root.render(
-        <FirstRunOnboardingStartupGate deferSurface>
+        <FirstRunOnboardingStartupGate
+          deferSurface
+          cover={<div data-testid="startup-skeleton" />}
+        >
           <GateOwnershipProbe />
         </FirstRunOnboardingStartupGate>,
       );
@@ -111,20 +122,118 @@ describe("FirstRunOnboardingStartupGate", () => {
     expect(
       container.querySelector('[data-testid="gate-ownership"]')?.textContent,
     ).toBe("true");
+    // oracle-change: an eligible first run under deferral used to leave the
+    // home painted and usable, so it flashed before the role question.
+    expect(
+      container.querySelector(
+        "[data-first-run-cover] [data-testid='startup-skeleton']",
+      ),
+    ).not.toBeNull();
     expect(
       container.querySelector('[data-first-run-app-inert="true"]'),
-    ).toBeNull();
-    expect(container.querySelector("[aria-hidden='true']")).toBeNull();
+    ).not.toBeNull();
     expect(
       container
         .querySelector("[data-testid='gate-ownership']")
         ?.getAttribute("data-blocked"),
-    ).toBe("false");
+    ).toBe("true");
     expect(
       container.querySelector('[data-testid="first-run-onboarding"]'),
     ).toBeNull();
   });
 
+  it("lifts the first-paint stand-in once first run is ruled out", async () => {
+    const status = deferred<boolean>();
+    mocks.fetchStatus.mockReturnValue(status.promise);
+    document.documentElement.setAttribute(FIRST_RUN_PENDING_ATTRIBUTE, "");
+
+    act(() => {
+      root.render(
+        <FirstRunOnboardingStartupGate>
+          <div data-testid="app-content">app</div>
+        </FirstRunOnboardingStartupGate>,
+      );
+    });
+    expect(
+      document.documentElement.hasAttribute(FIRST_RUN_PENDING_ATTRIBUTE),
+    ).toBe(true);
+
+    await act(async () => {
+      status.resolve(false);
+      await status.promise;
+    });
+    expect(
+      document.documentElement.hasAttribute(FIRST_RUN_PENDING_ATTRIBUTE),
+    ).toBe(false);
+  });
+
+  it("keeps an ineligible user's app usable while Builder setup defers onboarding", async () => {
+    mocks.fetchStatus.mockResolvedValue(false);
+    await act(async () => {
+      root.render(
+        <FirstRunOnboardingStartupGate deferSurface>
+          <GateOwnershipProbe />
+        </FirstRunOnboardingStartupGate>,
+      );
+    });
+    expect(container.querySelector("[data-first-run-cover]")).toBeNull();
+    expect(container.querySelector("[data-first-run-app-inert]")).toBeNull();
+    expect(
+      container
+        .querySelector("[data-testid='gate-ownership']")
+        ?.getAttribute("data-blocked"),
+    ).toBe("false");
+  });
+
+  it("keeps onboarding on screen when a deferral starts after it appears", async () => {
+    mocks.fetchStatus.mockResolvedValue(true);
+    const renderGate = (deferSurface: boolean) =>
+      act(async () => {
+        root.render(
+          <FirstRunOnboardingStartupGate deferSurface={deferSurface}>
+            <div data-testid="app-content">app</div>
+          </FirstRunOnboardingStartupGate>,
+        );
+      });
+    await renderGate(false);
+    await vi.waitFor(() => {
+      expect(
+        container.querySelector("[data-testid='first-run-onboarding']"),
+      ).not.toBeNull();
+    });
+    const mountId = container
+      .querySelector("[data-testid='first-run-onboarding']")
+      ?.getAttribute("data-mount-id");
+
+    await renderGate(true);
+
+    expect(
+      container
+        .querySelector("[data-testid='first-run-onboarding']")
+        ?.getAttribute("data-mount-id"),
+    ).toBe(mountId);
+    expect(container.querySelector("[data-first-run-cover]")).toBeNull();
+    expect(
+      container
+        .querySelector("[data-testid='app-content']")
+        ?.closest("[inert]"),
+    ).not.toBeNull();
+  });
+
+  it("paints a skeleton, not a blank screen, when the caller passes no cover", async () => {
+    mocks.fetchStatus.mockReturnValue(new Promise(() => {}));
+    await act(async () => {
+      root.render(
+        <FirstRunOnboardingStartupGate>
+          <div data-testid="app-content">app</div>
+        </FirstRunOnboardingStartupGate>,
+      );
+    });
+    expect(
+      container.querySelector("[data-first-run-cover] .skeleton-shimmer"),
+    ).not.toBeNull();
+  });
+
   it("holds the status read while the session preloads, then reads once it resolves", async () => {
     mocks.fetchStatus.mockResolvedValue(false);
     const renderGate = (preloading: boolean) =>
@@ -201,7 +310,7 @@ describe("FirstRunOnboardingStartupGate", () => {
     ).not.toBeNull();
   });
 
-  it("keeps the app visible but inert while eligibility is unresolved", async () => {
+  it("keeps the app mounted, inert and covered while eligibility is unresolved", async () => {
     const status = deferred<boolean>();
     mocks.fetchStatus.mockReturnValue(status.promise);
 
@@ -218,7 +327,7 @@ describe("FirstRunOnboardingStartupGate", () => {
     expect(
       container.querySelector("[data-first-run-startup-loading]"),
     ).toBeNull();
-    // oracle-change: the app paints behind onboarding while first-run eligibility resolves.
+    // oracle-change: the app stays mounted under the startup cover while first-run eligibility resolves.
     expect(
       container.querySelector("[data-testid='app-content']"),
     ).not.toBeNull();
@@ -226,6 +335,7 @@ describe("FirstRunOnboardingStartupGate", () => {
     expect(
       container.querySelector("[data-first-run-app-inert]"),
     ).not.toBeNull();
+    expect(container.querySelector("[data-first-run-cover]")).not.toBeNull();
     expect(
       container.querySelector("[data-testid='gate-ownership']")?.textContent,
     ).toBe("true");
@@ -235,6 +345,7 @@ describe("FirstRunOnboardingStartupGate", () => {
       await status.promise;
     });
     expect(container.querySelector("[data-first-run-app-inert]")).toBeNull();
+    expect(container.querySelector("[data-first-run-cover]")).toBeNull();
   });
 
   it("retries a failed status read before revealing a first-run app", async () => {
@@ -538,6 +649,7 @@ describe("FirstRunOnboardingStartupGate", () => {
         container.querySelector("[data-testid='first-run-onboarding']"),
       ).not.toBeNull();
     });
+    expect(container.querySelector("[data-first-run-cover]")).toBeNull();
     expect(container.querySelector("[data-first-run-app-hidden]")).toBeNull();
     expect(
       container.querySelector("[data-testid='app-content']"),

package/src/app/onboarding/first-run-startup-gate.tsx

@@ -6,8 +6,10 @@ import { useOnboardingPreviewMode } from "@agent-native/core/client/onboarding/u
 import { useSessionPreloading } from "@agent-native/core/client/use-session";
 import { FIRST_RUN_ONBOARDING_COOKIE } from "@agent-native/core/shared/first-run-onboarding";
 import { Button } from "@agent-native/toolkit/ui/button";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import React, { Suspense, lazy, useEffect, useState } from "react";
 
+import { clearFirstRunFirstPaint } from "./first-run-first-paint.js";
 import {
   FirstRunOnboardingGateContext,
   StartupInteractionContext,
@@ -53,15 +55,27 @@ function readFirstRunOnboardingCookieState(): FirstRunCookieState {
   }
 }
 
+function DefaultStartupCover() {
+  return (
+    <div className="flex h-full gap-4 p-4">
+      <Skeleton className="h-full w-60" />
+      <Skeleton className="h-full flex-1" />
+    </div>
+  );
+}
+
 export function FirstRunOnboardingStartupGate({
   children,
   suppressSurface = false,
   deferSurface = false,
+  cover = <DefaultStartupCover />,
 }: {
   children: React.ReactNode;
   suppressSurface?: boolean;
   /** Another startup operation owns onboarding until it settles. */
   deferSurface?: boolean;
+  /** Fills the screen while first run is possible but not yet on screen. */
+  cover?: React.ReactNode;
 }) {
   const t = useT();
   const inheritedInteractionBlock = useStartupInteractionBlocked();
@@ -138,14 +152,42 @@ export function FirstRunOnboardingStartupGate({
     };
   }, [retryNumber, shouldResolve, preloading]);
 
+  useEffect(() => {
+    if (decision === "ineligible") clearFirstRunFirstPaint();
+  }, [decision]);
+
+  // A deferral that starts once onboarding is on screen must not unmount it:
+  // that drops the user's answers and shows the app between two dialogs.
+  const [surfaceShown, setSurfaceShown] = useState(false);
   const ownsSurface =
-    !suppressSurface && !deferSurface && decision === "eligible";
+    !suppressSurface &&
+    decision === "eligible" &&
+    (!deferSurface || surfaceShown);
+  useEffect(() => {
+    if (ownsSurface) setSurfaceShown(true);
+  }, [ownsSurface]);
   const gateOwnsSurface =
     deferSurface || (!suppressSurface && decision !== "ineligible");
+  // Until first run is ruled out, the app must not paint: a frame of it
+  // before (or between) onboarding screens reads as a flash of the home.
+  const coversApp =
+    !suppressSurface &&
+    !ownsSurface &&
+    (decision === "pending" || decision === "eligible");
 
-  // Deferral only reserves onboarding ownership. The operation deferring it
-  // owns any cover; unknown eligibility must not disable unrelated app content.
-  const appIsInert = gateOwnsSurface && !deferSurface;
+  // Deferral alone does not block the app: an ineligible user keeps using it
+  // while another startup operation settles.
+  const appIsInert =
+    coversApp || ownsSurface || (gateOwnsSurface && !deferSurface);
+  const coverElement = (
+    <div
+      aria-busy="true"
+      data-first-run-cover="true"
+      className="fixed inset-0 z-[100] bg-background"
+    >
+      {cover}
+    </div>
+  );
 
   return (
     <FirstRunOnboardingGateContext.Provider value={gateOwnsSurface}>
@@ -179,8 +221,9 @@ export function FirstRunOnboardingStartupGate({
             </Button>
           </div>
         )}
+        {coversApp && coverElement}
         {ownsSurface && (
-          <Suspense fallback={null}>
+          <Suspense fallback={coverElement}>
             <FirstRunOnboarding initialFirstRun />
           </Suspense>
         )}

package/src/app/providers/AppProviders.tsx

@@ -9,6 +9,7 @@ import {
   AgentNativeI18nProvider,
   type AgentNativeI18nProviderProps,
 } from "@agent-native/core/client/i18n";
+import { isFirstRunOnboardingEnabled } from "@agent-native/core/client/onboarding/first-run-enabled";
 import { AgentNativeRouteWarmup } from "@agent-native/core/client/route-warmup";
 import {
   EMBEDDED_THEME_CHANGE_EVENT,
@@ -39,6 +40,7 @@ import {
   McpApprovalReviewGate,
   McpApprovalReviewSkeleton,
 } from "../mcp-approval/McpApprovalReview.js";
+import { getFirstRunFirstPaintScriptBody } from "../onboarding/first-run-first-paint.js";
 import { FirstRunOnboardingStartupGate } from "../onboarding/first-run-startup-gate.js";
 import {
   AppShellSkeleton,
@@ -158,6 +160,17 @@ function McpAppWidgetBootScript() {
   );
 }
 
+// Before the server-rendered skeleton paints, so a first-paint home never
+// shows to someone about to see the role question.
+function FirstRunFirstPaintScript() {
+  return (
+    <script
+      data-agent-native-first-run-first-paint="1"
+      dangerouslySetInnerHTML={{ __html: getFirstRunFirstPaintScriptBody() }}
+    />
+  );
+}
+
 function EarlySessionBootstrapScript() {
   const sessionPath = agentNativePath("/_agent-native/auth/session");
   // The document handler starts this read again from the top of <head>, where
@@ -653,12 +666,14 @@ export function AppProviders({
             <BuilderSignupStartupGate
               experimentId={builderSignupExperiment}
               suppressSurface={skipFirstRunOnboarding}
+              cover={fallback}
             >
               {children}
             </BuilderSignupStartupGate>
           ) : (
             <FirstRunOnboardingStartupGate
               suppressSurface={skipFirstRunOnboarding}
+              cover={fallback}
             >
               {children}
             </FirstRunOnboardingStartupGate>
@@ -697,6 +712,9 @@ export function AppProviders({
         <>
           <EarlySessionBootstrapScript />
           <EarlyBetaRedirectScript />
+          {isFirstRunOnboardingEnabled() && !skipFirstRunOnboarding ? (
+            <FirstRunFirstPaintScript />
+          ) : null}
         </>
       )}
       <ClientOnly fallback={fallback}>

package/src/app/providers/BuilderSignupActivation.tsx

@@ -218,7 +218,8 @@ export function BuilderSignupActivationCover({
         {children}
       </div>
       {activating ? (
-        <div className="fixed inset-0 z-50 flex gap-4 bg-background p-4">
+        // Above the first-run gate's cover, which waits under this one.
+        <div className="fixed inset-0 z-[110] flex gap-4 bg-background p-4">
           <span role="status" className="sr-only">
             {t("agentChat.common.loading")}
           </span>
@@ -239,7 +240,9 @@ export function BuilderSignupActivationCover({
       ) : statusError ? (
         <div
           role="alert"
-          className="fixed bottom-4 right-4 z-50 flex max-w-sm flex-col items-start gap-3 rounded-lg border bg-background p-4 shadow-lg"
+          // Above the first-run gate's cover, which stays up while an unknown
+          // eligibility defers onboarding.
+          className="fixed bottom-4 right-4 z-[110] flex max-w-sm flex-col items-start gap-3 rounded-lg border bg-background p-4 shadow-lg"
         >
           {retryContent}
         </div>
@@ -251,10 +254,12 @@ export function BuilderSignupActivationCover({
 export function BuilderSignupStartupGate({
   experimentId,
   suppressSurface,
+  cover,
   children,
 }: {
   experimentId?: string;
   suppressSurface: boolean;
+  cover?: ReactNode;
   children: ReactNode;
 }) {
   const { session } = useSession();
@@ -274,6 +279,7 @@ export function BuilderSignupStartupGate({
       <FirstRunOnboardingStartupGate
         suppressSurface={suppressSurface}
         deferSurface={resolving || activating}
+        cover={cover}
       >
         {children}
       </FirstRunOnboardingStartupGate>