@tokenoftrust/storefront-runner 2.2.126 → 2.3.0

package/apps/storefront/src/config/devTenantSeed.ts

@@ -14,9 +14,12 @@
  * The tenant's identity IS its dir name (the colocation convention: dir ==
  * tenant_id == appDomain == tot_data_scope). Content (content/home.html) and
  * theme (theme.json) come straight from the checkout via the existing dir globs;
- * catalog/compliance data it lacks DEGRADES to empty — siteType "marketing"
- * means no catalog is required, and index.astro serves the raw home.html before
- * any product resolution, so the tenant root renders instead of 404ing.
+ * catalog data it lacks resolves to an empty catalog, exactly as on the hosted
+ * Worker. Site type is never inferred here: like a provisioned tenant record the
+ * synthesized one leaves `siteType` undeclared (commerce), and the checkout's own
+ * `.tot/config.json` declaration — applied on top of this record on every surface
+ * (config/declaredTenantConfig.ts) — decides it. So `tot dev` renders a store's
+ * home.json with the same block vocabulary the hosted build renders.
  *
  * DEV ONLY: in prod the TENANT_CACHE KV drives the resolver and staticTenants is
  * the seed; this path is never taken. Kept inside `src/config` per the
@@ -35,13 +38,6 @@ export interface DevTenantHints {
    * Undefined ⇒ the colocation convention (dir == appDomain == scope).
    */
   appDomain?: string;
-  /**
-   * True when the checkout has a catalog: its own `content/catalog/products/` files,
-   * or a grandfathered in-repo snapshot for its data scope. When true we serve a real
-   * COMMERCE tenant so /collections + /products render from it; when false we degrade
-   * to a marketing home (no catalog).
-   */
-  hasCatalog?: boolean;
   /**
    * The tenant's own `tenants/<id>/analytics.json` content (already-parsed JSON),
    * or undefined when the tenant declares none. Materialized into `integrations`
@@ -56,10 +52,9 @@ export interface DevTenantHints {
  * colocated dir name (dir == id == appDomain == tot_data_scope); a slug tenant can
  * override the resolvable appDomain via `hints.appDomain`. No Storyblok space
  * (a "PLACEHOLDER" token → LocalContentProvider serves the checkout's content/).
- * Commerce is data-driven: with catalog fixtures on disk the tenant is
- * COMMERCE (catalog on); without them it degrades to a marketing home (siteType
- * "marketing" → no catalog required, so the root renders instead of 404ing).
- * Theme tokens come from the checkout's theme.json.
+ * `siteType` stays undeclared, as on a provisioned record, and the demo checkout
+ * store is wired so add-to-cart works on localhost. Theme tokens come from the
+ * checkout's theme.json.
  */
 export function synthesizeDevTenant(
   id: string,
@@ -98,27 +93,20 @@ export function synthesizeDevTenant(
     ...(integrations.length > 0 ? { integrations } : {}),
     ...(euUkVisitors ? { euUkVisitors } : {}),
   };
-  if (hints.hasCatalog) {
-    // Catalog fixtures on disk → a real commerce tenant (siteType omitted ==
-    // commerce → catalog on). Cart wires to the shared ToT demo checkout store
-    // (test mode, no secret), the same as the bundled demo tenants — so
-    // /collections + /products resolve and add-to-cart works on localhost.
-    return {
-      ...base,
-      commerce: { checkout: { storeSubDomain: "tot-preview", mode: "unsigned-demo" } },
-    };
-  }
-  // No catalog on disk → serve the raw marketing home and degrade commerce to
-  // empty rather than 404 the tenant root.
-  return { ...base, siteType: "marketing" };
+  // Cart wires to the shared ToT demo checkout store (test mode, no secret), the
+  // same as the bundled demo tenants. A marketing tenant never resolves it (the
+  // render chain gates on features.catalog); a commerce one gets its cart
+  // affordance and /cart on localhost whether or not it has catalog files yet.
+  return {
+    ...base,
+    commerce: { checkout: { storeSubDomain: "tot-preview", mode: "unsigned-demo" } },
+  };
 }
 
 /** Per-dir disk facts the resolver supplies so synthesis can go beyond colocation. */
 export interface DevTenantSeedOptions {
   /** Resolved appDomain for a slug tenant (from `.tot/config.json` scope). */
   scopeFor?: (id: string) => string | undefined;
-  /** Whether the checkout `id` (data scope `scope`) has a catalog on disk. */
-  hasCatalog?: (scope: string, id: string) => boolean;
   /** The tenant's parsed `tenants/<id>/analytics.json`, or undefined when it has none. */
   analyticsFor?: (id: string) => unknown;
 }
@@ -127,12 +115,12 @@ export interface DevTenantSeedOptions {
  * The dev tenants to seed ALONGSIDE staticTenants: one synthesized config per
  * local tenant dir that isn't already a static tenant (those keep their richer
  * hardcoded config). `themeFor` supplies each dir's theme tokens; `opts` carries
- * the per-dir disk facts (catalog presence, slug scope) the resolver reads.
+ * the per-dir disk facts (slug scope, analytics) the resolver reads.
  *
  * @param localDirIds dir names discovered under `tenants/*` (dir == tenant id)
  * @param staticIds   tenant_ids already in the static registry (skipped)
  * @param themeFor    theme-token lookup by dir/tenant id
- * @param opts        optional per-dir hints (scopeFor, hasCatalog)
+ * @param opts        optional per-dir hints (scopeFor, analyticsFor)
  */
 export function devTenantsToSeed(
   localDirIds: Iterable<string>,
@@ -146,10 +134,8 @@ export function devTenantsToSeed(
     if (!id || staticIds.has(id) || seen.has(id)) continue;
     seen.add(id);
     const appDomain = opts.scopeFor?.(id);
-    const scope = appDomain ?? id;
-    const hasCatalog = opts.hasCatalog?.(scope, id) ?? false;
     const analyticsRaw = opts.analyticsFor?.(id);
-    out.push(synthesizeDevTenant(id, themeFor(id), { appDomain, hasCatalog, analyticsRaw }));
+    out.push(synthesizeDevTenant(id, themeFor(id), { appDomain, analyticsRaw }));
   }
   return out;
 }

package/apps/storefront/src/config/resolver.ts

@@ -64,41 +64,6 @@ function localTenantDirIds(): string[] {
   return [...ids];
 }
 
-// Catalog fixtures committed on disk, keyed by data scope (== out/catalog dir
-// name). A dev tenant whose scope has fixtures is served as a real COMMERCE tenant
-// (see devTenantSeed); one without them degrades to a marketing home. Keys only —
-// the same fixtures the FixtureToTClient reads. Repo root is four up from config/.
-const catalogFixtureFiles = import.meta.glob(
-  "../../../../packages/migration/out/catalog/*/products.json",
-);
-
-// A checkout's own catalog files (ADR 0033): `tot dev` grafts the store's
-// `content/catalog/` here, and the catalog reader serves them.
-const storeCatalogFiles = import.meta.glob([
-  "../../../../tenants/*/content/catalog/products/*.json",
-  "../../../../tenants/e2e/*/content/catalog/products/*.json",
-]);
-
-/** Tenant dir ids whose checkout carries its own catalog files. */
-function storeCatalogIds(): Set<string> {
-  const ids = new Set<string>();
-  for (const key of Object.keys(storeCatalogFiles)) {
-    const id = tenantIdFromPath(key);
-    if (id) ids.add(id);
-  }
-  return ids;
-}
-
-/** Data scopes (== out/catalog dir names) that have committed catalog fixtures. */
-function catalogScopes(): Set<string> {
-  const scopes = new Set<string>();
-  for (const key of Object.keys(catalogFixtureFiles)) {
-    const scope = /\/out\/catalog\/([^/]+)\//.exec(key)?.[1];
-    if (scope) scopes.add(scope);
-  }
-  return scopes;
-}
-
 // A slug tenant (dir name != its domain) declares its resolvable appDomain in
 // the checkout's `.tot/config.json` `scope`. Read eagerly (tiny JSON) so synthesis
 // can resolve it at `/<domain>/`; trusted only when it looks like a hostname (has a
@@ -136,15 +101,12 @@ function slugScopes(): Map<string, string> {
 function devFallbackResolver(): TenantResolver {
   if (!import.meta.env.DEV) return staticResolver;
   const staticIds = new Set(staticTenants.map((t) => t.tenant_id));
-  const withCatalog = catalogScopes();
-  const withStoreCatalog = storeCatalogIds();
   const scopes = slugScopes();
   // The SAME tenant-owned analytics read the static registry uses; here it serves only
   // the tenants that have NO registry entry (see config/tenantAnalyticsFiles.ts).
   const analytics = tenantAnalyticsRawById();
   const dev = devTenantsToSeed(localTenantDirIds(), staticIds, getTenantTheme, {
     scopeFor: (id) => scopes.get(id),
-    hasCatalog: (scope, id) => withStoreCatalog.has(id) || withCatalog.has(scope),
     analyticsFor: (id) => analytics.get(id),
   });
   if (dev.length === 0) return staticResolver;

package/apps/storefront/src/layouts/Layout.astro

@@ -16,6 +16,7 @@ import QuickView from "@/components/islands/QuickView.tsx";
 import CheckoutLoader from "@/components/commerce/CheckoutLoader.astro";
 import CartDrawerStyles from "@/components/commerce/CartDrawerStyles.astro";
 import NicotineWarning from "@/components/compliance/NicotineWarning.astro";
+import PactActNotice from "@/components/compliance/PactActNotice.astro";
 import ShippingRestrictionNotice from "@/components/compliance/ShippingRestrictionNotice.astro";
 import IsolatedAgeGate from "@/components/islands/IsolatedAgeGate.tsx";
 import AuthBadge from "@/components/auth/AuthBadge.astro";
@@ -38,6 +39,8 @@ import { renderWidgetSlot } from "@/lib/apps/widgets/renderSlot.js";
 
 interface Props {
   title: string;
+  /** The page's own complete `<title>`, rendered verbatim (threaded to <Seo>). */
+  seoTitle?: string;
   description?: string;
   path: string;
   ogType?: "website" | "product" | "article";
@@ -80,6 +83,7 @@ interface Props {
 
 const {
   title,
+  seoTitle,
   description,
   path,
   ogType,
@@ -298,6 +302,7 @@ const footerWidgets = await renderWidgetSlot(
 
     <Seo
       title={title}
+      seoTitle={seoTitle}
       description={description}
       path={path}
       ogType={ogType}
@@ -331,7 +336,7 @@ const footerWidgets = await renderWidgetSlot(
 
     <AuthBadge />
 
-    {compliance?.nicotineWarning && <NicotineWarning variant="bar" />}
+    {compliance?.nicotineWarning && <NicotineWarning variant="bar" declaration={compliance.nicotineWarning} />}
 
     {sharedChrome ? (
       <Fragment set:html={sharedChrome.header} />
@@ -369,6 +374,7 @@ const footerWidgets = await renderWidgetSlot(
       <slot />
     </main>
 
+    <PactActNotice enabled={compliance?.pactAct} minAge={compliance?.minAge} variant="footer" />
     <ShippingRestrictionNotice text={compliance?.shippingRestriction} />
 
     {sharedChrome ? (
@@ -400,6 +406,7 @@ const footerWidgets = await renderWidgetSlot(
           }
           payments={chrome.footer.payments}
           social={chrome.footer.social}
+          disclaimer={chrome.footer.disclaimer}
           compliance={footerCompliance}
           legal={legalLine}
           bottomLinks={bottomLinks}

package/apps/storefront/src/lib/assets/preview-version-cookie.ts

@@ -1,10 +1,14 @@
 /**
- * Resolve the candidate/revision asset pin from preview cookies.
+ * Resolve the asset version a preview subresource reads.
  *
- * Candidate and revision renderers set `tot_preview_version` (the exact sha) and
- * `tot_preview` (capability token). Subresource GETs (img `/_a/…`, `/tenants/…`)
- * carry those cookies but not `__tot_candidate_pin`, so this is the revision
- * authority for revision-bound captured originals and preview assets.
+ * `resolvePreviewVersionFromCookies` is the candidate/revision pin: candidate and
+ * revision renderers set `tot_preview_version` (the exact sha) and `tot_preview`
+ * (capability token). Subresource GETs (img `/_a/…`, `/tenants/…`) carry those
+ * cookies but not `__tot_candidate_pin`, so this is the revision authority for
+ * revision-bound captured originals and preview assets.
+ *
+ * `resolveSharedPreviewAssetVersion` covers the shared preview, which sets no
+ * version cookie: it reads the version the preview channel serves.
  */
 import { verifyPreviewToken } from "@tot/public-runtime";
 
@@ -29,3 +33,46 @@ export async function resolvePreviewVersionFromCookies(input: {
   if (!verified.ok || verified.claims.tenantId !== input.tenantId) return null;
   return versionId;
 }
+
+/**
+ * Which asset snapshot a SHARED-preview subresource reads.
+ *
+ * The shared preview document renders the content `preview` channel's version — set
+ * by `reconcilePreview` and by the aggregate reconcile alike, and both ingest that
+ * version's `public/` subtree under the SAME versionId. So a subresource the preview
+ * document references must read that exact version too. It is NOT the assets `test`
+ * pointer: the aggregate reconcile ingests ingest-only and never moves it, so after
+ * "Add to release" that pointer names an older snapshot or nothing, and every tenant
+ * asset 404s under a page that rendered fine.
+ *
+ * A request is a shared-preview read when it is on the preview host (`previewHost`)
+ * or carries a valid `tot_preview` token for THIS tenant — the cookie the preview
+ * document sets from its `?__preview=` link, or the token on the asset URL itself.
+ * `versionId` is null for a non-preview read, or when the preview channel names no
+ * version yet (the caller then falls back to the assets `test` pointer).
+ */
+export async function resolveSharedPreviewAssetVersion(input: {
+  tenantId: string;
+  previewHost: boolean;
+  previewToken: string | null | undefined;
+  secret: string | null | undefined;
+  readPreviewChannelVersion: () => Promise<string | null>;
+  nowSeconds?: number;
+}): Promise<{ preview: boolean; versionId: string | null }> {
+  let preview = input.previewHost;
+  const token = input.previewToken?.trim() || null;
+  if (!preview && token && input.secret && input.tenantId) {
+    const verified = await verifyPreviewToken(
+      input.secret,
+      token,
+      input.nowSeconds ?? Math.floor(Date.now() / 1000),
+    );
+    preview = verified.ok && verified.claims.tenantId === input.tenantId;
+  }
+  if (!preview) return { preview: false, versionId: null };
+  const versionId = await input.readPreviewChannelVersion();
+  return {
+    preview: true,
+    versionId: versionId && SAFE_VERSION_ID.test(versionId) && !versionId.includes("..") ? versionId : null,
+  };
+}

package/apps/storefront/src/lib/blog/pagination.ts

@@ -8,41 +8,51 @@ export const DEFAULT_BLOG_PAGE_SIZE = 12;
  * an absent one falls back to a NEUTRAL default derived from the tenant's own
  * `displayName` — never Token of Trust's own copy (fb-1791301493691-brzl6f). A
  * tenant that wants ToT's current copy (tokenoftrust.com included) declares it
- * in its own `content/blog/settings.json`.
+ * in its own `content/blog/settings.json`. `eyebrow`/`tagline` are null when the
+ * tenant declared them empty: the index renders no element for them.
  */
 export interface BlogIndexCopy {
   title: string;
-  eyebrow: string;
-  tagline: string;
+  eyebrow: string | null;
+  tagline: string | null;
   description: string;
   pageSize: number;
 }
 
-function trimmed(value: string | undefined): string | undefined {
+function trimmed(value: string | null | undefined): string | undefined {
   const v = value?.trim();
   return v ? v : undefined;
 }
 
+/**
+ * An optional line of copy: declared text wins, a declared `""`/`null` suppresses it, and only an
+ * ABSENT field takes the default — so a migrated index that has no eyebrow or tagline can say so.
+ */
+function optionalCopy(value: string | null | undefined, fallback: string): string | null {
+  if (value === undefined) return fallback;
+  return trimmed(value) ?? null;
+}
+
 /**
  * Generic engine behind `resolveBlogIndexCopy` and every other per-tenant
  * collection index (e.g. `resolveTheBuildIndexCopy` in `../the-build/pagination.js`):
  * a declared settings field wins; an absent one falls back to the caller's own
  * NEUTRAL, tenant-derived default — never a Token of Trust-branded one
- * (fb-1791301493691-brzl6f, and its the-build sibling). `defaults.tagline` is
- * also the description fallback, matching every collection's settings schema.
+ * (fb-1791301493691-brzl6f, and its the-build sibling). The tagline (declared or
+ * default) is also the description fallback, matching every collection's settings schema.
  */
 export function resolveIndexCopy(
-  settings: { title?: string; eyebrow?: string; tagline?: string; description?: string; pageSize?: number } | null | undefined,
+  settings: Pick<BlogSettings, "title" | "eyebrow" | "tagline" | "description" | "pageSize"> | null | undefined,
   defaults: { title: string; eyebrow: string; tagline: string; description?: string },
   defaultPageSize: number,
 ): BlogIndexCopy {
-  const tagline = trimmed(settings?.tagline) ?? defaults.tagline;
+  const tagline = optionalCopy(settings?.tagline, defaults.tagline);
   const pageSize = settings?.pageSize;
   return {
     title: trimmed(settings?.title) ?? defaults.title,
-    eyebrow: trimmed(settings?.eyebrow) ?? defaults.eyebrow,
+    eyebrow: optionalCopy(settings?.eyebrow, defaults.eyebrow),
     tagline,
-    description: trimmed(settings?.description) ?? defaults.description ?? tagline,
+    description: trimmed(settings?.description) ?? defaults.description ?? tagline ?? defaults.tagline,
     pageSize: Number.isInteger(pageSize) && pageSize! > 0 ? pageSize! : defaultPageSize,
   };
 }

package/apps/storefront/src/lib/blog/presentation.ts

@@ -0,0 +1,94 @@
+import type { BlogSettings } from "./types.js";
+
+/**
+ * Which parts of the blog templates render, resolved from a collection's `settings.json`. Every
+ * part defaults ON; a tenant turns one off by declaring `false` (or `share: []`), so a migrated
+ * blog can match its source without hiding platform markup with CSS.
+ */
+export interface BlogPresentation {
+  hero: boolean;
+  topics: boolean;
+  postEyebrow: boolean;
+  dek: boolean;
+  aside: boolean;
+  reactions: boolean;
+  share: ShareTarget[];
+}
+
+/** Every share action the post template knows how to render. */
+export const SHARE_TARGETS = ["facebook", "email", "print", "x", "pinterest"] as const;
+export type ShareTarget = (typeof SHARE_TARGETS)[number];
+
+/** The share row a post renders when its collection declares no `share`. */
+export const DEFAULT_SHARE_TARGETS: readonly ShareTarget[] = SHARE_TARGETS;
+
+function isShareTarget(value: unknown): value is ShareTarget {
+  return typeof value === "string" && (SHARE_TARGETS as readonly string[]).includes(value);
+}
+
+/** Only an explicit `false` turns a part off; anything else keeps the platform default. */
+function on(value: unknown): boolean {
+  return value !== false;
+}
+
+export function resolveBlogPresentation(settings: BlogSettings | null | undefined): BlogPresentation {
+  const share = Array.isArray(settings?.share)
+    ? [...new Set(settings.share.filter(isShareTarget))]
+    : [...DEFAULT_SHARE_TARGETS];
+  return {
+    hero: on(settings?.hero),
+    topics: on(settings?.topics),
+    postEyebrow: on(settings?.postEyebrow),
+    dek: on(settings?.dek),
+    aside: on(settings?.aside),
+    reactions: on(settings?.reactions),
+    share,
+  };
+}
+
+/**
+ * The byline name, or null when the post names no author. A post without an author renders no
+ * byline at all: the platform never attributes a post to anyone its content does not name.
+ */
+export function bylineAuthor(author: string | null | undefined): string | null {
+  const name = author?.trim();
+  return name ? name : null;
+}
+
+export interface ShareLink {
+  target: ShareTarget;
+  /** Visible text. */
+  text: string;
+  /** Accessible name. */
+  label: string;
+  /** Null for `print`, which is a button the page script wires to `window.print()`. */
+  href: string | null;
+}
+
+const SHARE_COPY: Record<ShareTarget, { text: string; label: string }> = {
+  facebook: { text: "Facebook", label: "Share on Facebook" },
+  email: { text: "Email", label: "Share by email" },
+  print: { text: "Print", label: "Print this article" },
+  x: { text: "X", label: "Share on X" },
+  pinterest: { text: "Pinterest", label: "Pin on Pinterest" },
+};
+
+/**
+ * The share row for one post. `url` is the post's canonical URL, so a share from a preview host
+ * still points readers at the live article.
+ */
+export function shareLinks(
+  targets: readonly ShareTarget[],
+  post: { url: string; title: string; image?: string },
+): ShareLink[] {
+  const u = encodeURIComponent(post.url);
+  const t = encodeURIComponent(post.title);
+  const href: Record<ShareTarget, string | null> = {
+    facebook: `https://www.facebook.com/sharer/sharer.php?u=${u}`,
+    email: `mailto:?subject=${t}&body=${u}`,
+    print: null,
+    x: `https://x.com/intent/tweet?url=${u}&text=${t}`,
+    pinterest: `https://pinterest.com/pin/create/button/?url=${u}&description=${t}${post.image ? `&media=${encodeURIComponent(post.image)}` : ""}`,
+  };
+  return targets.map((target) => ({ target, ...SHARE_COPY[target], href: href[target] }));
+}

package/apps/storefront/src/lib/blog/rss.ts

@@ -68,7 +68,7 @@ export function renderRssFeed(input: RssFeedInput): string {
         `      <link>${escapeXml(link)}</link>`,
         `      <guid isPermaLink="true">${escapeXml(link)}</guid>`,
         pubDate ? `      <pubDate>${pubDate}</pubDate>` : "",
-        `      <dc:creator>${escapeXml(post.author)}</dc:creator>`,
+        post.author.trim() ? `      <dc:creator>${escapeXml(post.author.trim())}</dc:creator>` : "",
         `      <description>${escapeXml(post.excerpt)}</description>`,
         contentEncoded,
         categories,

package/apps/storefront/src/lib/blog/types.ts

@@ -45,21 +45,38 @@ export interface BlogPost extends BlogPostSummary {
 }
 
 /**
- * Optional per-tenant blog index copy + page size, sourced from
- * `tenants/<id>/content/blog/settings.json`. Every field is optional — an absent
- * field, or an absent file, resolves to a NEUTRAL default derived from the
+ * Optional per-tenant blog copy, page size and presentation, sourced from
+ * `tenants/<id>/content/<collection>/settings.json`. Every field is optional — an
+ * absent field, or an absent file, resolves to a NEUTRAL default derived from the
  * tenant's own `displayName` (see `resolveBlogIndexCopy` in `./pagination.ts`),
- * never Token of Trust's own copy. A tenant that wants its own branding
- * (tokenoftrust.com included) declares it here.
+ * never Token of Trust's own copy, and to the full platform presentation (see
+ * `resolveBlogPresentation` in `./presentation.ts`). A tenant that wants its own
+ * branding (tokenoftrust.com included) declares it here.
  */
 export interface BlogSettings {
   title?: string;
-  eyebrow?: string;
-  tagline?: string;
+  /** Index eyebrow. `""` or `null` renders none; absent uses the platform default. */
+  eyebrow?: string | null;
+  /** Index tagline. `""` or `null` renders none; absent uses the platform default. */
+  tagline?: string | null;
   description?: string;
   /** Posts per `/blog/` page. Must be a positive integer; anything else falls
    *  back to the platform default (`DEFAULT_BLOG_PAGE_SIZE`). */
   pageSize?: number;
+  /** Coloured band behind the index and tag/category/author archive headings. Default true. */
+  hero?: boolean;
+  /** "Explore topics" tag list beside the index grid. Default true. */
+  topics?: boolean;
+  /** Post eyebrow (the post's first tag above its title). Default true. */
+  postEyebrow?: boolean;
+  /** Post dek (the excerpt repeated under the title). Default true. */
+  dek?: boolean;
+  /** Post side column ("← All articles" + tag links). Default true; when false the tags follow the body. */
+  aside?: boolean;
+  /** Reader reaction bar under the post. Default true. */
+  reactions?: boolean;
+  /** Share row after the post's tags, in this order. `[]` renders none; absent uses `DEFAULT_SHARE_TARGETS`. */
+  share?: string[];
 }
 
 /**

package/apps/storefront/src/lib/breadcrumbs.ts

@@ -0,0 +1,25 @@
+import type { ChromeConfig } from "./chrome/model.js";
+
+/**
+ * One breadcrumb trail per page. A page builds it ONCE with `siteTrail` and hands the same array
+ * to the visible `<Breadcrumbs>` and to `breadcrumbLd`, so what a reader sees and what search
+ * engines read cannot disagree.
+ */
+export interface Crumb {
+  label: string;
+  /** Tenant-relative path; `<Breadcrumbs>` adds the base path, `breadcrumbLd` the canonical origin. */
+  href: string;
+}
+
+/** The first crumb's label when the tenant's chrome declares none. */
+export const DEFAULT_HOME_CRUMB_LABEL = "Home";
+
+/** The home crumb's label: the tenant's declared `chrome.json` `breadcrumbs.homeLabel`, else "Home". */
+export function homeCrumbLabel(chrome: Pick<ChromeConfig, "breadcrumbs"> | null | undefined): string {
+  return chrome?.breadcrumbs?.homeLabel?.trim() || DEFAULT_HOME_CRUMB_LABEL;
+}
+
+/** The full trail: the home crumb, then `crumbs` in order. The last crumb is the current page. */
+export function siteTrail(homeLabel: string, ...crumbs: Crumb[]): Crumb[] {
+  return [{ label: homeLabel, href: "/" }, ...crumbs];
+}

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

@@ -23,6 +23,10 @@ export {
   type FooterNewsletter,
   type ChromeBrand,
   type ChromeSearch,
+  HEADER_ACTION_KINDS,
+  type HeaderActionKind,
+  type ChromeHeaderActionLink,
+  type ChromeHeaderMobile,
   type ChromeUtilityNav,
   type ChromeAnnouncement,
   type ChromeAgeGate,

package/apps/storefront/src/lib/cloudflare-workers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The slice of the Workers runtime module `cloudflare:workers` this app uses.
+ *
+ * The storefront does not depend on @cloudflare/workers-types (its globals collide with the DOM
+ * lib Astro compiles against), so the Durable Object surface the pipeline needs is declared here.
+ * The module only resolves inside workerd; under Node it is imported lazily and guarded
+ * (`lib/runtimeEnv.ts`).
+ */
+declare module "cloudflare:workers" {
+  export type SqlStorageValue = ArrayBuffer | string | number | null;
+
+  export interface SqlStorageCursor<T extends Record<string, SqlStorageValue>> extends Iterable<T> {
+    toArray(): T[];
+    one(): T;
+    readonly rowsRead: number;
+    readonly rowsWritten: number;
+  }
+
+  export interface SqlStorage {
+    exec<T extends Record<string, SqlStorageValue>>(query: string, ...bindings: unknown[]): SqlStorageCursor<T>;
+  }
+
+  export interface DurableObjectStorage {
+    readonly sql: SqlStorage;
+    transactionSync<T>(closure: () => T): T;
+    getAlarm(): Promise<number | null>;
+    setAlarm(scheduledTime: number | Date): Promise<void>;
+    deleteAlarm(): Promise<void>;
+    sync(): Promise<void>;
+  }
+
+  export interface DurableObjectId {
+    toString(): string;
+    readonly name?: string;
+  }
+
+  export interface DurableObjectState {
+    readonly id: DurableObjectId;
+    readonly storage: DurableObjectStorage;
+    blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+    waitUntil(promise: Promise<unknown>): void;
+    abort(reason?: string): void;
+  }
+
+  export abstract class DurableObject<Env = unknown> {
+    protected readonly ctx: DurableObjectState;
+    protected readonly env: Env;
+    constructor(ctx: DurableObjectState, env: Env);
+    alarm?(alarmInfo?: { retryCount: number; isRetry: boolean }): void | Promise<void>;
+  }
+
+  export const env: Record<string, unknown>;
+}