@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/apps/storefront/src/lib/storyblok/provider.ts

@@ -17,12 +17,24 @@
 import type {
   EditorialPage,
   HomeContent,
-  SiteChrome,
 } from "./content-model.js";
+import type { ChromeConfig } from "../chrome/model.js";
 import type { CustomizationEnv, KvGet, TenantConfig } from "@tot/public-runtime";
-import { contentArtifactPath, readPublishedArtifact } from "@tot/public-runtime";
+import {
+  contentArtifactPath,
+  listPublishedArtifactPaths,
+  readPublishedArtifact,
+} from "@tot/public-runtime";
 import { renderRawChrome } from "../rawChrome.js";
 import { parseChromeConfig } from "../chrome/parseConfig.js";
+import { parseChromeAssignments } from "../chrome/model.js";
+
+/** Safe, always-valid fallback when neither the tenant's own chrome.json nor
+ * the default scope's validates — the storefront must always render. */
+const EMPTY_CHROME_CONFIG: ChromeConfig = {
+  header: { variant: "primary", brand: { label: "" }, nav: [] },
+  footer: { variant: "default", columns: [] },
+};
 
 export interface ContentProvider {
   getHome(): Promise<HomeContent>;
@@ -48,11 +60,21 @@ export interface ContentProvider {
    * spliced in (see lib/rawMarketingHtml.ts). Lets raw pages stop duplicating
    * chrome: chrome lives once here, pages become fragments. File:
    * `content/<tenant>/chrome.html`. Tenant-owned (no cross-tenant fallback).
+   *
+   * `currentPath`, when given, is the tenant-relative request path (e.g. "/"
+   * or "/collections/all") in the same unprefixed form the chrome config's
+   * own nav `href`s are authored in — drives `aria-current="page"` on the
+   * matching primary-nav link when the wrapper is rendered from chrome.json
+   * (rawChrome.ts). Omitted ⇒ no item is marked current.
    */
-  getChromeHtml(): Promise<string | null>;
-  getChrome(): Promise<SiteChrome>;
+  getChromeHtml(currentPath?: string): Promise<string | null>;
+  getChrome(): Promise<ChromeConfig>;
   getPage(slug: string): Promise<EditorialPage | null>;
   listPages(): Promise<EditorialPage[]>;
+  /** Raw tenant-content artifact, relative to `content/`. */
+  readArtifact(relative: string): Promise<string | null>;
+  /** Artifact paths relative to `content/`; null means use a legacy fallback. */
+  listArtifactPaths(prefix?: string): Promise<string[] | null>;
 }
 
 // ---------------------------------------------------------------------------
@@ -67,9 +89,16 @@ export interface ContentProvider {
 const homeGlobs = import.meta.glob<HomeContent>("../../../../../tenants/*/content/home.json", {
   import: "default",
 });
-const chromeGlobs = import.meta.glob<SiteChrome>("../../../../../tenants/*/content/chrome.json", {
+const chromeGlobs = import.meta.glob<unknown>("../../../../../tenants/*/content/chrome.json", {
   import: "default",
 });
+// Per-page header/footer variant overrides for the raw-HTML chrome path (see
+// lib/chrome/assignments.ts). Tenant-owned, no cross-tenant fallback — same
+// convention as chromeGlobs above.
+const chromeAssignmentGlobs = import.meta.glob<unknown>(
+  "../../../../../tenants/*/content/chrome-assignments.json",
+  { import: "default" },
+);
 const pageGlobs = import.meta.glob<EditorialPage>("../../../../../tenants/*/content/pages/*.json", {
   import: "default",
 });
@@ -91,6 +120,10 @@ const chromeHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/conte
   query: "?raw",
   import: "default",
 });
+const artifactGlobs = import.meta.glob<string>("../../../../../tenants/*/content/**/*", {
+  query: "?raw",
+  import: "default",
+});
 
 const DEFAULT_SCOPE = "home";
 
@@ -196,18 +229,22 @@ export class LocalContentProvider implements ContentProvider {
       .sort((a, b) => a.localeCompare(b));
   }
 
-  async getChromeHtml(): Promise<string | null> {
+  async getChromeHtml(currentPath?: string): Promise<string | null> {
     // (1) A hand-authored chrome.html wins — keeps a not-yet-adopted tenant's chrome
     //     byte-identical (dev: fresh from disk so an edit previews on save).
     const dev = await readRawDevFile(this.scope, "chrome.html");
     if (dev !== null) return dev;
     const loader = pickContent(chromeHtmlGlobs, this.scope);
     if (loader) return loader();
-    // (2) No chrome.html: render the CANONICAL shared chrome (unit F3) from the
-    //     tenant's chrome.json — but only when it opted in (sharedChrome: true).
-    //     Tenant-owned only, like the raw HTML above (no cross-tenant fallback).
+    // (2) No chrome.html: render the CANONICAL shared chrome from the
+    //     tenant's chrome.json — but only when it validates whole against the
+    //     consolidated ChromeConfig schema (lib/chrome/parseConfig.ts). Tenant-
+    //     owned only, like the raw HTML above (no cross-tenant fallback).
     const config = await this.loadChromeConfig();
-    return config ? renderRawChrome(config) : null;
+    if (!config) return null;
+    // Per-page variant override — a page not listed in chrome-assignments.json
+    // keeps chrome.json's default variant. renderRawChrome resolves it.
+    return renderRawChrome(config, currentPath, await this.loadChromeAssignments());
   }
 
   /** The tenant's parsed raw-chrome config (chrome.json), or null if not adopted. */
@@ -225,31 +262,33 @@ export class LocalContentProvider implements ContentProvider {
     return loader ? parseChromeConfig(await loader()) : null;
   }
 
-  async getChrome(): Promise<SiteChrome> {
+  /** The tenant's parsed page-assignment manifest (chrome-assignments.json),
+   * or null if absent/invalid — same dev-hot-reload + tenant-owned-only
+   * discipline as loadChromeConfig. */
+  private async loadChromeAssignments(): Promise<ReturnType<typeof parseChromeAssignments>> {
+    const devRaw = await readRawDevFile(this.scope, "chrome-assignments.json");
+    if (devRaw !== null) {
+      try {
+        return parseChromeAssignments(JSON.parse(devRaw));
+      } catch {
+        return null;
+      }
+    }
+    const loader = pickContent(chromeAssignmentGlobs, this.scope);
+    return loader ? parseChromeAssignments(await loader()) : null;
+  }
+
+  async getChrome(): Promise<ChromeConfig> {
+    // The full config is validated as ONE document now (header/footer are
+    // both required) — there is no more partial-field merge across scopes; a
+    // tenant's own chrome.json either validates whole, or the default scope's
+    // does, or the storefront falls back to an empty-but-valid config.
+    const own = await this.loadChromeConfig();
+    if (own) return own;
+    if (this.scope === DEFAULT_SCOPE) return EMPTY_CHROME_CONFIG;
     const defL = pickContent(chromeGlobs, DEFAULT_SCOPE);
-    const def: SiteChrome = defL
-      ? await defL()
-      : { nav: [], footer: { columns: [], social: [] } };
-    const ownL = pickContent(chromeGlobs, this.scope);
-    if (!ownL) return def;
-    const c = await ownL();
-    if (this.scope === DEFAULT_SCOPE) return c;
-    // Per-field fallback fills only STRUCTURAL scaffolding (nav/footer) so a
-    // partially-adopted tenant still renders. Promotional/identity/legal fields
-    // (announcement, headerCtas, disclaimers) are tenant-OWNED and never inherit
-    // from the default scope — otherwise e.g. a marketing tenant would show the
-    // default store's shipping banner or nicotine disclaimers.
-    return {
-      nav: c.nav?.length ? c.nav : def.nav,
-      footer:
-        c.footer && (c.footer.columns?.length || c.footer.social?.length)
-          ? c.footer
-          : def.footer,
-      headerCtas: c.headerCtas,
-      announcement: c.announcement,
-      disclaimer: c.disclaimer,
-      disclaimers: c.disclaimers,
-    };
+    const def = defL ? parseChromeConfig(await defL()) : null;
+    return def ?? EMPTY_CHROME_CONFIG;
   }
 
   async getPage(slug: string): Promise<EditorialPage | null> {
@@ -264,6 +303,24 @@ export class LocalContentProvider implements ContentProvider {
     const loaders = pickPages(this.scope);
     return Promise.all(loaders.map((l) => l()));
   }
+
+  async readArtifact(relative: string): Promise<string | null> {
+    const normalized = relative.replace(/^\/+/, "");
+    const marker = `/tenants/${this.scope}/content/${normalized}`;
+    const key = Object.keys(artifactGlobs).find((candidate) => candidate.endsWith(marker));
+    return key ? artifactGlobs[key]!() : null;
+  }
+
+  async listArtifactPaths(prefix = ""): Promise<string[]> {
+    const marker = `/tenants/${this.scope}/content/`;
+    return Object.keys(artifactGlobs)
+      .flatMap((key) => {
+        const at = key.indexOf(marker);
+        return at < 0 ? [] : [key.slice(at + marker.length)];
+      })
+      .filter((path) => path.startsWith(prefix))
+      .sort((a, b) => a.localeCompare(b));
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -405,26 +462,24 @@ export class StoryblokContentProvider implements ContentProvider {
     return this.fallback.listPageHtmlSlugs();
   }
 
-  getChromeHtml(): Promise<string | null> {
+  getChromeHtml(currentPath?: string): Promise<string | null> {
     // The chrome wrapper lives in tenant content files, not Storyblok — delegate.
-    return this.fallback.getChromeHtml();
+    return this.fallback.getChromeHtml(currentPath);
   }
 
-  async getChrome(): Promise<SiteChrome> {
-    // Editorial chrome (nav/footer/tagline) is authored in Storyblok; the
-    // announcement + legal disclaimers are MIGRATION-sourced (written to local
-    // chrome.json), so overlay those from the fallback regardless.
+  async getChrome(): Promise<ChromeConfig> {
+    // Editorial chrome (nav/footer) is authored in Storyblok; brand/variant
+    // and everything else stay MIGRATION-sourced (the local chrome.json), so
+    // overlay only nav + footer from Storyblok when present.
     const local = await this.fallback.getChrome();
     try {
       const story = await fetchStory(this.token, "chrome");
       const c = story?.content;
       if (c && Array.isArray(c.nav)) {
         return {
-          nav: c.nav,
-          footer: c.footer ?? local.footer,
-          announcement: local.announcement ?? c.announcement,
-          disclaimer: local.disclaimer,
-          disclaimers: local.disclaimers,
+          ...local,
+          header: { ...local.header, nav: c.nav },
+          footer: c.footer ? { ...local.footer, ...c.footer } : local.footer,
         };
       }
     } catch {
@@ -461,6 +516,14 @@ export class StoryblokContentProvider implements ContentProvider {
     }
     return this.fallback.listPages();
   }
+
+  readArtifact(relative: string): Promise<string | null> {
+    return this.fallback.readArtifact(relative);
+  }
+
+  listArtifactPaths(prefix?: string): Promise<string[] | null> {
+    return this.fallback.listArtifactPaths(prefix);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -468,7 +531,8 @@ export class StoryblokContentProvider implements ContentProvider {
 // resolved environment (store->app wiring). For each content artifact it checks
 // the customization store ({live,test} pointer -> versioned JSON); if present it
 // serves that, otherwise it delegates to the base provider (Storyblok/local).
-// listPages() stays from the base (per-page overrides flow through getPage).
+// Enumeration also follows the selected immutable manifest, so sitemap/blog/page
+// indexes do not need a build-time tenant checkout.
 // ---------------------------------------------------------------------------
 
 export interface ContentCustomization {
@@ -517,34 +581,72 @@ export class PublishedContentProvider implements ContentProvider {
     return (await this.publishedRaw(rel)) ?? this.base.getPageHtml(slug);
   }
   listPageHtmlSlugs(): Promise<string[]> {
-    return this.base.listPageHtmlSlugs();
+    return this.listArtifactPaths("pages-html/").then((paths) =>
+      paths === null
+        ? this.base.listPageHtmlSlugs()
+        : paths
+            .filter((path) => path.endsWith(".html"))
+            .map((path) => path.slice("pages-html/".length, -".html".length)),
+    );
   }
-  async getChromeHtml(): Promise<string | null> {
+  async getChromeHtml(currentPath?: string): Promise<string | null> {
     // A published raw chrome.html override (parallels the home.html/pages-html
     // publish path) wins, so a vendor edit previews / goes live with no rebuild.
     const publishedHtml = await this.publishedRaw("chrome.html");
     if (publishedHtml) return publishedHtml;
-    // Else, if the PUBLISHED chrome.json opts into shared chrome (unit F3), render
+    // Else, if the PUBLISHED chrome.json opts into shared chrome, render
     // the canonical wrapper from it — so a config edit previews without a rebuild.
     const config = parseChromeConfig(await this.published<unknown>("chrome.json"));
-    if (config) return renderRawChrome(config);
+    if (config) {
+      // Per-page variant override, resolved against the PUBLISHED assignment
+      // manifest (mirrors chrome.json itself — each source resolves fully
+      // within itself, no mixing published/base artifacts).
+      const assignments = parseChromeAssignments(await this.published<unknown>("chrome-assignments.json"));
+      return renderRawChrome(config, currentPath, assignments);
+    }
     // Otherwise fall back to the base chain (bundled chrome.html or config render).
-    return this.base.getChromeHtml();
+    return this.base.getChromeHtml(currentPath);
   }
-  async getChrome(): Promise<SiteChrome> {
-    return (await this.published<SiteChrome>("chrome.json")) ?? this.base.getChrome();
+  async getChrome(): Promise<ChromeConfig> {
+    // Runs through the SAME fail-closed schema validator as getChromeHtml's
+    // chrome.json branch (lib/chrome/parseConfig.ts) — a published artifact is
+    // no longer trusted blind (was: JSON.parse + a raw cast to SiteChrome).
+    const config = parseChromeConfig(await this.published<unknown>("chrome.json"));
+    return config ?? this.base.getChrome();
   }
   async getPage(slug: string): Promise<EditorialPage | null> {
     return (await this.published<EditorialPage>(`pages/${slug}.json`)) ?? this.base.getPage(slug);
   }
-  listPages(): Promise<EditorialPage[]> {
-    return this.base.listPages();
+  async listPages(): Promise<EditorialPage[]> {
+    const paths = await this.listArtifactPaths("pages/");
+    if (paths === null) return this.base.listPages();
+    const pages = await Promise.all(
+      paths
+        .filter((path) => path.endsWith(".json"))
+        .map(async (path) => this.published<EditorialPage>(path)),
+    );
+    return pages.filter((page): page is EditorialPage => page !== null);
+  }
+
+  readArtifact(relative: string): Promise<string | null> {
+    return this.publishedRaw(relative);
+  }
+
+  async listArtifactPaths(prefix = ""): Promise<string[] | null> {
+    const root = contentArtifactPath(this.tenantId, "");
+    const paths = await listPublishedArtifactPaths(
+      this.cust.get,
+      this.tenantId,
+      this.cust.env,
+      `${root}${prefix}`,
+    );
+    return paths?.map((path) => path.slice(root.length)) ?? null;
   }
 }
 
 // ---------------------------------------------------------------------------
-// DevDraftContentProvider — the per-developer DRAFT overlay (decision
-// draft-overlay-same-origin). Wraps the resolved provider chain and serves a
+// DevDraftContentProvider — the per-developer DRAFT overlay. Wraps the
+// resolved provider chain and serves a
 // draft artifact (written by /api/content-edit/ai-edit into TENANT_CACHE under
 // `dev-draft:<tenantId>:<draftId>:<path>`) when one exists, else delegates.
 // The middleware constructs this ONLY for a request whose signed tot_dev_draft
@@ -581,10 +683,10 @@ export class DevDraftContentProvider implements ContentProvider {
   listPageHtmlSlugs(): Promise<string[]> {
     return this.base.listPageHtmlSlugs();
   }
-  getChromeHtml(): Promise<string | null> {
-    return this.base.getChromeHtml();
+  getChromeHtml(currentPath?: string): Promise<string | null> {
+    return this.base.getChromeHtml(currentPath);
   }
-  getChrome(): Promise<SiteChrome> {
+  getChrome(): Promise<ChromeConfig> {
     return this.base.getChrome();
   }
   getPage(slug: string): Promise<EditorialPage | null> {
@@ -593,6 +695,12 @@ export class DevDraftContentProvider implements ContentProvider {
   listPages(): Promise<EditorialPage[]> {
     return this.base.listPages();
   }
+  readArtifact(relative: string): Promise<string | null> {
+    return this.base.readArtifact(relative);
+  }
+  listArtifactPaths(prefix?: string): Promise<string[] | null> {
+    return this.base.listArtifactPaths(prefix);
+  }
 }
 
 const PLACEHOLDER_TOKEN_RE = /PLACEHOLDER|^$/i;

package/apps/storefront/src/lib/subscription/model.ts

@@ -8,7 +8,7 @@
  *
  * Because a savings headline (a "%", a "$" amount) is a claim, {@link
  * SubscriptionFigure} is treated as ILLUSTRATIVE by default — same discipline
- * as the membership tier figures (decision compliance-widgets-platform-owned):
+ * as the membership tier figures:
  * unless a figure explicitly asserts `real: true`, the widget marks it as an
  * example so it is never presented as a live offer.
  */
@@ -44,8 +44,8 @@ export interface SubscriptionFigure {
 }
 
 /**
- * The account-management actions a subscriber can take on an Autopilot order
- * (F10). The storefront never EXECUTES these — each is a handoff into the
+ * The account-management actions a subscriber can take on an Autopilot order.
+ * The storefront never EXECUTES these — each is a handoff into the
  * tenant's product-owned manage-subscription portal (see {@link
  * SubscriptionManagePortal}); this enum just gives the entry points stable,
  * typed identities so the copy, ordering, and analytics hooks are consistent.
@@ -151,7 +151,7 @@ function defaultActionHref(action: SubscriptionManageAction, baseHref: string):
 }
 
 /**
- * Build the manage-subscription entry points for a tenant's portal — the F10
+ * Build the manage-subscription entry points for a tenant's portal — the
  * skip / pause / cancel / reschedule / quantity (+ resume / swap / address)
  * handoffs. Each entry is a plain link into `portal.baseHref`; the storefront
  * hands off, the provider executes.

package/apps/storefront/src/lib/the-build/provider.ts

@@ -0,0 +1,32 @@
+// Thin wrapper binding the generic blog engine to the "the-build" collection.
+// The engine (src/lib/blog/collection.ts) is the single implementation; this
+// module only fixes the collection id so existing/downstream callers can import
+// collection-bound helpers.
+import { getPost, listPosts, resolveRedirect, type Collection } from "../blog/collection.js";
+import type { BlogPost, BlogPostSummary } from "../blog/types.js";
+import type { ContentProvider } from "../storyblok/provider.js";
+
+export const THE_BUILD: Collection = { id: "the-build", base: "/the-build" };
+
+export function listBuildPosts(
+  tenantId: string,
+  opts?: { includeUnpublished?: boolean; now?: string; content?: ContentProvider },
+): Promise<BlogPostSummary[]> {
+  return listPosts(tenantId, THE_BUILD.id, opts);
+}
+
+export function getBuildPost(
+  tenantId: string,
+  slug: string,
+  opts?: { includeUnpublished?: boolean; now?: string; content?: ContentProvider },
+): Promise<BlogPost | null> {
+  return getPost(tenantId, THE_BUILD.id, slug, opts);
+}
+
+export function resolveBuildRedirect(
+  tenantId: string,
+  slug: string,
+  content?: ContentProvider,
+): Promise<string | null> {
+  return resolveRedirect(tenantId, THE_BUILD.id, slug, content);
+}

package/apps/storefront/src/lib/the-build/readingTime.ts

@@ -0,0 +1,35 @@
+// Estimated reading time for a post's rendered HTML (B1.5). Pure + Node-free
+// (parse5 is Workers-safe), so it's unit-testable and usable on any render path.
+import { parseFragment } from "parse5";
+
+/** Minimal structural view of a parse5 node (duck-typed, as scripts/dev/locate.mjs does). */
+interface P5Node {
+  nodeName: string;
+  tagName?: string;
+  value?: string;
+  childNodes?: P5Node[];
+}
+
+const WORDS_PER_MINUTE = 225;
+
+function collectText(node: P5Node, out: string[]): void {
+  if (node.nodeName === "#text") {
+    if (node.value) out.push(node.value);
+    return;
+  }
+  // Non-visible/text-irrelevant subtrees never count toward reading time.
+  if (node.tagName === "script" || node.tagName === "style") return;
+  for (const child of node.childNodes ?? []) collectText(child, out);
+}
+
+/**
+ * Reading time in whole minutes: visible word count / 225 wpm, rounded up, min 1.
+ * Ignores markup, script, and style content.
+ */
+export function readingTime(html: string): number {
+  const frag = parseFragment(html ?? "") as unknown as P5Node;
+  const parts: string[] = [];
+  collectText(frag, parts);
+  const words = parts.join(" ").trim().split(/\s+/).filter(Boolean);
+  return Math.max(1, Math.ceil(words.length / WORDS_PER_MINUTE));
+}

package/apps/storefront/src/lib/the-build/toc.ts

@@ -0,0 +1,95 @@
+// Table of contents for a post's rendered HTML (B1.5): parse h2/h3 headings and
+// derive stable anchor ids. Pure + Node-free (parse5 is Workers-safe).
+//
+// `toc()` and `htmlWithHeadingIds()` derive ids from the SAME deterministic pass
+// (`annotate`), so a render path can feed `htmlWithHeadingIds(post.contentHtml)`
+// to `set:html` and `toc(post.contentHtml)` to the aside and the anchors line up.
+import { parseFragment, serialize } from "parse5";
+import { slugifyHeading } from "../content/prose.js";
+
+/** Minimal structural view of a parse5 node (duck-typed, as scripts/dev/locate.mjs does). */
+interface P5Node {
+  nodeName: string;
+  tagName?: string;
+  value?: string;
+  attrs?: { name: string; value: string }[];
+  childNodes?: P5Node[];
+}
+
+export interface TocEntry {
+  id: string;
+  text: string;
+  level: 2 | 3;
+}
+
+function textOf(node: P5Node): string {
+  if (node.nodeName === "#text") return node.value ?? "";
+  return (node.childNodes ?? []).map(textOf).join("");
+}
+
+function getId(node: P5Node): string | undefined {
+  return node.attrs?.find((a) => a.name === "id")?.value?.trim() || undefined;
+}
+
+function* headings(node: P5Node): Generator<P5Node> {
+  for (const child of node.childNodes ?? []) {
+    if (child.tagName === "h2" || child.tagName === "h3") yield child;
+    yield* headings(child);
+  }
+}
+
+interface AnnotatedHeading {
+  node: P5Node;
+  id: string;
+  text: string;
+  level: 2 | 3;
+}
+
+/**
+ * Walk headings in document order, assigning each a unique anchor id: an
+ * author-supplied `id` is kept as-is; otherwise the slugified text, de-duped
+ * with a numeric suffix on collision. Empty headings are skipped.
+ */
+function* annotate(root: P5Node): Generator<AnnotatedHeading> {
+  const seen = new Map<string, number>();
+  for (const node of headings(root)) {
+    const text = textOf(node).replace(/\s+/g, " ").trim();
+    if (!text) continue;
+    const level: 2 | 3 = node.tagName === "h2" ? 2 : 3;
+    const explicit = getId(node);
+    let id: string;
+    if (explicit) {
+      id = explicit;
+      seen.set(id, (seen.get(id) ?? 0) + 1);
+    } else {
+      const base = slugifyHeading(text) || "section";
+      const n = seen.get(base) ?? 0;
+      seen.set(base, n + 1);
+      id = n === 0 ? base : `${base}-${n + 1}`;
+    }
+    yield { node, id, text, level };
+  }
+}
+
+/** TOC entries (one per h2/h3) with stable anchor ids, in document order. */
+export function toc(html: string): TocEntry[] {
+  const frag = parseFragment(html ?? "") as unknown as P5Node;
+  return [...annotate(frag)].map(({ id, text, level }) => ({ id, text, level }));
+}
+
+/**
+ * The same HTML with anchor ids added to any h2/h3 that lacks one (author ids
+ * untouched). Returns the input unchanged when every heading already has an id,
+ * so posts without generated anchors are byte-for-byte preserved.
+ */
+export function htmlWithHeadingIds(html: string): string {
+  const frag = parseFragment(html ?? "") as unknown as P5Node;
+  let changed = false;
+  for (const { node, id } of annotate(frag)) {
+    if (!getId(node)) {
+      node.attrs = [...(node.attrs ?? []), { name: "id", value: id }];
+      changed = true;
+    }
+  }
+  return changed ? serialize(frag as never) : (html ?? "");
+}

package/apps/storefront/src/lib/tot/ToTClient.ts

@@ -166,7 +166,7 @@ export async function createToTClient(
   tenant: TenantConfig,
   d1?: D1Like,
 ): Promise<ToTClient> {
-  // Edge read replica (epics/edge-read-replica.md): when a D1 binding is wired,
+  // Edge read replica: when a D1 binding is wired,
   // serve reads from it (FTS5 search + SQL facets). Otherwise the bundled fixture
   // snapshot renders the site offline. The tot20 HTTP catalog API has been retired,
   // so the read path is fully edge-native.

package/apps/storefront/src/lib/tot/d1Client.ts

@@ -1,5 +1,5 @@
 /**
- * D1-backed ToTClient — the edge read-replica path (epics/edge-read-replica.md).
+ * D1-backed ToTClient — the edge read-replica path.
  *
  * Implements the same ToTClient interface as Fixture/Http, but every read is a D1
  * query (FTS5 search, SQL faceted listing, row-blob retrieval) instead of an
@@ -56,7 +56,7 @@ export class D1ToTClient implements ToTClient {
   }
 
   async getReviews(_handle: string): Promise<Review[]> {
-    // Phase 1 reviews are display-via-metafields; D1 carries none yet.
+    // Reviews are display-via-metafields; the D1 catalog carries none.
     return [];
   }
 }

package/apps/storefront/src/lib/tot/totClientInterface.ts

@@ -1,11 +1,10 @@
 /**
  * The ToTClient interface — the storefront's single product-truth contract.
  *
- * Extracted from ToTClient.ts so the concrete backends (FixtureToTClient here,
+ * Lives in its own module so the concrete backends (FixtureToTClient here,
  * D1ToTClient in d1Client.ts) can both `implements ToTClient` without a circular
  * module edge: d1Client imports only this contract, while ToTClient.ts imports
- * D1ToTClient for its factory. ToTClient.ts re-exports this type, so existing
- * `import type { ToTClient } from "./ToTClient"` call sites are unchanged.
+ * D1ToTClient for its factory. ToTClient.ts re-exports this type.
  */
 import type {
   CatalogCollection,
@@ -25,6 +24,6 @@ export interface ToTClient {
   getFeatured(limit?: number): Promise<CatalogProduct[]>;
   /** Full active catalog — used to build the per-tenant search index. */
   getAllActiveProducts(): Promise<CatalogProduct[]>;
-  /** Full review content for a product (migrated from the store's reviews app). */
+  /** Full review content for a product. */
   getReviews(handle: string): Promise<Review[]>;
 }