@tomako/tools-runtime 0.1.4 → 0.1.6

package/src/features/tools/app-store-screenshot-generator/widget/generation.test.ts

@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { registerToolsRuntimeHostClient } from "../../../../host/client";
+import type { AppStoreScreenshotAgentResult } from "../../../../lib/tools/app-store-screenshot-generator-schema";
+
+import { waitForAgentResult } from "./generation";
+
+const prompt = "Generate a cohesive app store screenshot set from the supplied product UI. ".repeat(4);
+
+function agentResult(
+  assetCount: number,
+  reportStatus: AppStoreScreenshotAgentResult["reportStatus"] = "partial",
+): AppStoreScreenshotAgentResult {
+  return {
+    promptId: "tools.app-store-screenshot-generator.agent",
+    promptVersion: "2026-07-03.2",
+    reportStatus,
+    summary: `${assetCount} screenshots planned`,
+    prompt,
+    assets: Array.from({ length: assetCount }, (_, index) => ({
+      id: `asset-${index + 1}`,
+      platform: "apple" as const,
+      format: "iphone" as const,
+      title: `Screenshot ${index + 1}`,
+      width: 1290,
+      height: 2796,
+      slot: index + 1,
+      setSize: 10,
+      imageTaskId: `image-task-${index + 1}`,
+    })),
+    failures: [],
+    totalAssets: 10,
+    completedAssets: assetCount,
+    failedAssets: 0,
+  };
+}
+
+function registerTaskSequence(
+  responses: Array<{
+    status: string;
+    data: AppStoreScreenshotAgentResult | null;
+    errorCode?: "task_failed";
+    error?: string;
+  }>,
+) {
+  let calls = 0;
+  registerToolsRuntimeHostClient({
+    fetchAppStoreScreenshotSetTask: async () => {
+      const response = responses[Math.min(calls, responses.length - 1)];
+      calls += 1;
+      return response;
+    },
+  });
+  return () => calls;
+}
+
+const fastPolling = { pollIntervalMs: 0, timeoutMs: 1_000 };
+
+describe("waitForAgentResult", () => {
+  it("keeps following after the first partial batch until the expected asset count arrives", async () => {
+    const firstBatch = agentResult(4);
+    const completeBatch = agentResult(10);
+    const calls = registerTaskSequence([
+      { status: "SUCCEEDED", data: firstBatch },
+      { status: "SUCCEEDED", data: completeBatch },
+    ]);
+    const progressCounts: number[] = [];
+
+    const result = await waitForAgentResult(
+      "task-expected-count",
+      (progress) => progressCounts.push(progress.assets.length),
+      10,
+      fastPolling,
+    );
+
+    assert.equal(calls(), 2);
+    assert.deepEqual(progressCounts, [4, 10]);
+    assert.equal(result.assets.length, 10);
+    assert.equal(result.reportStatus, "partial");
+  });
+
+  it("stops on an explicit final snapshot even when it has fewer assets than expected", async () => {
+    const firstBatch = agentResult(4);
+    const finalBatch = agentResult(4, "final");
+    const calls = registerTaskSequence([
+      { status: "SUCCEEDED", data: firstBatch },
+      { status: "SUCCEEDED", data: finalBatch },
+    ]);
+
+    const result = await waitForAgentResult(
+      "task-final",
+      () => undefined,
+      10,
+      fastPolling,
+    );
+
+    assert.equal(calls(), 2);
+    assert.equal(result.reportStatus, "final");
+    assert.equal(result.assets.length, 4);
+  });
+
+  it("returns the last usable partial snapshot when the task fails terminally", async () => {
+    const firstBatch = agentResult(4);
+    const calls = registerTaskSequence([
+      { status: "RUNNING", data: firstBatch },
+      {
+        status: "FAILED",
+        data: null,
+        errorCode: "task_failed",
+        error: "background follower failed",
+      },
+    ]);
+
+    const result = await waitForAgentResult(
+      "task-terminal",
+      () => undefined,
+      10,
+      fastPolling,
+    );
+
+    assert.equal(calls(), 2);
+    assert.equal(result.reportStatus, "partial");
+    assert.equal(result.assets.length, 4);
+  });
+});

package/src/features/tools/app-store-screenshot-generator/widget/generation.ts

@@ -33,16 +33,30 @@ export async function generateStoreAssets(
   locale: AppLocale,
   onProgress: (progress: GeneratedStoreAssetsResult) => void,
   onPlanning: () => void,
+  options: {
+    taskId?: string;
+    startedAtMs?: number;
+    onTaskSubmitted?: (taskId: string, startedAtMs: number) => void;
+  } = {},
 ): Promise<GeneratedStoreAssetsResult> {
-  const submitted = await submitAppStoreScreenshotSet(input, locale);
+  const submitted = options.taskId
+    ? { taskId: options.taskId }
+    : await submitAppStoreScreenshotSet(input, locale);
+  const startedAtMs = options.startedAtMs ?? Date.now();
+  if (!options.taskId) options.onTaskSubmitted?.(submitted.taskId, startedAtMs);
   onPlanning();
-  const agentResult = await waitForAgentResult(submitted.taskId, (partialResult) => {
-    try {
-      onProgress(buildGeneratedStoreAssetsResult(partialResult, { allowMissingImageUrl: false }));
-    } catch {
-      // Ignore non-renderable intermediate snapshots and keep waiting for a usable result.
-    }
-  });
+  const agentResult = await waitForAgentResult(
+    submitted.taskId,
+    (partialResult) => {
+      try {
+        onProgress(buildGeneratedStoreAssetsResult(partialResult, { allowMissingImageUrl: false }));
+      } catch {
+        // Ignore non-renderable intermediate snapshots and keep waiting for a usable result.
+      }
+    },
+    expectedAssetCount(input),
+    { startedAtMs },
+  );
   return resolveGeneratedStoreAssetsResult(agentResult, input, onProgress);
 }
 
@@ -247,8 +261,17 @@ export function buildGeneratedStoreAssetsResult(
 export async function waitForAgentResult(
   taskId: string,
   onProgress: (result: AppStoreScreenshotAgentResult) => void,
+  expectedCount: number,
+  options: {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    startedAtMs?: number;
+  } = {},
 ) {
-  const deadline = Date.now() + AGENT_RESULT_TIMEOUT_MS;
+  const deadline =
+    (options.startedAtMs ?? Date.now()) +
+    (options.timeoutMs ?? AGENT_RESULT_TIMEOUT_MS);
+  const pollIntervalMs = options.pollIntervalMs ?? AGENT_RESULT_POLL_INTERVAL_MS;
   let lastResult: AppStoreScreenshotAgentResult | null = null;
   let lastSignature = "";
 
@@ -261,7 +284,13 @@ export async function waitForAgentResult(
         lastSignature = signature;
         onProgress(task.data);
       }
-      if (task.data.reportStatus === "final" || hasResolvableAgentAssets(task.data)) {
+      // submit-only can finish the LLM task after writing the first partial batch while
+      // its background follower continues to append screenshot tasks. Do not treat the
+      // task's SUCCEEDED status or one resolvable asset as the completed image set.
+      if (
+        task.data.reportStatus === "final" ||
+        hasExpectedAgentAssetCount(task.data, expectedCount)
+      ) {
         return task.data;
       }
     }
@@ -269,15 +298,24 @@ export async function waitForAgentResult(
       if (lastResult) return lastResult;
       throw new AppStoreAgentGenerationError(task.errorCode, task.error);
     }
-    await wait(AGENT_RESULT_POLL_INTERVAL_MS);
+    await wait(pollIntervalMs);
   }
 
   if (lastResult) return lastResult;
   throw new AppStoreAgentGenerationError("task_failed", "Agent result timed out.");
 }
 
-export function hasResolvableAgentAssets(result: AppStoreScreenshotAgentResult) {
-  return result.assets.some((asset) => Boolean(asset.imageUrl || asset.imageTaskId));
+export function hasExpectedAgentAssetCount(
+  result: AppStoreScreenshotAgentResult,
+  expectedCount: number,
+) {
+  const settledAssetIds = new Set([
+    ...result.assets
+      .filter((asset) => Boolean(asset.imageUrl || asset.imageTaskId || asset.errorMessage))
+      .map((asset) => asset.id),
+    ...result.failures.map((failure) => failure.id),
+  ]);
+  return settledAssetIds.size >= clampAssetCount(expectedCount);
 }
 
 export function progressSignature(result: AppStoreScreenshotAgentResult) {
@@ -459,7 +497,7 @@ export function blobToImage(blob: Blob): Promise<HTMLImageElement> {
 }
 
 export function wait(ms: number): Promise<void> {
-  return new Promise((resolve) => window.setTimeout(resolve, ms));
+  return new Promise((resolve) => globalThis.setTimeout(resolve, ms));
 }
 
 export function formatGenerationError(

package/src/features/tools/cold-start-channel-selector/cold-start-channel-selector.spec.ts

@@ -6,7 +6,7 @@ export const coldStartChannelSelectorSpec: ToolSpec = {
   riskLevel: "medium",
   seo: {
     publishedAt: "2026-06-29",
-    updatedAt: "2026-08-03",
+    updatedAt: "2026-08-30",
     readingTime: "7 min",
     featured: false,
     ogImage: "/tools/cold-start-channel-selector-hero.webp",

package/src/features/tools/cold-start-channel-selector/widget/cold-start-channel-selector.tsx

@@ -28,6 +28,11 @@ import {
 } from "../../../../host/client";
 
 import { useLegacyLlmTaskWatch } from "../../../../components/tools/engine/use-legacy-llm-task";
+import {
+  clearToolTaskRecovery,
+  persistToolTaskRecovery,
+  readToolTaskRecovery,
+} from "../../../../components/tools/engine/task-recovery";
 import { GRACE_WINDOW_MS, initialInput } from "./constants";
 import { SelectField } from "./form-controls";
 import { EmptyPreview, RunningPanel } from "./preview-panels";
@@ -38,6 +43,8 @@ type FormFieldErrors = Partial<
   Record<"productUrl" | "productDescription", string>
 >;
 
+const RECOVERY_SLUG = "cold-start-channel-selector";
+
 export function ColdStartChannelSelector() {
   const t = useTranslations("toolsPages.coldStartChannelSelector.widget");
   const locale = useLocale() as AppLocale;
@@ -74,6 +81,22 @@ export function ColdStartChannelSelector() {
     };
   }, [taskWatch]);
 
+  useEffect(() => {
+    const recovered = readToolTaskRecovery(RECOVERY_SLUG, {
+      parseInput: (value) => {
+        const parsed = coldStartChannelSelectorInputSchema.safeParse(value);
+        return parsed.success ? parsed.data : null;
+      },
+    });
+    if (!recovered) return;
+    setInput(recovered.input);
+    cancelledRef.current = false;
+    settledRef.current = false;
+    watchAnalysis(recovered.taskId, recovered.startedAtMs);
+    // Restore only once for this mounted tool route.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [taskWatch]);
+
   function updateInput<K extends keyof ColdStartChannelSelectorInput>(
     key: K,
     value: ColdStartChannelSelectorInput[K],
@@ -117,6 +140,24 @@ export function ColdStartChannelSelector() {
     return { settled: false as const };
   }
 
+  function watchAnalysis(taskId: string, startedAtMs?: number) {
+    setState({ phase: "running", status: startedAtMs ? "RESTORING" : "PENDING" });
+    taskWatch.start(
+      taskId,
+      pollOnce,
+      {
+        onStatus: (status) => {
+          if (!cancelledRef.current && !settledRef.current) {
+            setState({ phase: "running", status });
+          }
+        },
+        onSuccess: (data) => finishDone(data),
+        onError: (category) => finishError(category === "timeout" ? "timeout" : category),
+      },
+      { graceWindowMs: GRACE_WINDOW_MS, startedAtMs },
+    );
+  }
+
   async function startAnalysis() {
     const parsed = coldStartChannelSelectorInputSchema.safeParse(input);
     if (!parsed.success) {
@@ -159,28 +200,16 @@ export function ColdStartChannelSelector() {
     }
 
     if (cancelledRef.current) return;
-    setState({ phase: "running", status: "PENDING" });
-
-    taskWatch.start(
-      taskId,
-      pollOnce,
-      {
-        onStatus: (status) => {
-          if (!cancelledRef.current && !settledRef.current) {
-            setState({ phase: "running", status });
-          }
-        },
-        onSuccess: (data) => finishDone(data),
-        onError: (category) => finishError(category === "timeout" ? "timeout" : category),
-      },
-      { graceWindowMs: GRACE_WINDOW_MS },
-    );
+    const startedAtMs = Date.now();
+    persistToolTaskRecovery(RECOVERY_SLUG, taskId, parsed.data, startedAtMs);
+    watchAnalysis(taskId, startedAtMs);
   }
 
   function resetResult() {
     cancelledRef.current = false;
     settledRef.current = false;
     cleanup();
+    clearToolTaskRecovery(RECOVERY_SLUG);
     setState({ phase: "idle" });
   }
 

package/src/features/tools/competitor-analysis/competitor-analysis.container.tsx

@@ -1,4 +1,4 @@
-import { ImageOff } from "lucide-react";
+import Image from "next/image";
 import { createToolGuideTranslator } from "../shared/tool-message-translator";
 
 import { CompetitorAnalysis } from "./widget";
@@ -17,36 +17,30 @@ import { ToolWorkspaceSection } from "../shared/tool-guide-section";
 import { ToolPageShell } from "../shared/tool-page-shell";
 import type { ToolPageProps } from "../types";
 
-/**
- * Gray-white image placeholder. The agent has no image-generation capability,
- * so first-pass bitmap assets are intentionally deferred (see release notes /
- * tool brief). Swap each placeholder for a real `public/tools/competitor-analysis-*.webp`
- * when assets are produced.
- */
-function ImagePlaceholder({
+function CompetitorVisual({
+  src,
   label,
   className = "",
 }: {
+  src: string;
   label: string;
   className?: string;
 }) {
   return (
-    <div
-      role="img"
-      aria-label={label}
-      className={`flex aspect-[16/10] w-full items-center justify-center rounded-[1.5rem] border border-dashed border-[#D7DCE3] bg-[#F4F5F7] text-[#A8B0BA] ${className}`}
-    >
-      <span className="flex flex-col items-center gap-2 text-xs font-medium">
-        <ImageOff className="size-6" aria-hidden />
-        {label}
-      </span>
-    </div>
+    <figure className={`relative aspect-[16/10] w-full overflow-hidden rounded-[1.5rem] border border-[#D7DCE3] bg-[#F4F5F7] ${className}`}>
+      <Image
+        src={src}
+        alt={label}
+        fill
+        sizes="(min-width: 1024px) 560px, 100vw"
+        className="object-cover"
+      />
+    </figure>
   );
 }
 
 export async function CompetitorAnalysisContainer({ locale, spec }: ToolPageProps) {
   const t = await createToolGuideTranslator(locale, "toolsPages.competitorAnalysis.guide");
-  const sharedT = await createToolGuideTranslator(locale, "toolsPages.shared");
 
   const steps = t.raw("howToUseSteps") as readonly string[];
   const guidance = t.raw("guidanceBullets") as readonly string[];
@@ -58,13 +52,13 @@ export async function CompetitorAnalysisContainer({ locale, spec }: ToolPageProp
     <ToolPageShell
       locale={locale}
       spec={spec}
-      heroVariant="showcase"
-      heroVisual={<ImagePlaceholder label={t("visualAlt.hero")} className="max-w-4xl" />}
+      showDefaultHeader={false}
     >
       <ToolWorkspaceSection
-        heading={sharedT("toolWorkspace")}
-        hint={sharedT("toolWorkspaceHint")}
-        badge={sharedT("keywords")}
+        heading={t("workspaceHeading")}
+        hint={t("workspaceHint")}
+        badge={t("workspaceBadge")}
+        headingLevel="h1"
       >
         <CompetitorAnalysis />
       </ToolWorkspaceSection>
@@ -81,12 +75,18 @@ export async function CompetitorAnalysisContainer({ locale, spec }: ToolPageProp
             <p className="text-sm leading-6 text-[#777777]">{t("runtimeNote")}</p>
           </div>
         </div>
-        <ImagePlaceholder label={t("visualAlt.howToUse")} />
+        <CompetitorVisual
+          src="/tools/competitor-radar-how-it-works.webp"
+          label={t("visualAlt.howToUse")}
+        />
       </section>
 
       {/* Result guidance — visual-led split */}
       <section className="grid gap-8 border-t border-[#E8E4DB] py-12 md:grid-cols-[1.08fr_0.92fr] md:items-center md:py-16">
-        <ImagePlaceholder label={t("visualAlt.result")} />
+        <CompetitorVisual
+          src="/tools/competitor-radar-trust-boundary.webp"
+          label={t("visualAlt.result")}
+        />
         <div>
           <ToolSectionEyebrow tone="blue">{t("resultKicker")}</ToolSectionEyebrow>
           <h2 className="mt-3 text-3xl font-semibold leading-tight text-[#111111] md:text-4xl">
@@ -110,6 +110,11 @@ export async function CompetitorAnalysisContainer({ locale, spec }: ToolPageProp
           <p className="max-w-md text-sm leading-6 text-[#777777]">{t("useCasesIntro")}</p>
         </div>
         <ToolNumberedUseCaseGrid items={useCases} />
+        <CompetitorVisual
+          src="/tools/competitor-radar-use-cases.webp"
+          label={t("visualAlt.useCases")}
+          className="mt-8"
+        />
       </section>
 
       {/* FAQ + boundary */}

package/src/features/tools/competitor-analysis/competitor-analysis.spec.ts

@@ -6,7 +6,7 @@ export const competitorAnalysisSpec: ToolSpec = {
   riskLevel: "medium",
   seo: {
     "publishedAt": "2026-06-29",
-    "updatedAt": "2026-06-29",
+    "updatedAt": "2026-08-30",
     "readingTime": "6 min",
     "featured": false,
     "ogImage": "/tools/competitor-radar-hero.webp"

package/src/features/tools/competitor-analysis/widget/competitor-analysis.tsx

@@ -22,11 +22,18 @@ import {
 } from "../../../../host/client";
 
 import { useLegacyLlmTaskWatch } from "../../../../components/tools/engine/use-legacy-llm-task";
+import {
+  clearToolTaskRecovery,
+  persistToolTaskRecovery,
+  readToolTaskRecovery,
+} from "../../../../components/tools/engine/task-recovery";
 import { GRACE_WINDOW_MS } from "./constants";
 import { EmptyPanel, ErrorPanel, RunningPanel } from "./preview-panels";
 import { Dossier } from "./result-shell";
 import type { ErrorCategory, WidgetState } from "./types";
 
+const RECOVERY_SLUG = "competitor-analysis";
+
 export function CompetitorAnalysis() {
   const t = useTranslations("toolsPages.competitorAnalysis.widget");
   const locale = useLocale() as AppLocale;
@@ -53,6 +60,24 @@ export function CompetitorAnalysis() {
     };
   }, [taskWatch]);
 
+  useEffect(() => {
+    const recovered = readToolTaskRecovery(RECOVERY_SLUG, {
+      parseInput: (value) => {
+        const parsed = competitorAnalysisInputSchema.safeParse(value);
+        return parsed.success ? parsed.data : null;
+      },
+    });
+    if (!recovered) return;
+    setUrl(recovered.input.competitorUrl);
+    setName(recovered.input.competitorName ?? "");
+    setNotes(recovered.input.notes ?? "");
+    cancelledRef.current = false;
+    settledRef.current = false;
+    watchAnalysis(recovered.taskId, recovered.startedAtMs);
+    // Restore only once for this mounted tool route.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [taskWatch]);
+
   useEffect(() => {
     if (!activityBrief || state.phase !== "done") return;
     publishActivityArtifact(
@@ -93,6 +118,24 @@ export function CompetitorAnalysis() {
     return { settled: false as const };
   }
 
+  function watchAnalysis(taskId: string, startedAtMs?: number) {
+    setState({ phase: "running", status: startedAtMs ? "RESTORING" : "PENDING" });
+    taskWatch.start(
+      taskId,
+      pollOnce,
+      {
+        onStatus: (status) => {
+          if (!cancelledRef.current && !settledRef.current) {
+            setState({ phase: "running", status });
+          }
+        },
+        onSuccess: (data) => finishDone(data, taskId),
+        onError: (category) => finishError(category === "timeout" ? "timeout" : category),
+      },
+      { graceWindowMs: GRACE_WINDOW_MS, startedAtMs },
+    );
+  }
+
   async function startAnalysis() {
     const parsed = competitorAnalysisInputSchema.safeParse({
       competitorUrl: url,
@@ -119,28 +162,16 @@ export function CompetitorAnalysis() {
       return;
     }
     if (cancelledRef.current) return;
-    setState({ phase: "running", status: "PENDING" });
-
-    taskWatch.start(
-      taskId,
-      pollOnce,
-      {
-        onStatus: (status) => {
-          if (!cancelledRef.current && !settledRef.current) {
-            setState({ phase: "running", status });
-          }
-        },
-        onSuccess: (data) => finishDone(data, taskId),
-        onError: (category) => finishError(category === "timeout" ? "timeout" : category),
-      },
-      { graceWindowMs: GRACE_WINDOW_MS },
-    );
+    const startedAtMs = Date.now();
+    persistToolTaskRecovery(RECOVERY_SLUG, taskId, parsed.data, startedAtMs);
+    watchAnalysis(taskId, startedAtMs);
   }
 
   function reset() {
     cancelledRef.current = false;
     settledRef.current = false;
     cleanup();
+    clearToolTaskRecovery(RECOVERY_SLUG);
     setState({ phase: "idle" });
   }
 

package/src/features/tools/disclaimer-generator/disclaimer-generator.package.ts

@@ -34,15 +34,15 @@ export const disclaimerGeneratorPackage: ToolPackage = {
     riskLevel: "high",
     keywordEvidence: "docs/seo-keyword-briefs/disclaimer-generator.md",
     seo: {
-      updatedAt: "2026-07-10",
+      updatedAt: "2026-08-30",
       readingTime: "6 min",
       ogImage: "/tools/disclaimer-generator-section-primary.webp",
     },
   },
   copy: {
-    title: t("Disclaimer Generator", "免责声明生成器", "免責聲明產生器"),
+    title: t("Website Disclaimer Generator", "网站免责声明生成器", "網站免責聲明產生器"),
     description: t(
-      "Create a tailored website, affiliate, review, or professional-information disclaimer draft with placement guidance, missing facts, risk flags, and a human review checklist.",
+      "Draft a website, affiliate, review, or professional-information disclaimer with placement guidance, missing facts, risk flags, and a review checklist.",
       "根据业务和发布场景生成网站、联盟、评测或专业信息免责声明草案，并提供放置建议、缺失信息、风险提示与人工复核清单。",
       "依照業務與發布情境產生網站、聯盟、評測或專業資訊免責聲明草案，並提供放置建議、缺漏資訊、風險提示與人工複核清單。",
     ),
@@ -252,7 +252,7 @@ export const disclaimerGeneratorPackage: ToolPackage = {
   },
   page: {
     workspace: {
-      heading: t("Create a disclaimer you can review", "生成一份便于复核的免责声明", "產生一份便於複核的免責聲明"),
+      heading: t("Website disclaimer generator with review guidance", "网站免责声明生成器：草案与复核指引", "網站免責聲明產生器：草案與複核指引"),
       hint: t(
         "Describe your content and where it appears. Get a copyable draft, suggested placement, gaps to confirm, and a review checklist before you publish.",
         "描述你的内容和发布位置，获得可复制草案、建议放置位置、待确认缺口和发布前复核清单。",