@tokenoftrust/storefront-runner 4.4.0 → 4.6.0

package/agency-kit/tools/lib/catalog-model/files.mjs

@@ -18,8 +18,11 @@
  *   - `created_at` / `updated_at` / `migrated_at` / `source_checksum` are optional.
  *   - `variants[].inventory` is never read, and writers leave it out. Availability is hot data and
  *     lives behind the store's declared `inventory.provider`, never in a content file.
+ *   - `variants[].sku` follows the SKU contract (`./sku.mjs`): reader and writer trim it, a blank
+ *     one is no SKU, and one with a control character or over the length cap refuses the file.
  */
 import { validateRecord } from "./model.mjs";
+import { parseSku, skuFindings } from "./sku.mjs";
 
 /** Store-relative directories, one per record kind. */
 export const CATALOG_CONTENT_DIRS = {
@@ -66,14 +69,37 @@ export function classifyCatalogPath(relative) {
 
 // --- Writing ----------------------------------------------------------------------------------
 
-/** A record as its file holds it: every variant's `inventory` left out. */
+/**
+ * A variant's SKU in its stored form: trimmed, a blank one removed. A SKU the contract refuses is
+ * left as written so the validator names it.
+ */
+function storedSkuVariant(variant) {
+  if (!isObject(variant) || typeof variant.sku !== "string") return variant;
+  const parsed = parseSku(variant.sku);
+  if (parsed.ok) return parsed.sku === variant.sku ? variant : { ...variant, sku: parsed.sku };
+  if (parsed.reason !== "empty") return variant;
+  const { sku: _blank, ...rest } = variant;
+  return rest;
+}
+
+/** Every refused variant SKU in a product record, as validator issues. */
+function skuIssues(record) {
+  if (!isObject(record) || !Array.isArray(record.variants)) return [];
+  return record.variants.flatMap((variant, index) =>
+    isObject(variant) && variant.sku !== undefined
+      ? skuFindings(variant.sku).filter((f) => f.level === "error").map((f) => `variants[${index}].sku: ${f.message}`)
+      : [],
+  );
+}
+
+/** A record as its file holds it: every variant's `inventory` left out, every SKU stored form. */
 export function catalogFileRecord(kind, record) {
   if (kind !== "product" || !isObject(record) || !Array.isArray(record.variants)) return record;
   return {
     ...record,
     variants: record.variants.map((variant) => {
       if (!isObject(variant)) return variant;
-      const { inventory: _inventory, ...rest } = variant;
+      const { inventory: _inventory, ...rest } = storedSkuVariant(variant);
       return rest;
     }),
   };
@@ -157,7 +183,7 @@ function stamp(kind, doc, tenantScope, availability) {
     const productId = typeof doc.id === "string" ? doc.id : "";
     out.variants = doc.variants.map((variant) =>
       isObject(variant)
-        ? { ...variant, tenant_id: tenantScope, product_id: productId, inventory: { ...availability } }
+        ? { ...storedSkuVariant(variant), tenant_id: tenantScope, product_id: productId, inventory: { ...availability } }
         : variant,
     );
   }
@@ -185,6 +211,7 @@ function parse(relative, raw, tenantScope, availability) {
   const issues = validateRecord(where.kind === "product" ? "CatalogProduct" : "CatalogCollection", record).map(
     (i) => (i.path ? `${i.path}: ${i.message}` : i.message),
   );
+  if (where.kind === "product") issues.push(...skuIssues(record));
   if (isObject(doc) && typeof doc.handle === "string" && doc.handle !== where.handle) {
     issues.push(`handle: "${doc.handle}" does not match the file name "${where.handle}.json"`);
   }

package/agency-kit/tools/lib/catalog-model/sku.d.mts

@@ -0,0 +1,16 @@
+export const SKU_MAX_LENGTH: number;
+export const CHECKOUT_CODE_MAX_LENGTH: number;
+export const SKU_TOKEN_MAX_LENGTH: number;
+export type SkuRefusal = "not-string" | "empty" | "control-character" | "too-long";
+export function parseSku(value: unknown): { ok: true; sku: string } | { ok: false; reason: SkuRefusal };
+export function isStoredSku(value: unknown): value is string;
+export function skuKey(sku: string): string;
+export function skuToken(sku: string): string;
+export function skuFromToken(token: unknown): string | null;
+export interface SkuFinding {
+  level: "error" | "warning";
+  code: string;
+  message: string;
+}
+export function skuFindings(value: unknown): SkuFinding[];
+export function skuCollisions<T extends { sku: string }>(entries: Iterable<T>): Array<{ key: string; entries: T[] }>;

package/agency-kit/tools/lib/catalog-model/sku.mjs

@@ -0,0 +1,146 @@
+/**
+ * The SKU contract: one rule for every reader and writer of a merchant's SKU.
+ *
+ * A SKU is merchant data, kept exactly as the merchant wrote it. The only rewrite is trimming
+ * leading and trailing whitespace on the way in. A SKU is refused only when it is empty, carries a
+ * control character, or is longer than {@link SKU_MAX_LENGTH} characters. Anything else, a space
+ * included, is a valid SKU; a space is a lint warning, never an error.
+ *
+ * Two SKUs are the same SKU when their {@link skuKey} is equal: trimmed, NBSP read as a space, and
+ * case-folded. The key is for comparison only and is never stored.
+ *
+ * A SKU is never used raw where a boundary needs a safe token (a path, a file name, a URL segment,
+ * a checkout product code). {@link skuToken} is the one encoding for those boundaries: reversible,
+ * injective, and the identity for a SKU of letters, digits, `.`, `_` and `-`.
+ *
+ * Pure: no filesystem, no network, no dependencies. `packages/cli/src/sku.mjs` is a byte-identical
+ * copy (the CLI installs without the kit), pinned by `packages/cli/test/sku-copy.test.mjs`.
+ */
+
+/** Longest SKU accepted, in characters (code points). */
+export const SKU_MAX_LENGTH = 250;
+/** The checkout provider's product-code limit; a longer {@link skuToken} is a lint warning. */
+export const CHECKOUT_CODE_MAX_LENGTH = 200;
+/** Longest {@link skuToken} any SKU can produce (four UTF-8 bytes, three characters each). */
+export const SKU_TOKEN_MAX_LENGTH = SKU_MAX_LENGTH * 12;
+
+const CONTROL = /\p{Cc}/u;
+const WHITESPACE = /\s/u;
+const TOKEN_SAFE = /^[A-Za-z0-9._-]$/;
+const TOKEN = /^(?:[A-Za-z0-9._-]|%[0-9A-F]{2})+$/;
+
+/**
+ * Read a SKU as it arrives from a merchant, a file or an import.
+ *
+ * @param {unknown} value
+ * @returns {{ ok: true, sku: string } | { ok: false, reason: "not-string" | "empty" | "control-character" | "too-long" }}
+ */
+export function parseSku(value) {
+  if (typeof value !== "string") return { ok: false, reason: "not-string" };
+  const sku = value.trim();
+  if (sku === "") return { ok: false, reason: "empty" };
+  if (CONTROL.test(sku)) return { ok: false, reason: "control-character" };
+  if ([...sku].length > SKU_MAX_LENGTH) return { ok: false, reason: "too-long" };
+  return { ok: true, sku };
+}
+
+/** True when `value` is a SKU in its stored form: valid and already trimmed. */
+export function isStoredSku(value) {
+  const parsed = parseSku(value);
+  return parsed.ok && parsed.sku === value;
+}
+
+/** The comparison key two SKUs share when they are the same SKU. Never stored. */
+export function skuKey(sku) {
+  return String(sku).replace(/ /g, " ").trim().toLowerCase();
+}
+
+/**
+ * The SKU as a token safe in a path, file name, URL segment or checkout product code. Letters,
+ * digits, `.`, `_` and `-` pass through; every other character is its UTF-8 bytes as `%XX`.
+ */
+export function skuToken(sku) {
+  let out = "";
+  for (const char of String(sku)) {
+    if (TOKEN_SAFE.test(char)) {
+      out += char;
+      continue;
+    }
+    for (const byte of new TextEncoder().encode(char)) out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+  }
+  return out;
+}
+
+/** The stored SKU a {@link skuToken} encodes, or null when `token` is not one. */
+export function skuFromToken(token) {
+  if (typeof token !== "string" || token.length > SKU_TOKEN_MAX_LENGTH || !TOKEN.test(token)) return null;
+  const bytes = [];
+  for (let i = 0; i < token.length; i += 1) {
+    if (token[i] === "%") {
+      bytes.push(Number.parseInt(token.slice(i + 1, i + 3), 16));
+      i += 2;
+    } else {
+      bytes.push(token.charCodeAt(i));
+    }
+  }
+  // Bytes that are not UTF-8 decode to U+FFFD, whose token differs, so the round trip refuses them.
+  const sku = new TextDecoder().decode(new Uint8Array(bytes));
+  return isStoredSku(sku) && skuToken(sku) === token ? sku : null;
+}
+
+const REASONS = {
+  "not-string": "a SKU must be text",
+  empty: "a SKU cannot be empty",
+  "control-character": "a SKU cannot contain a control character (tab, newline, ...)",
+  "too-long": `a SKU is at most ${SKU_MAX_LENGTH} characters`,
+};
+
+/**
+ * Lint findings for one SKU. `error` means the SKU is refused; `warning` means it works.
+ *
+ * @param {unknown} value
+ * @returns {Array<{ level: "error" | "warning", code: string, message: string }>}
+ */
+export function skuFindings(value) {
+  const parsed = parseSku(value);
+  if (!parsed.ok) return [{ level: "error", code: `sku-${parsed.reason}`, message: REASONS[parsed.reason] }];
+  /** @type {Array<{ level: "error" | "warning", code: string, message: string }>} */
+  const findings = [];
+  if (parsed.sku !== value) {
+    findings.push({ level: "warning", code: "sku-untrimmed", message: "leading or trailing whitespace is trimmed when the SKU is read" });
+  }
+  if (WHITESPACE.test(parsed.sku)) {
+    findings.push({
+      level: "warning",
+      code: "sku-whitespace",
+      message: "works, but we recommend against spaces in a SKU: spreadsheets, scanners and other systems often trim or split on them",
+    });
+  }
+  if (skuToken(parsed.sku).length > CHECKOUT_CODE_MAX_LENGTH) {
+    findings.push({
+      level: "warning",
+      code: "sku-checkout-code-long",
+      message: `its checkout product code is longer than ${CHECKOUT_CODE_MAX_LENGTH} characters, which the checkout provider may refuse`,
+    });
+  }
+  return findings;
+}
+
+/**
+ * SKUs that are the same SKU under {@link skuKey}. Each group lists every entry that shares a key.
+ *
+ * @template {{ sku: string }} T
+ * @param {Iterable<T>} entries
+ * @returns {Array<{ key: string, entries: T[] }>}
+ */
+export function skuCollisions(entries) {
+  /** @type {Map<string, T[]>} */
+  const groups = new Map();
+  for (const entry of entries) {
+    const key = skuKey(entry.sku);
+    const group = groups.get(key);
+    if (group) group.push(entry);
+    else groups.set(key, [entry]);
+  }
+  return [...groups].filter(([, group]) => group.length > 1).map(([key, group]) => ({ key, entries: group }));
+}

package/apps/storefront/src/components/catalog/storefront/plp/FacetSidebar.astro

@@ -7,7 +7,7 @@
  * Encoding handled by src/lib/publication/shared/url.ts (opt.<Name>=<value>, tag=, price, avail).
  */
 import type { Facet, ListProductsQuery } from "@tot/public-runtime";
-import { toggleFacet, buildQueryString, isPriceBucketActive, togglePriceBucket } from "@/lib/publication/shared/url";
+import { toggleFacet, splitFacetValues, buildQueryString, isPriceBucketActive, togglePriceBucket } from "@/lib/publication/shared/url";
 import { PRICE_BUCKETS, bucketByKey } from "@/lib/catalog/shared/priceBuckets";
 
 interface Props {
@@ -52,17 +52,29 @@ const clearHref =
 
   <div class="space-y-7">
     {
-      ordered.map((facet) => (
-        <fieldset>
-          <legend class="mb-2.5 font-display text-[0.95rem] font-medium">
-            {facet.name === "tags"
-              ? "Tags"
-              : facet.name === "availability"
-              ? "Availability"
-              : facet.name}
-          </legend>
+      ordered.map((facet) => {
+        const hasSelected = facet.values.some((fv) => selected(facet.name, fv.value));
+        const label =
+          facet.name === "tags" ? "Tags" : facet.name === "availability" ? "Availability" : facet.name;
+        // The first values (plus any selected one) are listed; the rest sit in a nested
+        // "Show more" <details>. A selected value is never in the remainder.
+        const { shown, rest } = splitFacetValues(facet.values, (v) => selected(facet.name, v));
+        const segments = [
+          { more: false, values: shown },
+          ...(rest.length > 0 ? [{ more: true, values: rest }] : []),
+        ];
+        return (
+        <details open={hasSelected} data-facet-group={facet.name}>
+          <summary class="mb-2.5 cursor-pointer font-display text-[0.95rem] font-medium">
+            {label} ({facet.values.length})
+          </summary>
+          {segments.map((seg) => {
+          const Wrap = seg.more ? "details" : Fragment;
+          return (
+          <Wrap>
+          {seg.more && <summary class="cursor-pointer py-1 text-xs text-[var(--color-muted)]">Show more</summary>}
           <ul class="space-y-1.5">
-            {facet.values.map((fv) => {
+            {seg.values.map((fv) => {
               const isSel = selected(facet.name, fv.value);
               const href =
                 basePath + toggleFacet(query, facet.name, fv.value);
@@ -101,8 +113,12 @@ const clearHref =
               );
             })}
           </ul>
-        </fieldset>
-      ))
+          </Wrap>
+          );
+          })}
+        </details>
+        );
+      })
     }
 
     {/* Price range — bucketed quick-select (live counts) + a free-text form

package/apps/storefront/src/components/content/storefront/chrome/SiteHeader.astro

@@ -64,6 +64,12 @@ interface Props {
    */
   layout?: HeaderVariant;
   sticky?: boolean;
+  /**
+   * Render the brand link inside `<h1 class="brand-h1">` (margin:0; font:inherit).
+   * The caller sets it on the home route only, and only when the page content
+   * supplies no h1 of its own — exactly one h1 per page.
+   */
+  brandAsH1?: boolean;
   class?: string;
 }
 
@@ -85,6 +91,7 @@ const {
   variant = "light",
   layout = "primary",
   sticky = true,
+  brandAsH1 = false,
   class: className,
 } = Astro.props;
 
@@ -96,7 +103,16 @@ const dark = variant === "dark";
 const minimal = layout === "minimal";
 const compact = layout === "compact-centered";
 
-const ctaClass = (v?: string) =>
+// Home brand heading: the brand link sits inside <h1 class="brand-h1"> (look unchanged);
+// the compact layout's positioning classes move to the h1, which is then the grid child.
+const brandCompactClass =
+  "absolute left-1/2 -translate-x-1/2 md:static md:translate-x-0 md:justify-self-center";
+const BrandWrap = brandAsH1 ? "h1" : Fragment;
+const brandWrapProps = brandAsH1
+  ? { class: ["brand-h1", compact && brandCompactClass].filter(Boolean).join(" "), style: "margin:0;font:inherit" }
+  : {};
+
+const ctaClass =(v?: string) =>
   v === "secondary" || v === "ghost"
     ? "inline-flex items-center rounded-full border border-current px-4 py-2 font-display text-sm font-medium transition-opacity hover:opacity-80"
     : "inline-flex items-center rounded-full bg-accent px-4 py-2 font-display text-sm font-medium text-accent-contrast transition-transform hover:-translate-y-0.5";
@@ -151,11 +167,12 @@ const currentPath = Astro.url.pathname;
         )
       }
       <!-- Logo / wordmark -->
+      <BrandWrap {...brandWrapProps}>
       <a
         href={homeHref}
         class:list={[
           "flex shrink-0 items-center transition-opacity hover:opacity-80",
-          compact && "absolute left-1/2 -translate-x-1/2 md:static md:translate-x-0 md:justify-self-center",
+          !brandAsH1 && compact && brandCompactClass,
         ]}
         aria-label={logo?.alt ?? wordmark ?? "Home"}
       >
@@ -203,6 +220,7 @@ const currentPath = Astro.url.pathname;
           )
         }
       </a>
+      </BrandWrap>
 
       <!-- Search (live typeahead island) -->
       {

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

@@ -29,7 +29,14 @@ import { organizationLd, websiteLd } from "@/lib/content/shared/jsonld";
 import { composeStructuredData, structuredDataProfile, type StructuredDataPage } from "@/lib/content/seo/structuredData";
 import { canonicalUrl } from "@/lib/content/seo/urlForm";
 import { documentTitle } from "@/lib/content/seo/documentTitle";
-import { nonceInlineTags, prefixSharedChrome, CHROME_BODY_MARKER } from "@/lib/content/shared/rawMarketingHtml";
+import {
+  nonceInlineTags,
+  prefixSharedChrome,
+  CHROME_BODY_MARKER,
+  demoteBrandH1,
+  hasContentH1,
+  isHomePath,
+} from "@/lib/content/shared/rawMarketingHtml";
 import { withBase } from "@/lib/publication/shared/basePath";
 import { CHROME_BEHAVIOR_JS, CHROME_HEAD_JS, sanitizeSharedChromeFragment } from "@/lib/content/shared/rawChrome";
 import { ASYNC_CSS_SWAP_JS } from "@/lib/content/shared/asyncCss";
@@ -218,6 +225,16 @@ if (chromeHtml && chromeHtml.includes(CHROME_BODY_MARKER)) {
   };
 }
 
+// One-h1 contract: on the home route the header brand is the page's <h1> unless the
+// page content supplies its own (then the brand stays a plain link). Only home
+// renders the slot to a string to inspect it.
+const isHome = isHomePath(path);
+const homeSlotHtml = isHome ? await Astro.slots.render("default") : null;
+const brandIsH1 = isHome && !hasContentH1(homeSlotHtml ?? "");
+if (sharedChrome && !brandIsH1) {
+  sharedChrome.header = demoteBrandH1(sharedChrome.header);
+}
+
 const compliance = tenant.compliance;
 const sections = complianceSections({
   compliance,
@@ -395,6 +412,7 @@ const footerWidgets = await renderWidgetSlot(
             nav={chrome.header.nav}
             variant={headerDark ? "dark" : "light"}
             layout={resolvedHeaderVariant}
+            brandAsH1={brandIsH1}
             announcement={chrome.header.announcement?.messages[0]}
             searchAction={
               features.productSearch
@@ -415,7 +433,7 @@ const footerWidgets = await renderWidgetSlot(
     )}
 
     <main id="main">
-      <slot />
+      {homeSlotHtml !== null ? <Fragment set:html={homeSlotHtml} /> : <slot />}
     </main>
 
     {sections.includes("pact-act") && (

package/apps/storefront/src/lib/checkout/commerce/finalCartAuthorization.ts

@@ -30,6 +30,15 @@ export interface SeamView {
   codes?: readonly string[];
   /** Flavor labels that triggered a `flavored_prohibited` block, for the refusal. */
   flavors?: readonly string[];
+  /** Every refused block with the compliance engine's own shopper-facing sentence. */
+  lines?: readonly RefusedLine[];
+}
+
+export interface RefusedLine {
+  code: string;
+  message: string;
+  sku?: string;
+  title?: string;
 }
 
 export interface FinalCartRequest {