@tomako/tools-runtime 0.1.0

package/src/features/tools/shared/tool-standard-landing-sections.tsx

@@ -0,0 +1,447 @@
+import type { LucideIcon } from "lucide-react";
+import type { ComponentType, ReactNode } from "react";
+import { Minus, Plus } from "lucide-react";
+import Image from "next/image";
+
+import { Button } from "@tomako/ui/button";
+
+import { ToolStandardGenerationSteps } from "./tool-standard-generation-steps";
+
+export type ToolStandardBenefitCard = {
+  title: string;
+  body: string;
+  icon: LucideIcon | ComponentType<{ className?: string }>;
+};
+
+export type ToolStandardImageTextSection = {
+  id?: string;
+  title: string;
+  body: readonly string[];
+  image: {
+    src: string;
+    alt: string;
+  };
+  imageFirst?: boolean;
+  background?: "white" | "muted";
+};
+
+/**
+ * A readable, answer-first section for decision tools. Unlike image/text
+ * sections, it does not require an illustration merely to satisfy a layout.
+ */
+export type ToolStandardNarrativeSection = {
+  id?: string;
+  title: string;
+  body: readonly string[];
+  background?: "white" | "muted";
+};
+
+export type ToolStandardGenerationStep = {
+  title: string;
+  body: string;
+};
+
+export type ToolStandardReportPreview = {
+  eyebrow: string;
+  title: string;
+  intro: string;
+  inputLabel: string;
+  input: string;
+  outputLabel: string;
+  fields: readonly {
+    label: string;
+    body: string;
+  }[];
+};
+
+export type ToolStandardSectionId =
+  | "benefits"
+  | "reportPreview"
+  | "imageTextSections"
+  | "narrative"
+  | "generation"
+  | "faq";
+
+export type ToolStandardFaqItem = {
+  question: string;
+  answer?: string;
+};
+
+export type ToolLandingStandardSectionsProps = {
+  benefits: {
+    title: string;
+    cards: readonly ToolStandardBenefitCard[];
+  };
+  imageTextSections: readonly ToolStandardImageTextSection[];
+  narrativeSections?: readonly ToolStandardNarrativeSection[];
+  generation: {
+    title: string;
+    image: {
+      src: string;
+      alt: string;
+    };
+    steps: readonly ToolStandardGenerationStep[];
+    ctaLabel: string;
+    ctaHref?: string;
+  };
+  reportPreview?: ToolStandardReportPreview;
+  faq: {
+    title: string;
+    intro: string;
+    ctaLabel: string;
+    ctaHref?: string;
+    items: readonly ToolStandardFaqItem[];
+  };
+  /** Keep the shared primitives, while allowing a report-style tool to lead with its output. */
+  sectionOrder?: readonly ToolStandardSectionId[];
+  className?: string;
+};
+
+export function ToolLandingStandardSections({
+  benefits,
+  imageTextSections,
+  narrativeSections = [],
+  generation,
+  reportPreview,
+  faq,
+  sectionOrder = [
+    "benefits",
+    "imageTextSections",
+    "generation",
+    "faq",
+  ],
+  className,
+}: ToolLandingStandardSectionsProps) {
+  const sections: Record<ToolStandardSectionId, ReactNode> = {
+    benefits: <ToolStandardBenefitsSection {...benefits} />,
+    reportPreview: reportPreview ? (
+      <ToolStandardReportPreviewSection {...reportPreview} />
+    ) : null,
+    imageTextSections: imageTextSections.map((section, index) => (
+      <ToolStandardImageTextBlock
+        key={section.id ?? section.title}
+        {...section}
+        imagePriority={index === 0}
+      />
+    )),
+    narrative: narrativeSections.map((section) => (
+      <ToolStandardNarrativeBlock key={section.id ?? section.title} {...section} />
+    )),
+    generation: <ToolStandardGenerationSection {...generation} />,
+    faq: <ToolStandardFaqSection {...faq} />,
+  };
+
+  return (
+    <div className={className}>
+      {sectionOrder.map((section) => (
+        <div key={section}>{sections[section]}</div>
+      ))}
+    </div>
+  );
+}
+
+function ToolStandardNarrativeBlock({
+  id,
+  title,
+  body,
+  background = "white",
+}: ToolStandardNarrativeSection) {
+  return (
+    <section
+      className={`relative left-1/2 w-screen -translate-x-1/2 border-t border-[#E8EBF0] px-5 py-20 md:px-10 md:py-24 lg:px-16 lg:py-28 ${
+        background === "muted" ? "bg-[#F6F7F8]" : "bg-white"
+      }`}
+      data-tool-standard-section={id ?? "narrative"}
+    >
+      <div className="mx-auto max-w-[880px]">
+        <h2 className="text-balance text-[2rem] font-semibold leading-[1.18] text-[#010205] md:text-[40px]">
+          {title}
+        </h2>
+        <div className="mt-5 space-y-4 text-pretty text-base leading-[28px] text-[#0D1216] md:text-lg">
+          {body.map((paragraph, index) => (
+            <p key={index}>{paragraph}</p>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function ToolStandardBenefitsSection({
+  title,
+  cards,
+}: {
+  title: string;
+  cards: readonly ToolStandardBenefitCard[];
+}) {
+  return (
+    <section
+      className="relative left-1/2 w-screen -translate-x-1/2 border-t border-[#E8EBF0] bg-white px-5 py-24 md:px-10 md:py-28 lg:px-16 lg:py-32"
+      data-tool-standard-section="benefits"
+    >
+      <div className="mx-auto max-w-[1284px]">
+        <h2 className="text-balance text-center text-[2rem] font-semibold leading-[1.18] text-[#010205] md:text-[40px]">
+          {title}
+        </h2>
+        <div className="mt-8 grid gap-6 lg:grid-cols-3">
+          {cards.map((item) => {
+            const Icon = item.icon;
+
+            return (
+              <article
+                key={item.title}
+                className="min-w-0 rounded-2xl bg-[#F6F7F8] p-6"
+              >
+                <div className="flex min-w-0 items-center gap-4">
+                  <span className="flex size-12 shrink-0 items-center justify-center rounded-lg bg-[#E0D9FC] text-[#0D1216]">
+                    <Icon aria-hidden className="size-5" />
+                  </span>
+                  <h3 className="text-xl font-semibold leading-snug text-[#010205] md:text-2xl">
+                    {item.title}
+                  </h3>
+                </div>
+                <p className="mt-4 text-pretty text-base leading-[26px] text-[#11171D]/60">
+                  {item.body}
+                </p>
+              </article>
+            );
+          })}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function ToolStandardImageTextBlock({
+  id,
+  title,
+  body,
+  image,
+  imageFirst = false,
+  imagePriority = false,
+}: ToolStandardImageTextSection & { imagePriority?: boolean }) {
+  return (
+    <section
+      className="relative left-1/2 w-screen -translate-x-1/2 border-t border-[#E8EBF0] bg-white px-5 py-24 md:px-10 md:py-28 lg:px-16 lg:py-32"
+      data-tool-standard-section={id ?? "image-text"}
+    >
+      <div
+        className={`mx-auto grid max-w-[1356px] gap-8 xl:items-center xl:gap-12 ${
+          imageFirst
+            ? "xl:grid-cols-[minmax(0,0.95fr)_minmax(0,1.05fr)]"
+            : "xl:grid-cols-[minmax(0,1.05fr)_minmax(0,0.95fr)]"
+        }`}
+      >
+        {imageFirst ? (
+          <ToolStandardImageFrame {...image} priority={imagePriority} />
+        ) : null}
+        <div className={`min-w-0 ${imageFirst ? "xl:pl-4" : "xl:pr-4"}`}>
+          <h2 className="max-w-[620px] whitespace-pre-line text-balance text-[2rem] font-semibold leading-[1.18] text-[#010205] md:text-[40px]">
+            {title}
+          </h2>
+          <div className="mt-5 max-w-2xl space-y-4 text-pretty text-base leading-[26px] text-[#0D1216]">
+            {body.map((paragraph, index) => (
+              <p key={index}>{paragraph}</p>
+            ))}
+          </div>
+        </div>
+        {imageFirst ? null : (
+          <ToolStandardImageFrame {...image} priority={imagePriority} />
+        )}
+      </div>
+    </section>
+  );
+}
+
+function ToolStandardGenerationSection({
+  title,
+  image,
+  steps,
+  ctaLabel,
+  ctaHref,
+}: ToolLandingStandardSectionsProps["generation"]) {
+  return (
+    <section
+      className="relative left-1/2 w-screen -translate-x-1/2 border-t border-[#E8EBF0] bg-white px-5 py-24 md:px-10 md:py-28 lg:px-16 lg:py-32"
+      data-tool-standard-section="generation-steps"
+    >
+      <div className="mx-auto grid max-w-[1284px] gap-10 xl:grid-cols-2 xl:items-center xl:gap-14">
+        <ToolStandardImageFrame {...image} />
+        <div className="min-w-0 xl:pl-4">
+          <h2 className="max-w-[620px] whitespace-pre-line text-balance text-[2rem] font-semibold leading-[1.18] text-[#010205] md:text-[40px]">
+            {title}
+          </h2>
+          <ToolStandardGenerationSteps steps={steps} />
+          {ctaHref ? (
+            <Button
+              asChild
+              className="mt-8 h-12 min-w-40 rounded-lg bg-black px-4 text-base font-semibold text-white shadow-none hover:bg-[#1F1F1F]"
+            >
+              <a href={ctaHref}>{ctaLabel}</a>
+            </Button>
+          ) : (
+            <Button
+              type="button"
+              className="mt-8 h-12 min-w-40 rounded-lg bg-black px-4 text-base font-semibold text-white shadow-none hover:bg-[#1F1F1F]"
+            >
+              {ctaLabel}
+            </Button>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function ToolStandardReportPreviewSection({
+  eyebrow,
+  title,
+  intro,
+  inputLabel,
+  input,
+  outputLabel,
+  fields,
+}: ToolStandardReportPreview) {
+  return (
+    <section
+      className="relative left-1/2 w-screen -translate-x-1/2 border-t border-[#E8EBF0] bg-[#F6F7F8] px-5 py-24 md:px-10 md:py-28 lg:px-16 lg:py-32"
+      data-tool-standard-section="report-preview"
+    >
+      <div className="mx-auto max-w-[1284px]">
+        <p className="text-sm font-semibold uppercase tracking-[0.08em] text-[#4A5968]">
+          {eyebrow}
+        </p>
+        <div className="mt-4 grid gap-10 lg:grid-cols-[minmax(0,0.82fr)_minmax(0,1.18fr)] lg:items-start lg:gap-14">
+          <div>
+            <h2 className="max-w-[570px] text-balance text-[2rem] font-semibold leading-[1.18] text-[#010205] md:text-[40px]">
+              {title}
+            </h2>
+            <p className="mt-5 max-w-[560px] text-pretty text-base leading-[26px] text-[#0D1216]">
+              {intro}
+            </p>
+          </div>
+          <div className="overflow-hidden rounded-2xl border border-[#DDE3EA] bg-white shadow-[0_18px_42px_rgba(13,18,22,0.06)]">
+            <div className="border-b border-[#E8EBF0] bg-[#FBFCFD] px-6 py-5">
+              <p className="text-xs font-semibold uppercase tracking-[0.08em] text-[#56616B]">
+                {inputLabel}
+              </p>
+              <p className="mt-3 text-sm leading-6 text-[#0D1216]">{input}</p>
+            </div>
+            <div className="px-6 py-5">
+              <p className="text-xs font-semibold uppercase tracking-[0.08em] text-[#56616B]">
+                {outputLabel}
+              </p>
+              <div className="mt-4 grid gap-3 sm:grid-cols-2">
+                {fields.map((field) => (
+                  <article
+                    key={field.label}
+                    className="rounded-xl border border-[#E5E9F0] bg-[#F6F7F8] p-4"
+                  >
+                    <h3 className="text-sm font-semibold leading-5 text-[#010205]">
+                      {field.label}
+                    </h3>
+                    <p className="mt-2 text-sm leading-6 text-[#4D5964]">
+                      {field.body}
+                    </p>
+                  </article>
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+
+function ToolStandardFaqSection({
+  title,
+  intro,
+  ctaLabel,
+  ctaHref,
+  items,
+}: ToolLandingStandardSectionsProps["faq"]) {
+  return (
+    <section
+      className="relative left-1/2 w-screen -translate-x-1/2 overflow-hidden border-t border-[#E8EBF0] bg-white px-5 py-24 md:px-10 md:py-28 lg:px-16 lg:py-32"
+      data-tool-standard-section="faq"
+    >
+      <div className="relative mx-auto grid max-w-[1280px] gap-12 lg:grid-cols-[0.42fr_0.58fr] lg:gap-[90px]">
+        <div>
+          <h2 className="max-w-[620px] whitespace-pre-line text-balance text-[2rem] font-semibold leading-[1.18] text-[#010205] md:text-[40px]">
+            {title}
+          </h2>
+          <p className="mt-8 max-w-[531px] text-pretty text-base leading-[26px] text-[#0D1216]">
+            {intro}
+          </p>
+          {ctaHref ? (
+            <Button
+              asChild
+              variant="outline"
+              className="mt-10 h-12 rounded-full border-[#010205] bg-transparent px-6 text-base font-normal text-[#0D1216] shadow-none hover:bg-[#F6F7F8]"
+            >
+              <a href={ctaHref}>{ctaLabel}</a>
+            </Button>
+          ) : (
+            <Button
+              type="button"
+              variant="outline"
+              className="mt-10 h-12 rounded-full border-[#010205] bg-transparent px-6 text-base font-normal text-[#0D1216] shadow-none hover:bg-[#F6F7F8]"
+            >
+              {ctaLabel}
+            </Button>
+          )}
+        </div>
+        <div className="min-w-0">
+          {items.map((item, index) => (
+            <details
+              key={item.question}
+              className="group border-b border-black first:border-t"
+              open={index === 0}
+            >
+              <summary className="flex cursor-pointer list-none items-start justify-between gap-6 px-0 py-6 md:px-6 [&::-webkit-details-marker]:hidden">
+                <h3 className="max-w-[560px] text-pretty text-xl font-semibold leading-normal text-[#010205] md:text-2xl">
+                  {item.question}
+                </h3>
+                <span className="mt-1 flex size-6 shrink-0 items-center justify-center text-[#010205]">
+                  <Plus aria-hidden className="size-5 group-open:hidden" />
+                  <Minus aria-hidden className="hidden size-5 group-open:block" />
+                </span>
+              </summary>
+              {item.answer ? (
+                <p className="px-0 pb-7 text-pretty text-base leading-[26px] text-[#0D1216] md:px-6">
+                  {item.answer}
+                </p>
+              ) : null}
+            </details>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function ToolStandardImageFrame({
+  alt,
+  src,
+  priority = false,
+}: {
+  alt: string;
+  src: string;
+  priority?: boolean;
+}) {
+  return (
+    <figure className="mx-auto w-full min-w-0 max-w-[760px] overflow-hidden rounded-2xl border border-[#40576D]/[0.07] bg-white xl:max-w-none">
+      <Image
+        alt={alt}
+        className="h-auto w-full object-cover"
+        height={840}
+        priority={priority}
+        sizes="(min-width: 1536px) 630px, (min-width: 1280px) 45vw, (min-width: 768px) 760px, calc(100vw - 40px)"
+        src={src}
+        width={1260}
+      />
+    </figure>
+  );
+}

package/src/features/tools/shared/tool-ui-registry.ts

@@ -0,0 +1,237 @@
+export type ToolUiModuleStatus = "ready" | "candidate" | "planned";
+
+export type ToolUiModuleCategory =
+  | "shell"
+  | "workspace"
+  | "engine"
+  | "section"
+  | "conversion";
+
+export type ToolUiModule = {
+  id: string;
+  name: string;
+  category: ToolUiModuleCategory;
+  status: ToolUiModuleStatus;
+  source: string;
+  contract: string;
+  defaultUse: string;
+  fallback: string;
+  localDuplicateNames?: readonly string[];
+};
+
+export const REQUIRED_TOOL_UI_MODULE_IDS = [
+  "tool-page-shell",
+  "tool-workspace-section",
+  "tool-standard-landing-sections",
+  "tool-package-form",
+  "tool-result-view",
+  "tool-card-grid",
+  "tool-faq-section",
+  "tool-cta",
+] as const;
+
+export const TOOL_UI_GENERATION_RULES = [
+  "Read this registry before generating or refactoring any Tool page UI.",
+  "Reuse a ready module when its contract matches the page module intent.",
+  "Extend the shared module before writing a new local FAQ, card grid, CTA, workspace, form, or result view.",
+  "For custom workspaces, compose every matching control and state from src/components/tools/workspace; Design System Tool Landing and production Tool pages must import the same source instead of maintaining preview-only or page-local visual copies.",
+  "For new Tool pages with the standard SEO landing stack, use createStandardLandingContainer (src/features/tools/shared/create-standard-landing-container.tsx) instead of cloning a container.",
+  "For Guide/Card immersive twins (interview record/insight shape), use createGuideStackContainer instead of cloning those containers.",
+  "For new Tool pages, render ToolLandingStandardSections immediately after the workspace unless the user explicitly approves a custom landing stack.",
+  "For workspace-first Tool pages, pass showDefaultHeader={false} to ToolPageShell so the old marketing header does not appear above the workspace.",
+  "Workspace-first Tool pages use a white page background by default; do not wrap the whole tool page in beige, blue, or decorative canvas backgrounds.",
+  "ToolLandingStandardSections owns white full-bleed post-workspace bands: each white section background spans the viewport while inner content remains centered.",
+  "Use the registry to select shared modules, then always validate the result against p0-ui-gates.md for layout, states, responsive behavior, accessibility, and visual quality.",
+  "If a custom widget cannot reuse a module, document the custom reason in the delivery notes.",
+] as const;
+
+export const TOOL_UI_REGISTRY = [
+  {
+    id: "tool-page-shell",
+    name: "ToolPageShell",
+    category: "shell",
+    status: "ready",
+    source: "src/features/tools/shared/tool-page-shell.tsx",
+    contract:
+      "ToolSpec + locale + page children. Owns the public Tool page shell, white page background, sticky navigation, optional legacy header/hero, bottom footer, WebApplication JSON-LD, Breadcrumb JSON-LD, and FAQPage JSON-LD.",
+    defaultUse:
+      "Default outer shell for ToolPackage pages and any custom Tool page that still uses the shared public route. New workspace-first pages should set showDefaultHeader={false}.",
+    fallback:
+      "Only bypass for a route-level experiment that cannot use the shared /tools/[slug] dispatcher.",
+  },
+  {
+    id: "tool-workspace-section",
+    name: "ToolWorkspaceSection",
+    category: "workspace",
+    status: "ready",
+    source: "src/features/tools/shared/tool-guide-section.tsx",
+    contract:
+      "Heading, hint, optional action, and one interactive workspace child. In the current Tool page generation flow this workspace replaces the old standalone Hero and is the first page content below navigation. Complex workspaces should compose src/components/tools/workspace ToolWorkspaceLayout and ToolPreviewPanel so the right preview/result area keeps the shared light-gray module style.",
+    defaultUse:
+      "Default wrapper around the primary tool workspace near the top of the page.",
+    fallback:
+      "Custom workspace layout is allowed only when the interaction requires a different result/output geometry.",
+  },
+  {
+    id: "tool-package-form",
+    name: "FormBuilder",
+    category: "engine",
+    status: "ready",
+    source: "src/components/tools/engine/form-builder.tsx",
+    contract:
+      "FormFieldSpec[] + FormValues + invalid field ids. Renders text, textarea, select, and toggle fields with field-level errors.",
+    defaultUse:
+      "Default form renderer for every ToolPackage page.",
+    fallback:
+      "Extend FormFieldSpec and FormBuilder for repeated field patterns before creating a custom widget form.",
+  },
+  {
+    id: "tool-package-widget",
+    name: "PackageWidget",
+    category: "engine",
+    status: "ready",
+    source: "src/components/tools/engine/package-widget.tsx",
+    contract:
+      "Registered ToolPackage slug. Owns form submission, reset, task state, engine errors, copy, and result rendering.",
+    defaultUse:
+      "Default interactive widget for ToolPackage pages.",
+    fallback:
+      "Use a custom widget only for interactions that ToolPackage cannot express, such as canvas editing, multi-stage chat, or specialized file processing.",
+  },
+  {
+    id: "tool-result-view",
+    name: "ResultView",
+    category: "engine",
+    status: "ready",
+    source: "src/components/tools/engine/result-view.tsx",
+    contract:
+      "ResultViewBlock[] + validated result JSON. Renders keyValues, bulletList, bulletGroups, cardList, and strategicCurve result blocks.",
+    defaultUse:
+      "Default renderer for structured ToolPackage results.",
+    fallback:
+      "Add a new ResultViewBlock type when two or more tools need the same missing result shape.",
+  },
+  {
+    id: "tool-page-section",
+    name: "ToolSection",
+    category: "section",
+    status: "ready",
+    source: "src/features/tools/shared/tool-content-sections.tsx",
+    contract:
+      "Heading, optional intro, optional visual, optional children, and optional reverse layout.",
+    defaultUse:
+      "Base section primitive for reusable Tool landing modules.",
+    fallback:
+      "Write a custom section only when the content model cannot fit a heading, intro, visual, and children.",
+  },
+  {
+    id: "tool-standard-landing-sections",
+    name: "ToolLandingStandardSections",
+    category: "section",
+    status: "ready",
+    source: "src/features/tools/shared/tool-standard-landing-sections.tsx",
+    contract:
+      "Fixed post-workspace landing sequence: user-benefit cards, three alternating image/text education sections, generation steps, and FAQ. Accepts per-tool copy, local image assets, steps, icons, and FAQ items while preserving order, white full-bleed section bands, centered content, generous vertical spacing, and visual style.",
+    defaultUse:
+      "Default section stack immediately below ToolWorkspaceSection. Prefer createStandardLandingContainer when the page is only namespace/widget/icons/image config.",
+    fallback:
+      "Only replace, reorder, or omit when the user explicitly asks for a different landing flow and the delivery notes record the exception.",
+  },
+  {
+    id: "create-standard-landing-container",
+    name: "createStandardLandingContainer",
+    category: "shell",
+    status: "ready",
+    source: "src/features/tools/shared/create-standard-landing-container.tsx",
+    contract:
+      "Factory: guideNamespace + Widget + three benefit icons + generationImageSrc (+ optional copy key overrides). Renders ToolPageShell + ToolWorkspaceSection + ToolLandingStandardSections.",
+    defaultUse:
+      "Default container for A1-style workspace-first tools whose landing is the standard SEO 4-block stack. Do not clone app-icon-resizer / product-name-generator containers.",
+    fallback:
+      "Hand-write a container only for custom landing stacks or non-standard section order; document the exception. For Guide/Card immersive twins use createGuideStackContainer.",
+  },
+  {
+    id: "create-guide-stack-container",
+    name: "createGuideStackContainer",
+    category: "shell",
+    status: "ready",
+    source: "src/features/tools/shared/create-guide-stack-container.tsx",
+    contract:
+      "Factory: guideNamespace + Widget + asset paths + CTA hrefs. Renders immersive ToolPageShell + workspace + Guide/Card/FAQ/CTA stack (interview twin shape).",
+    defaultUse:
+      "User-interview record/insight and similar Guide-stack twins. Do not clone those containers.",
+    fallback:
+      "Use createStandardLandingContainer for ToolLandingStandardSections pages; ToolPackage for form+result tools; custom only for unique layouts.",
+  },
+  {
+    id: "tool-card-grid",
+    name: "ToolCardGrid",
+    category: "section",
+    status: "ready",
+    source: "src/features/tools/shared/tool-content-sections.tsx",
+    contract:
+      "Readonly cards with title/body and two- or three-column responsive layout.",
+    defaultUse:
+      "Default value, standards, use-case, and compact feature card pattern.",
+    fallback:
+      "Extend ToolCardGrid before creating a local CardGrid clone.",
+    localDuplicateNames: ["CardGrid", "TextCardGrid"],
+  },
+  {
+    id: "tool-boundary-section",
+    name: "ToolBoundarySection",
+    category: "section",
+    status: "ready",
+    source: "src/features/tools/shared/tool-content-sections.tsx",
+    contract:
+      "Heading, optional intro, and grouped bullet lists with optional visual.",
+    defaultUse:
+      "Default pattern for support scope, privacy, failure cases, and responsibility boundaries.",
+    fallback:
+      "Use FAQ when the content is question-shaped; use custom only for a richer comparison or checklist model.",
+  },
+  {
+    id: "tool-comparison-section",
+    name: "ToolComparisonSection",
+    category: "section",
+    status: "ready",
+    source: "src/features/tools/shared/tool-content-sections.tsx",
+    contract:
+      "Before label, after label, and before/after row pairs.",
+    defaultUse:
+      "Default pattern for before/after positioning and quality-difference modules.",
+    fallback:
+      "Use ToolCardGrid when there is no meaningful before/after relationship.",
+  },
+  {
+    id: "tool-faq-section",
+    name: "ToolFaqSection",
+    category: "section",
+    status: "ready",
+    source: "src/features/tools/shared/tool-content-sections.tsx",
+    contract:
+      "Heading, optional intro, and question/answer rows.",
+    defaultUse:
+      "Default FAQ renderer for Tool landing pages and ToolPackage FAQ content.",
+    fallback:
+      "Extend ToolFaqSection before creating a local FaqSection clone.",
+    localDuplicateNames: ["FaqSection", "FaqRows"],
+  },
+  {
+    id: "tool-cta",
+    name: "ToolCta",
+    category: "conversion",
+    status: "ready",
+    source: "src/features/tools/shared/tool-cta.tsx",
+    contract:
+      "Optional heading, optional hint, primary link, optional secondary link, and neutral/lime tone.",
+    defaultUse:
+      "Default bottom conversion band for Tool pages.",
+    fallback:
+      "Custom CTA is allowed when the page has a materially different conversion target.",
+  },
+] satisfies readonly ToolUiModule[];
+
+export function getToolUiModule(id: string): ToolUiModule | undefined {
+  return TOOL_UI_REGISTRY.find((module) => module.id === id);
+}