@tomako/tools-runtime 0.1.0

package/src/features/tools/social-listening-research-report/widget/social-listening-research-report.tsx

@@ -0,0 +1,303 @@
+"use client";
+import { useLegacyLlmTaskWatch } from "../../../../components/tools/engine/use-legacy-llm-task";
+import { Button } from "@tomako/ui/button";
+import { Field, Input, Textarea } from "@tomako/ui/input";
+import { NativeSelect, NativeSelectOption } from "@tomako/ui/native-select";
+import { useLocale, useTranslations } from "../../../../i18n/client";
+import type { AppLocale } from "../../../../i18n/locale";
+import {
+    socialListeningResearchReportInputSchema,
+    type SocialListeningResearchReportResult,
+} from "../../../../lib/tools/social-listening-research-report-schema";
+import {
+    fetchSocialListeningResearchReportResult,
+    fetchSocialListeningResearchReportTask,
+    submitSocialListeningResearchReport,
+    type LlmTaskWatchPollOutcome,
+} from "../../../../host/client";
+import { Loader2 } from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { GRACE_WINDOW_MS, POLL_INTERVAL_MS, PROGRESS_INTERVAL_MS } from "./constants";
+import { EmptyPanel, ErrorPanel, RunningPanel } from "./preview-panels";
+import { ResearchReport } from "./result-shell";
+import type { ErrorCategory, Platforms, ProgressItem, WidgetState } from "./types";
+
+export function SocialListeningResearchReport() {
+  const t = useTranslations("toolsPages.socialListeningResearchReport.widget");
+  const locale = useLocale() as AppLocale;
+
+  const [researchQuestion, setResearchQuestion] = useState("");
+  const [platforms, setPlatforms] = useState<Platforms>("reddit_x");
+  const [audience, setAudience] = useState("");
+  const [market, setMarket] = useState("");
+  const [fieldError, setFieldError] = useState<string | null>(null);
+  const [state, setState] = useState<WidgetState>({ phase: "idle" });
+  const [progressItems, setProgressItems] = useState<ProgressItem[]>([]);
+
+  const resultRef = useRef<HTMLDivElement | null>(null);
+  const cancelledRef = useRef(false);
+  const progressTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const progressStepIndexRef = useRef(0);
+  const settledRef = useRef(false);
+  const currentPartialRef = useRef<SocialListeningResearchReportResult | undefined>(undefined);
+  const taskWatch = useLegacyLlmTaskWatch<SocialListeningResearchReportResult>();
+  const progressMessages = useMemo(() => t.raw("progressSteps") as string[], [t]);
+
+  function cleanup() {
+    taskWatch.stop();
+    if (progressTimerRef.current) clearInterval(progressTimerRef.current);
+    progressTimerRef.current = null;
+  }
+
+  function pushProgressStep(text: string) {
+    setProgressItems((items) => [
+      ...items.slice(-5),
+      { id: `${Date.now()}-${items.length}`, text },
+    ]);
+  }
+
+  function startProgressTicker() {
+    setProgressItems([]);
+    progressStepIndexRef.current = 0;
+    if (progressMessages[0]) pushProgressStep(progressMessages[0]);
+    progressTimerRef.current = setInterval(() => {
+      progressStepIndexRef.current = Math.min(
+        progressStepIndexRef.current + 1,
+        progressMessages.length - 1,
+      );
+      const nextStep = progressMessages[progressStepIndexRef.current];
+      if (nextStep) pushProgressStep(nextStep);
+      if (progressStepIndexRef.current >= progressMessages.length - 1) {
+        if (progressTimerRef.current) clearInterval(progressTimerRef.current);
+        progressTimerRef.current = null;
+      }
+    }, PROGRESS_INTERVAL_MS);
+  }
+
+  useEffect(() => {
+    return () => {
+      cancelledRef.current = true;
+      taskWatch.stop();
+    };
+  }, [taskWatch]);
+
+  function updatePartial(data: SocialListeningResearchReportResult) {
+    if (cancelledRef.current || settledRef.current) return;
+    currentPartialRef.current = data;
+    setState((current) => {
+      if (current.phase === "running") {
+        return { ...current, partial: data };
+      }
+      return { phase: "running", status: "AWAITING_RESULT", partial: data };
+    });
+  }
+
+  function finishDone(data: SocialListeningResearchReportResult, taskId: string) {
+    if (cancelledRef.current || settledRef.current) return;
+    settledRef.current = true;
+    cleanup();
+    setState({ phase: "done", data, taskId });
+  }
+
+  function finishError(category: ErrorCategory) {
+    if (cancelledRef.current || settledRef.current) return;
+    settledRef.current = true;
+    cleanup();
+    setState({ phase: "error", category, partial: currentPartialRef.current });
+  }
+
+  async function pollOnce(taskId: string): Promise<LlmTaskWatchPollOutcome> {
+    const [task, result] = await Promise.all([
+      fetchSocialListeningResearchReportTask(taskId),
+      fetchSocialListeningResearchReportResult(taskId),
+    ]);
+    if (cancelledRef.current || settledRef.current) {
+      return { settled: true as const, kind: "error" as const, category: "task" as const };
+    }
+    if (result.data) {
+      if (result.data.reportStatus === "final") {
+        return { settled: true as const, kind: "success" as const, data: result.data };
+      }
+      updatePartial(result.data);
+      setState((current) => ({
+        phase: "running",
+        status: task.status,
+        partial: current.phase === "running" ? current.partial : currentPartialRef.current,
+      }));
+      return { settled: false as const, pendingWriteback: true as const };
+    }
+    if (result.status === "RESULT_INVALID") {
+      return { settled: true as const, kind: "error" as const, category: "schema" as const };
+    }
+    if (task.status === "FAILED") {
+      return { settled: true as const, kind: "error" as const, category: "task" as const };
+    }
+    setState((current) => ({
+      phase: "running",
+      status: task.status,
+      partial: current.phase === "running" ? current.partial : currentPartialRef.current,
+    }));
+    return { settled: false as const };
+  }
+
+  async function startResearch() {
+    const parsed = socialListeningResearchReportInputSchema.safeParse({
+      researchQuestion,
+      platforms,
+      audience: audience || undefined,
+      market: market || undefined,
+    });
+    if (!parsed.success) {
+      setFieldError(t("errors.invalid"));
+      setState({ phase: "error", category: "invalid" });
+      return;
+    }
+
+    setFieldError(null);
+    currentPartialRef.current = undefined;
+    cancelledRef.current = false;
+    settledRef.current = false;
+    cleanup();
+    setState({ phase: "submitting" });
+    startProgressTicker();
+    resultRef.current?.scrollIntoView({ behavior: "smooth", block: "center" });
+
+    let taskId: string;
+    try {
+      const submitted = await submitSocialListeningResearchReport(parsed.data, locale);
+      taskId = submitted.taskId;
+    } catch {
+      finishError("submit");
+      return;
+    }
+
+    if (cancelledRef.current) return;
+    setState({ phase: "running", status: "PENDING" });
+    taskWatch.start(
+      taskId,
+      pollOnce,
+      {
+        onStatus: (status) => {
+          if (!cancelledRef.current && !settledRef.current) {
+            setState((current) => ({
+              phase: "running",
+              status,
+              partial: current.phase === "running" ? current.partial : currentPartialRef.current,
+            }));
+          }
+        },
+        onSuccess: (data) => {
+          pushProgressStep(t("progressResultReady"));
+          finishDone(data, taskId);
+        },
+        onError: (category) => finishError(category === "timeout" ? "timeout" : category),
+      },
+      { pollIntervalMs: POLL_INTERVAL_MS, graceWindowMs: GRACE_WINDOW_MS },
+    );
+  }
+
+  function reset() {
+    cancelledRef.current = false;
+    settledRef.current = false;
+    currentPartialRef.current = undefined;
+    cleanup();
+    setProgressItems([]);
+    setState({ phase: "idle" });
+  }
+
+  const busy = state.phase === "submitting" || state.phase === "running";
+  const partial =
+    state.phase === "running" || state.phase === "error" ? state.partial : undefined;
+  const statusLabel =
+    state.phase === "running"
+      ? t.has(`status.${state.status}`)
+        ? t(`status.${state.status}`)
+        : t("status.default")
+      : "";
+
+  return (
+    <div className="grid gap-8">
+      <section className="rounded-[1.5rem] border border-[#E2E6EC] bg-white p-5 shadow-[0_14px_38px_rgba(17,17,17,0.05)] md:p-6">
+        <Field label={t("questionLabel")}>
+          <Textarea
+            rows={5}
+            placeholder={t("questionPlaceholder")}
+            value={researchQuestion}
+            onChange={(event) => setResearchQuestion(event.target.value)}
+            disabled={busy}
+            aria-invalid={fieldError ? true : undefined}
+          />
+        </Field>
+        {fieldError ? (
+          <p className="mt-1.5 text-xs font-medium text-[#B91C1C]">{fieldError}</p>
+        ) : null}
+        <div className="mt-4 grid gap-4 sm:grid-cols-3">
+          <Field label={t("platformsLabel")}>
+            <NativeSelect
+              className="w-full bg-white"
+              value={platforms}
+              onChange={(event) => setPlatforms(event.target.value as Platforms)}
+              disabled={busy}
+            >
+              <NativeSelectOption value="reddit_x">{t("platforms.redditX")}</NativeSelectOption>
+              <NativeSelectOption value="reddit">{t("platforms.reddit")}</NativeSelectOption>
+              <NativeSelectOption value="x">{t("platforms.x")}</NativeSelectOption>
+              <NativeSelectOption value="all">{t("platforms.all")}</NativeSelectOption>
+            </NativeSelect>
+          </Field>
+          <Field label={t("audienceLabel")}>
+            <Input
+              placeholder={t("audiencePlaceholder")}
+              value={audience}
+              onChange={(event) => setAudience(event.target.value)}
+              disabled={busy}
+            />
+          </Field>
+          <Field label={t("marketLabel")}>
+            <Input
+              placeholder={t("marketPlaceholder")}
+              value={market}
+              onChange={(event) => setMarket(event.target.value)}
+              disabled={busy}
+            />
+          </Field>
+        </div>
+        <Button className="mt-5 w-full" onClick={() => void startResearch()} disabled={busy}>
+          {busy ? (
+            <>
+              <Loader2 className="size-4 animate-spin" aria-hidden />
+              {state.phase === "submitting" ? t("submitting") : t("running")}
+            </>
+          ) : (
+            t("submit")
+          )}
+        </Button>
+        <p className="mt-3 text-xs leading-5 text-[#777777]">{t("inputHint")}</p>
+      </section>
+
+      <section ref={resultRef} className="min-h-[30rem]">
+        {state.phase === "idle" ? <EmptyPanel title={t("emptyTitle")} hint={t("emptyHint")} /> : null}
+        {busy ? (
+          <RunningPanel
+            title={t("runningTitle")}
+            hint={t("runningHint")}
+            statusLabel={statusLabel}
+            progressItems={progressItems}
+            progressTitle={t("progressTitle")}
+          />
+        ) : null}
+        {partial ? <ResearchReport data={partial} t={t} variant="partial" onReset={reset} /> : null}
+        {state.phase === "error" ? (
+          <ErrorPanel
+            message={t(`errors.${state.category}`)}
+            retryLabel={t("retry")}
+            onRetry={() => void startResearch()}
+          />
+        ) : null}
+        {state.phase === "done" ? (
+          <ResearchReport data={state.data} taskId={state.taskId} t={t} variant="final" onReset={reset} />
+        ) : null}
+      </section>
+    </div>
+  );
+}

package/src/features/tools/social-listening-research-report/widget/types.ts

@@ -0,0 +1,15 @@
+import type { SocialListeningResearchReportResult } from "../../../../lib/tools/social-listening-research-report-schema";
+
+export type ErrorCategory = "submit" | "task" | "timeout" | "schema" | "invalid";
+export type Platforms = "reddit_x" | "reddit" | "x" | "all";
+export type WidgetState =
+  | { phase: "idle" }
+  | { phase: "submitting" }
+  | { phase: "running"; status: string; partial?: SocialListeningResearchReportResult }
+  | { phase: "done"; data: SocialListeningResearchReportResult; taskId: string }
+  | { phase: "error"; category: ErrorCategory; partial?: SocialListeningResearchReportResult };
+
+export type ProgressItem = {
+  id: string;
+  text: string;
+};

package/src/features/tools/social-platform-asset-adapter/social-platform-asset-adapter.container.tsx

@@ -0,0 +1,123 @@
+import { createToolGuideTranslator } from "../shared/tool-message-translator";
+
+import { socialPlatformAssetAdapterImages } from "../../../constants/tool-assets";
+import { SocialPlatformAssetAdapter } from "./widget";
+
+import {
+    ToolCardGrid,
+    ToolFaqSection,
+    ToolPlainTextGrid,
+    ToolSection,
+    type ToolFaqItem,
+    type ToolTextCard,
+} from "../shared/tool-content-sections";
+import { ToolCta } from "../shared/tool-cta";
+import {
+    ToolGuideSection,
+    ToolImageVisual,
+    ToolWorkspaceSection,
+} from "../shared/tool-guide-section";
+import { ToolPageShell } from "../shared/tool-page-shell";
+import type { ToolPageProps } from "../types";
+
+export async function SocialPlatformAssetAdapterContainer({
+  locale,
+  spec,
+}: ToolPageProps) {
+  const t = await createToolGuideTranslator(locale, "toolsPages.socialPlatformAssetAdapter.guide");
+  const outputItems = t.raw("outputItems") as readonly ToolTextCard[];
+  const supportItems = t.raw("supportItems") as readonly string[];
+  const boundaryItems = t.raw("boundaryItems") as readonly string[];
+  const failureItems = t.raw("failureItems") as readonly string[];
+  const resultUseItems = t.raw("resultUseItems") as readonly string[];
+  const whyTomakoItems = t.raw("whyTomakoItems") as readonly ToolTextCard[];
+  const standardItems = t.raw("standardItems") as readonly string[];
+  const faqItems = t.raw("faqItems") as readonly ToolFaqItem[];
+
+  return (
+    <ToolPageShell
+      heroBackgroundAlt={t("heroVisualAlt")}
+      heroBackgroundImage={socialPlatformAssetAdapterImages.hero}
+      heroVariant="immersive"
+      locale={locale}
+      spec={spec}
+    >
+      <ToolWorkspaceSection
+        badge={t("workspaceBadge")}
+        heading={t("workspaceHeading")}
+        hint={t("workspaceHint")}
+      >
+        <SocialPlatformAssetAdapter />
+      </ToolWorkspaceSection>
+      <ToolSection heading={t("outputs")}>
+        <ToolCardGrid items={outputItems} columns="four" />
+      </ToolSection>
+      <ToolGuideSection
+        heading={t("supportHeading")}
+        visual={
+          <ToolImageVisual
+            alt={t("supportVisualAlt")}
+            src={socialPlatformAssetAdapterImages.value}
+            wide
+          />
+        }
+      >
+        <ToolPlainTextGrid items={supportItems} />
+      </ToolGuideSection>
+      <ToolGuideSection
+        heading={t("boundaryHeading")}
+        reverse
+        visual={
+          <ToolImageVisual
+            alt={t("boundaryVisualAlt")}
+            src={socialPlatformAssetAdapterImages.support}
+            wide
+          />
+        }
+      >
+        <ToolPlainTextGrid items={boundaryItems} />
+        <h3 className="mt-8 text-xl font-semibold text-[#111111]">
+          {t("failureHeading")}
+        </h3>
+        <ToolPlainTextGrid items={failureItems} />
+      </ToolGuideSection>
+      <ToolGuideSection
+        heading={t("resultUseHeading")}
+        visual={
+          <ToolImageVisual
+            alt={t("resultUseVisualAlt")}
+            src={socialPlatformAssetAdapterImages.useCase}
+            wide
+          />
+        }
+      >
+        <ToolPlainTextGrid items={resultUseItems} />
+      </ToolGuideSection>
+      <ToolSection heading={t("whyTomakoHeading")}>
+        <ToolCardGrid items={whyTomakoItems} columns="four" />
+      </ToolSection>
+      <ToolGuideSection
+        heading={t("standardHeading")}
+        reverse
+        visual={
+          <ToolImageVisual
+            alt={t("standardVisualAlt")}
+            src={socialPlatformAssetAdapterImages.workspace}
+            wide
+          />
+        }
+      >
+        <ToolPlainTextGrid items={standardItems} />
+      </ToolGuideSection>
+      <ToolFaqSection heading={t("faq")} items={faqItems} />
+      <ToolCta
+        hint={t("ctaHint")}
+        primary={{
+          href: "/tools/social-media-profile-generator",
+          label: t("ctaPrimary"),
+        }}
+        secondary={{ href: "/tools/email-template-generator", label: t("ctaSecondary") }}
+      />
+    </ToolPageShell>
+  );
+}

package/src/features/tools/social-platform-asset-adapter/social-platform-asset-adapter.spec.ts

@@ -0,0 +1,15 @@
+import type { ToolSpec } from "../types";
+
+export const socialPlatformAssetAdapterSpec: ToolSpec = {
+  slug: "social-platform-asset-adapter",
+  toolType: "generator",
+  riskLevel: "medium",
+  seo: {
+    "publishedAt": "2026-06-30",
+    "updatedAt": "2026-06-30",
+    "readingTime": "8 min",
+    "featured": false,
+    "ogImage": "/tools/social-platform-asset-adapter-hero-generated.webp"
+  },
+  widget: {"id":"social-platform-asset-adapter","mode":"custom"},
+};

package/src/features/tools/social-platform-asset-adapter/widget/constants.ts

@@ -0,0 +1,43 @@
+import type {
+    SocialAssetGoal,
+    SocialAssetPlatform,
+    SocialAssetTone,
+} from "../../../../lib/tools/social-platform-asset-adapter-schema";
+
+export const platforms: SocialAssetPlatform[] = [
+  "x",
+  "linkedin",
+  "instagram",
+  "tiktok",
+  "youtubeShorts",
+  "facebook",
+];
+
+export const goals: SocialAssetGoal[] = [
+  "launch",
+  "education",
+  "community",
+  "leadGeneration",
+  "retention",
+];
+
+export const tones: SocialAssetTone[] = ["clear", "bold", "warm", "expert", "playful"];
+
+export const designAssetTypes = ["image/png", "image/jpeg", "image/webp"] as const;
+export const designAssetAccept = designAssetTypes.join(",");
+export const maxDesignAssetCount = 3;
+export const maxOriginalDesignAssetBytes = 3 * 1024 * 1024;
+export const maxDesignAssetDataUrlLength = 700_000;
+export const maxDesignAssetEdge = 960;
+
+export const platformImageSpecs: Record<
+  SocialAssetPlatform,
+  { width: number; height: number; ratio: string }
+> = {
+  x: { width: 1600, height: 900, ratio: "16:9" },
+  linkedin: { width: 1200, height: 627, ratio: "1.91:1" },
+  instagram: { width: 1080, height: 1350, ratio: "4:5" },
+  tiktok: { width: 1080, height: 1920, ratio: "9:16" },
+  youtubeShorts: { width: 1080, height: 1920, ratio: "9:16" },
+  facebook: { width: 1200, height: 630, ratio: "1.91:1" },
+};