@usequeek/theme-kit 0.1.21 → 0.1.23

package/types/vendor.ts

@@ -7,13 +7,11 @@ export interface BrandFont {
 }
 
 /**
- * Semantic design-token shapes — the FROZEN contract
- * (`.agent/.tmp/design-token-contract.md` in queek_backend). Backend resolves
- * theme defaults ← legacy vendor fields ← vendor `tokens` overrides and
- * returns this object under `StorefrontConfig.tokens`. Every field is
- * optional: during the transition many vendors have no `tokens` at all, and
- * the storefront injector (`lib/core/utils/brand.ts`) fills every gap with a
- * sane default so it can never crash or omit a CSS var.
+ * Semantic design-token shapes. The API resolves theme defaults ← legacy
+ * vendor fields ← vendor `tokens` overrides and returns this object under
+ * `StorefrontConfig.tokens`. Every field is optional: many vendors have no
+ * `tokens` at all, and the token injector (`utils/brand.ts`) fills every gap
+ * with a sane default so it can never crash or omit a CSS var.
  */
 export type DesignColorScheme = 'light' | 'dark';
 export type DesignScaleRatio = 1.125 | 1.2 | 1.25 | 1.333;
@@ -94,9 +92,9 @@ export type DesignTokenAxis = keyof DesignTokens;
  * container's radius is a hardcoded literal, or a button's border reads
  * `--border-weight` while its radius doesn't. Declaring only the dimension name
  * (e.g. `'shape'`) would show a dead sub-dial next to a live one — this is the
- * exact 2026-08-03 gap found in Allure's products/carousel section (Image radius
- * and Corner radius dead, Image fit/filter and Border weight live, all under the
- * same 'shape'/'image' bundle). `type`/`elevation`/`motion` have no UI sub-controls
+ * exact gap of a products/carousel section whose Image radius and Corner radius
+ * were dead while Image fit/filter and Border weight were live, all under the
+ * same 'shape'/'image' bundle. `type`/`elevation`/`motion` have no UI sub-controls
  * today, so they stay bare (no `.field` suffix) — add one here the day a sub-dial
  * is added for them.
  */
@@ -185,7 +183,7 @@ export interface StorefrontConfig {
     heading?: string;
     body?: string;
   };
-  /** Resolved semantic design tokens (see design-token-contract.md). Absent for stores not yet migrated. */
+  /** Resolved semantic design tokens. Absent for stores that have none. */
   tokens?: DesignTokens | null;
   menus?: {
     header?: Menu;
@@ -235,7 +233,7 @@ export interface StorefrontConfig {
       heading?: string;
       tagline?: string;
       cta?: string;
-      /** `modal` variant only — when it should pop up. Backend field pending; defaults to 'scroll' when unset. */
+      /** `modal` variant only — when it should pop up. Defaults to 'scroll' when unset. */
       trigger?: 'immediate' | 'delay' | 'scroll';
     };
   };

package/utils/announcement.ts

@@ -1,9 +1,9 @@
 /**
- * The announcement bar is ONE text field on the backend
+ * The announcement bar is ONE text field on the API
  * (`header.announcement.text`). A vendor writes several messages into it
  * separated by `|` or a line break and the bar rotates them; a single
- * message renders static. Roast's masthead set the convention; the merchant
- * editor and Qee teach it. Split here, once, so every theme rotates the same
+ * message renders static. The merchant editor and Qee teach this convention.
+ * Split here, once, so every theme rotates the same
  * list — a theme-local split meant the other themes showed the literal pipes
  * after a switch.
  */

package/utils/benefit-icon.tsx

@@ -1,13 +1,12 @@
 import type { JSX } from 'react';
 /**
- * Shared icon-keyword vocabulary for "benefit row" content blocks (glow's
- * `trust-badges`, any theme's `features-columns`, and similar icon+title+text
- * item lists). qee generates a short keyword per item (e.g. "star", "truck"),
+ * Shared icon-keyword vocabulary for "benefit row" content blocks (a theme's
+ * `trust-badges` or `features-columns`, and similar icon+title+text item
+ * lists). Qee generates a short keyword per item (e.g. "star", "truck"),
  * never raw SVG markup — themes render that keyword through this resolver
- * instead of each theme re-declaring its own switch (glow and allure both
- * had one, independently, before this was extracted) or a theme trying to
- * `dangerouslySetInnerHTML` the keyword directly (renders as literal text,
- * not an icon — the bug that prompted this).
+ * instead of each theme re-declaring its own switch, or trying to
+ * `dangerouslySetInnerHTML` the keyword directly (that renders as literal
+ * text, not an icon).
  *
  * `currentColor` throughout — the caller controls color via CSS `color` on
  * an ancestor, same convention every existing usage already followed.
@@ -88,8 +87,8 @@ const PATHS: Record<BenefitIconKey, JSX.Element> = {
   ),
 };
 
-// Synonyms qee has actually generated in practice for a key in BENEFIT_ICON_KEYS
-// (confirmed live: "truck" for a shipping/delivery benefit) — the AI is given
+// Synonyms Qee is known to generate for a key in BENEFIT_ICON_KEYS (for example
+// "truck" for a shipping/delivery benefit) — the AI is given
 // the canonical keyword list in the manifest/prompt, but a close synonym
 // should still resolve to the right icon instead of silently falling back.
 const ALIASES: Record<string, BenefitIconKey> = {
@@ -103,8 +102,7 @@ const ALIASES: Record<string, BenefitIconKey> = {
   quality: 'star',
   payment: 'wallet',
   price: 'wallet',
-  // Carried over from glow's pre-shared TrustIcon switch — real demo data
-  // and, presumably, real qee-generated pages already use this word.
+  // Already used by existing demo data and generated pages.
   sustainability: 'leaf',
 };
 

package/utils/brand.ts

@@ -20,10 +20,8 @@ import type {
 
 /**
  * Storefront design-token injector — turns the resolved semantic `tokens`
- * object (design-token-contract.md, queek_backend `.agent/.tmp/`) into the
- * full CSS custom-property set every theme reads. Replaces the old
- * `getBrandCssVariables`, which only ever emitted ~12 of the 24 color roles
- * (the bug this fixes).
+ * object into the full CSS custom-property set every theme reads, covering
+ * all 24 color roles.
  *
  * `expandDesignTokens` is the pure, unit-tested core: given ANY partial (or
  * absent) token object it fills every gap with a sane default and always
@@ -34,7 +32,7 @@ import type {
  * legacy `config.colors` / `brand.colors` / `brand.font` ← defaults) and
  * hands them to `expandDesignTokens`, then layers on the handful of
  * chrome vars (`--brand-footer-*`, explicit legacy button overrides) that
- * live outside the token contract so existing stores render identically.
+ * live outside the token set so existing stores render identically.
  */
 
 const DEFAULT_COLOR: Required<DesignTokenColor> = {
@@ -120,7 +118,7 @@ const CASE_MAP: Record<DesignHeadingCase, string> = {
 
 /**
  * Deliberately its OWN fixed scale, not a reference into RADIUS_SCALE/
- * shape.radius. Live-caught (15/8/26): when `--image-radius` pointed at
+ * shape.radius. When `--image-radius` pointed at
  * `var(--radius-sm/md/lg)`, a vendor on the (very common) 'sharp' global
  * Shape preset saw EVERY image-radius choice — sharp, soft, AND rounded —
  * collapse to the same 0px, since 'sharp' flattens the whole sm/md/lg
@@ -215,8 +213,7 @@ function contrastRatio(hexA: string, hexB: string): number | null {
 }
 
 /** WCAG AA body-text minimum. Below this, `accent`/`on_accent` reads as
- *  the same color rather than text-on-a-surface (the Taylor/glow incident:
- *  a vendor's legacy `colors.accent` override went to near-black while
+ *  the same color rather than text-on-a-surface (for example, a vendor's legacy `colors.accent` override went to near-black while
  *  `on_accent` silently kept the theme's own default — also near-black,
  *  since it was tuned to pair with THAT theme's accent, not the vendor's). */
 const MIN_ON_ACCENT_CONTRAST = 4.5;
@@ -474,7 +471,7 @@ function legacyTokensFromConfig(brand?: Brand | null, config?: StorefrontConfig
 }
 
 /**
- * Resolution order per the contract: `config.tokens` (per-group) ←
+ * Resolution order: `config.tokens` (per-group) ←
  * legacy fields ← (handled by `expandDesignTokens`'s own defaults).
  */
 function resolveEffectiveTokens(brand?: Brand | null, config?: StorefrontConfig | null): DesignTokens {
@@ -497,7 +494,7 @@ function resolveEffectiveTokens(brand?: Brand | null, config?: StorefrontConfig
 /**
  * Resolve brand CSS variables for the `provider.tsx` wrapper. Emits the
  * full token-derived var set (see `expandDesignTokens`), then layers on
- * the legacy chrome/override vars that sit outside the token contract:
+ * the legacy chrome/override vars that sit outside the token set:
  * footer colors and an explicit `config.colors.button(_text)` override
  * (pre-tokens stores could set a button color independent of `primary`).
  */

package/utils/format.ts

@@ -4,11 +4,10 @@
  * down to 0, so it silently truncated EVERY fractional-naira amount to a
  * whole number, everywhere in the storefront. A ₦0.28 balance (e.g. a tiny
  * residual left after a near-100% discount) displayed as "₦0" — the customer
- * saw a free checkout, then got asked to actually pay something. POS already
- * shows real money correctly (lib/currency.ts: minimumFractionDigits: 2,
- * maximumFractionDigits: 2, always).
+ * saw a free checkout, then got asked to actually pay something. The POS
+ * always shows two decimals.
  *
- * Deliberately NOT matching POS's always-2-decimals contract here: the
+ * Deliberately NOT matching the POS's always-2-decimals format here: the
  * overwhelming majority of storefront prices are whole naira, and putting
  * ".00" on every single one would be a large, unrequested visual change
  * across every theme. `minimumFractionDigits: 0, maximumFractionDigits: 2`
@@ -51,8 +50,7 @@ function displayTagFor(
 /**
  * A date for display (default "14 Feb 2026"), identical on server and browser.
  * '' if unparseable. The locale parameter is routed through the canonical
- * mapping (founder 2/10/26: English is British/Nigerian order, never US
- * order), so even an explicit 'en'/'en-US' renders "15 February 2026" — no
+ * mapping (English is British/Nigerian order, never US order), so even an explicit 'en'/'en-US' renders "15 February 2026" — no
  * exported formatter lets an 'en*' tag reach Intl unmapped.
  */
 export function formatDisplayDate(
@@ -137,7 +135,7 @@ export const PLATFORM_DEFAULT_CURRENCY = 'NGN';
  * The ONE currency-code resolver: trims/uppercases the item or vendor code,
  * accepts it when it is a 3-letter code, and returns the platform default
  * otherwise. List-level `meta.currency` is never consulted — it stamps the
- * platform default even on non-NGN stores (api-currency-contract-fix).
+ * platform default even on non-NGN stores.
  */
 export function normalizeCurrencyCode(value: unknown, fallback: string = PLATFORM_DEFAULT_CURRENCY): string {
   const code = typeof value === 'string' ? value.trim().toUpperCase() : '';

package/utils/image-srcset.ts

@@ -22,10 +22,10 @@ export interface ResolvedImageSources {
 
 const NONE: ResolvedImageSources = { src: undefined, srcSet: undefined, sizes: undefined };
 
-/** Ascending by cap. `thumb` is excluded by contract rule 5; `original` is
+/** Ascending by cap. `thumb` is excluded because it has no width; `original` is
  *  excluded on purpose — it is uncapped and unoptimized (raw jpg/png, possibly
  *  6000px), so letting a browser pick it off a srcset is the exact regression
- *  this whole effort exists to remove. `original` survives only as a last-resort
+ *  the tier map exists to prevent. `original` survives only as a last-resort
  *  `src` for the `raw` intent and as the onError step-2 retry. */
 const SRCSET_TIERS = ['card', 'card2x', 'view'] as const;
 type SrcSetTier = (typeof SRCSET_TIERS)[number];

package/utils/locale-switch.ts

@@ -0,0 +1,208 @@
+/**
+ * Language-switch URL rules — pure (no `next/*`, no React) so the hook, the
+ * component and any node tooling share one implementation.
+ *
+ * Routing shape of a storefront with several languages:
+ *
+ * - The store's DEFAULT language is served at the store root (`path_prefix`
+ *   is `''`).
+ * - Every other language — English included when it is not the default —
+ *   lives under its bare lower-case code: `/fr`, `/en`, `/zh-cn`.
+ * - Slugs are never translated, so a page keeps the same path under every
+ *   prefix.
+ * - `StorefrontProvider`'s `basePath` already carries the ACTIVE language
+ *   prefix (`/store/fr` on a path-based host, `/fr` on a store domain), so
+ *   links built from it stay in the shopper's language. `localeHref` takes
+ *   that into account.
+ */
+
+/** One language a store serves — the row shape the locales endpoint returns. */
+export interface StoreLocale {
+  /** Language code, e.g. `en`, `fr`, `zh-CN`. */
+  locale: string;
+  /** English name, e.g. `French`. */
+  name: string;
+  /** The language's own name, e.g. `Français`. */
+  native_name: string;
+  /** The store's content (source) language. */
+  is_primary: boolean;
+  /** Served at the store root. Exactly one language is the default. */
+  is_default: boolean;
+  /** URL prefix: `''` on the default language, the bare lower-case code otherwise. */
+  path_prefix: string;
+  hreflang: string;
+  html_lang: string;
+  /** `'rtl'` or `'ltr'`. */
+  dir: string;
+}
+
+/**
+ * What `StorefrontProvider` accepts for `locales`: a `StoreLocale` list as
+ * the storefront already holds it, or an older payload that lacks
+ * `is_default` (then the primary language is the default). Extra fields are
+ * tolerated and dropped.
+ */
+export interface StoreLocaleInput {
+  locale: string;
+  name?: string;
+  native_name?: string;
+  is_primary?: boolean;
+  is_default?: boolean;
+  path_prefix?: string;
+  hreflang?: string;
+  html_lang?: string;
+  dir?: string;
+}
+
+const FALLBACK_LOCALE_CODE = 'en';
+
+/**
+ * Validates and normalises a locales payload into `StoreLocale` rows.
+ *
+ * - Rows without a string `locale` are dropped; a repeated code keeps its
+ *   first row.
+ * - `is_default` missing (older backend) is derived from `is_primary`.
+ * - Exactly one row stays default: the first flagged one, else the primary,
+ *   else the first row. It sorts first (others keep their order) and its
+ *   prefix is forced to `''`; every other prefix is lower-cased, and an
+ *   empty one becomes the bare lower-case code.
+ * - Nothing usable → `[]`, which the hook and component read as "single
+ *   language: no switcher".
+ */
+export function normalizeStoreLocales(input: readonly StoreLocaleInput[] | null | undefined): StoreLocale[] {
+  if (!Array.isArray(input)) return [];
+
+  const seen = new Set<string>();
+  const rows: StoreLocale[] = [];
+  for (const row of input as readonly StoreLocaleInput[]) {
+    if (!row || typeof row.locale !== 'string' || row.locale.length === 0) continue;
+    const key = row.locale.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const isPrimary = row.is_primary === true;
+    rows.push({
+      locale: row.locale,
+      name: typeof row.name === 'string' && row.name ? row.name : row.locale,
+      native_name: typeof row.native_name === 'string' && row.native_name ? row.native_name : (typeof row.name === 'string' && row.name ? row.name : row.locale),
+      is_primary: isPrimary,
+      is_default: typeof row.is_default === 'boolean' ? row.is_default : isPrimary,
+      path_prefix: typeof row.path_prefix === 'string' ? row.path_prefix.toLowerCase() : '',
+      hreflang: typeof row.hreflang === 'string' && row.hreflang ? row.hreflang : row.locale,
+      html_lang: typeof row.html_lang === 'string' && row.html_lang ? row.html_lang : row.locale,
+      dir: row.dir === 'rtl' ? 'rtl' : 'ltr',
+    });
+  }
+  if (rows.length === 0) return [];
+
+  const defaultRow = rows.find((row) => row.is_default) ?? rows.find((row) => row.is_primary) ?? rows[0];
+  const normalized = rows.map((row) => {
+    const isDefault = row === defaultRow;
+    return {
+      ...row,
+      is_default: isDefault,
+      path_prefix: isDefault ? '' : row.path_prefix || row.locale.toLowerCase(),
+    };
+  });
+  return [...normalized.filter((row) => row.is_default), ...normalized.filter((row) => !row.is_default)];
+}
+
+/**
+ * The store's default language — the one served at the root. Falls back to
+ * the primary, then the first row, then English for an empty list.
+ */
+export function defaultStoreLocale(locales: readonly StoreLocale[]): StoreLocale {
+  return (
+    locales.find((locale) => locale.is_default) ??
+    locales.find((locale) => locale.is_primary) ??
+    locales[0] ?? {
+      locale: FALLBACK_LOCALE_CODE,
+      name: 'English',
+      native_name: 'English',
+      is_primary: true,
+      is_default: true,
+      path_prefix: '',
+      hreflang: FALLBACK_LOCALE_CODE,
+      html_lang: FALLBACK_LOCALE_CODE,
+      dir: 'ltr',
+    }
+  );
+}
+
+/**
+ * The language a request renders in. `localeCode` is the request locale the
+ * provider holds (`null` on the default language). An unknown code resolves
+ * to the default — never an error.
+ */
+export function resolveActiveLocale(locales: readonly StoreLocale[], localeCode: string | null | undefined): StoreLocale {
+  if (localeCode) {
+    const code = localeCode.toLowerCase();
+    const match = locales.find((locale) => locale.locale.toLowerCase() === code);
+    if (match) return match;
+  }
+  return defaultStoreLocale(locales);
+}
+
+/** `/a/b` starts with segment path `/a` (whole segments only). */
+function hasSegmentPrefix(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+function hasSegmentSuffix(path: string, segment: string): boolean {
+  return path === `/${segment}` || path.endsWith(`/${segment}`);
+}
+
+function withMark(value: string | undefined, mark: '?' | '#'): string {
+  if (!value || value === mark) return '';
+  return value.startsWith(mark) ? value : `${mark}${value}`;
+}
+
+export interface LocaleHrefInput {
+  /** The current path as the browser shows it, e.g. `/store/fr/shop`. */
+  pathname: string;
+  /** Query string, with or without the leading `?`. Kept as is. */
+  search?: string;
+  /** Hash, with or without the leading `#`. Kept as is. */
+  hash?: string;
+  /** The provider's `basePath` (already carries the active language prefix). */
+  basePath?: string;
+  /** The language the page renders in now. */
+  active: StoreLocale;
+  /** The language to switch to. */
+  target: StoreLocale;
+}
+
+/**
+ * The same page in another language: the path moves under the target's
+ * prefix (or to the root for the default language), the query string and
+ * hash are kept, and a trailing slash is kept.
+ *
+ * Only the ACTIVE prefix is removed from the current path, and only as a
+ * whole segment — `/french-press` is a page, not the `fr` language.
+ */
+export function localeHref({ pathname, search, hash, basePath = '', active, target }: LocaleHrefInput): string {
+  const activePrefix = active.path_prefix.toLowerCase();
+  const current = pathname || '/';
+  const lowerBase = basePath.toLowerCase();
+
+  let vendorBase = basePath;
+  let bare = current;
+
+  if (activePrefix && hasSegmentSuffix(lowerBase, activePrefix)) {
+    // `basePath` is the localized one: removing it removes the language too.
+    vendorBase = basePath.slice(0, basePath.length - activePrefix.length - 1);
+    if (hasSegmentPrefix(current.toLowerCase(), lowerBase)) bare = current.slice(basePath.length) || '/';
+  } else {
+    if (basePath && hasSegmentPrefix(current, basePath)) bare = current.slice(basePath.length) || '/';
+    if (activePrefix && hasSegmentPrefix(bare.toLowerCase(), `/${activePrefix}`)) {
+      bare = bare.slice(activePrefix.length + 1) || '/';
+    }
+  }
+  if (!bare.startsWith('/')) bare = `/${bare}`;
+
+  const targetPrefix = target.is_default ? '' : target.path_prefix.toLowerCase() || target.locale.toLowerCase();
+  const rest = bare === '/' ? '' : bare;
+  const path = `${vendorBase}${targetPrefix ? `/${targetPrefix}` : ''}${rest}` || '/';
+
+  return `${path}${withMark(search, '?')}${withMark(hash, '#')}`;
+}

package/utils/locale.ts

@@ -1,10 +1,9 @@
 /**
- * Storefront locale transport — the kit side of the translations plan.
+ * Storefront locale transport.
  *
- * Contract (translations-core.md, decisions closed): the backend accepts
- * `?locale=<code>` on every customer-facing read and answers translated text
- * (unknown/unpublished locale → source text, no error). The storefront proxy
- * sets `x-queek-locale` on the incoming request for published NON-primary
+ * The API accepts `?locale=<code>` on every customer-facing read and answers
+ * translated text (unknown/unpublished locale → source text, no error). The
+ * storefront proxy sets `x-queek-locale` on the incoming request for published NON-primary
  * locales only — the header is ABSENT on the primary locale — and suffixes
  * revalidation tags as `<tag>:locale:<code>`.
  *
@@ -23,17 +22,17 @@
  * English display locale — the ONE Intl tag every English shopper sees dates,
  * numbers and money in. `en-NG`, not `en-GB`: both print dates identically
  * ("2 October 2026", "14 Feb 2026"), but only `en-NG` renders NGN with the
- * naira sign the stores already show (`₦12,500` vs `en-GB`'s `NGN 12,500` —
- * verified on Node 22, full ICU, 2/10/26). `DISPLAY_LOCALE` in
- * `utils/format.ts` aliases this, so the value lives in exactly one place.
+ * naira sign the stores already show (`₦12,500` vs `en-GB`'s `NGN 12,500`, on
+ * Node 22 with full ICU). `DISPLAY_LOCALE` in `utils/format.ts` aliases this, so
+ * the value lives in exactly one place.
  */
 export const ENGLISH_DISPLAY_LOCALE = 'en-NG';
 
 /**
  * THE single canonical mapping from a storefront locale code to the Intl
- * locale dates/numbers/relative time are formatted in (founder 2/10/26:
- * shopper's locale, English in the British/Nigerian style so English stores
- * do not change visibly — "2 October 2026", never US "October 2, 2026").
+ * locale dates/numbers/relative time are formatted in: the shopper's locale,
+ * with English in the British/Nigerian style ("2 October 2026", never US
+ * "October 2, 2026").
  *
  * - Missing/invalid/unknown-structure codes and EVERY English variant (`en`,
  *   `en-GB`, `en-NG`, `en-US`, …) become `ENGLISH_DISPLAY_LOCALE`. In

package/utils/menu-link.ts

@@ -17,7 +17,7 @@ export function menuItemToHref(item: MenuItem, basePath: string = ''): string {
       const href = `${basePath}/${item.ref}`;
       const anchor = item.meta?.anchor;
       // href may already end in "/" (the home page's ref is normalized to
-      // "/" — see MenuResource::normalizeHomeRefs) — never emit a doubled
+      // "/") — never emit a doubled
       // slash before the fragment.
       return anchor ? `${href.replace(/\/$/, '')}#${anchor}` : href;
     }

package/utils/menu-placement.ts

@@ -0,0 +1,91 @@
+/**
+ * Popover collision handling for the language menu — pure (no DOM reads, no
+ * React) so it is unit-testable with plain numbers.
+ *
+ * The menu is positioned by CSS (under or over its trigger, aligned to the
+ * trigger's inline-start or inline-end edge). This module only decides
+ * whether that preferred placement fits the viewport, and if not, which of
+ * the alternatives to use: flip to the other side, flip the alignment, then
+ * shift horizontally to keep a gutter.
+ */
+
+export type MenuSide = 'bottom' | 'top';
+export type MenuAlign = 'start' | 'end';
+
+export interface Box {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface PlacementInput {
+  trigger: Box;
+  /** The popover's size — independent of where it is placed. */
+  popover: { width: number; height: number };
+  viewport: { width: number; height: number };
+  side: MenuSide;
+  align: MenuAlign;
+  /** Page direction: `'end'` is the right edge in `ltr` and the left edge in `rtl`. */
+  dir: 'ltr' | 'rtl';
+  /** Space kept between the popover and the viewport edge. */
+  gutter?: number;
+  /** Gap between the trigger and the popover. */
+  offset?: number;
+}
+
+export interface Placement {
+  side: MenuSide;
+  align: MenuAlign;
+  /** Horizontal correction in px, in the physical direction (positive = right). */
+  shift: number;
+  /** Room on the chosen side in px: the popover's height cap. */
+  available: number;
+}
+
+const DEFAULT_GUTTER = 16;
+const DEFAULT_OFFSET = 8;
+
+/** Left edge of the popover for an alignment. */
+function leftFor(align: MenuAlign, dir: 'ltr' | 'rtl', trigger: Box, width: number): number {
+  const rightEdgeAligned = (align === 'end') === (dir === 'ltr');
+  return rightEdgeAligned ? trigger.right - width : trigger.left;
+}
+
+/** Overflow (px) of a left edge past the gutters, 0 when it fits. */
+function overflow(left: number, width: number, viewportWidth: number, gutter: number): number {
+  if (left < gutter) return gutter - left;
+  if (left + width > viewportWidth - gutter) return viewportWidth - gutter - (left + width);
+  return 0;
+}
+
+export function computePlacement(input: PlacementInput): Placement {
+  const { trigger, popover, viewport, dir } = input;
+  const gutter = input.gutter ?? DEFAULT_GUTTER;
+  const offset = input.offset ?? DEFAULT_OFFSET;
+
+  const room = {
+    bottom: viewport.height - trigger.bottom - offset - gutter / 2,
+    top: trigger.top - offset - gutter / 2,
+  };
+  const other: MenuSide = input.side === 'bottom' ? 'top' : 'bottom';
+  const side =
+    popover.height <= room[input.side] || room[input.side] >= room[other] ? input.side : other;
+
+  const otherAlign: MenuAlign = input.align === 'end' ? 'start' : 'end';
+  const preferred = overflow(leftFor(input.align, dir, trigger, popover.width), popover.width, viewport.width, gutter);
+  let align = input.align;
+  let shift = preferred;
+  if (preferred !== 0) {
+    const alternative = overflow(leftFor(otherAlign, dir, trigger, popover.width), popover.width, viewport.width, gutter);
+    if (alternative === 0) {
+      align = otherAlign;
+      shift = 0;
+    } else if (Math.abs(alternative) < Math.abs(preferred)) {
+      align = otherAlign;
+      shift = alternative;
+    }
+  }
+
+  return { side, align, shift, available: Math.max(0, Math.floor(room[side])) };
+}

package/utils/product-media.ts

@@ -14,7 +14,7 @@ export interface MediaFrame {
 
 /**
  * Picks the largest tier a PDP hero should ever request. `view` is capped at
- * 1600px (queek_backend config/media.php) which covers every theme's hero box
+ * 1600px, which covers every theme's hero box
  * at DPR2 — the raw `original` is uncapped and unoptimized.
  */
 function heroUrl(variants: ImageVariants | null | undefined): string | null {

package/utils/product-normalizer.ts

@@ -37,8 +37,8 @@ function toBool(value: unknown, fallback = false): boolean {
 
 /**
  * Same base/sale/compare-at shape as normalizePricing(), but a variant's own price lives on
- * FLAT fields (price/discount_price/compare_at_price/discount_amount — see
- * ProductResource::resolveShopVariants on the backend), never nested under a `pricing` key.
+ * FLAT fields (price/discount_price/compare_at_price/discount_amount), never nested
+ * under a `pricing` key.
  * Reading `variant.pricing?.sale_amount` (as this used to) is always undefined, so every
  * variant silently fell back to the base product's price — picking Denim vs Taupe never
  * changed what was shown, even though the backend had already computed the right number.

package/utils/vendor-host.ts

@@ -1,14 +1,11 @@
 /**
  * Vendor resolution from a hostname: which store is this request for?
  *
- * Lived at `app/middleware.ts` until core needed it — `lib/core/api/products.ts`
- * and `lib/core/sdk/server-store-client.ts` both import from here, which meant
- * core depended on the app. Nothing here is app-specific: it reads env and
- * resolves a slug. (The actual Next middleware is `proxy.ts`; the old filename
- * suggested otherwise and was never that.)
+ * Nothing here is app-specific: it reads env and resolves a slug, so the kit's
+ * server fetchers and a host app's proxy can both import it.
  */
 
-// Mirrors backend config/storefront.php `reserved_slugs`. Keep in sync.
+// Mirrors the API's reserved store slugs. Keep in sync.
 // These are subdomains the storefront proxy must NOT treat as vendor slugs.
 export const RESERVED_VENDOR_SLUGS = new Set([
   // Live platform subdomains
@@ -24,11 +21,10 @@ export const RESERVED_VENDOR_SLUGS = new Set([
   'staff', 'team', 'queek', 'merchant', 'vendor', 'rider', 'customer',
 ]);
 
-// Every sluggable backend model (Vendor, Product, Category, Region, Service —
-// app/Models/*.php `getSlugOptions()`) is Spatie Sluggable output: lowercase
-// alphanumeric, optionally hyphen-separated, never a dot/underscore/uppercase.
-// Anything else cannot be a real slug of any kind, so reject it before any
-// backend round-trip instead of burning calls that all 404. This is what stops
+// Every sluggable API model (Vendor, Product, Category, Region, Service)
+// produces lowercase alphanumeric slugs, optionally hyphen-separated, never a
+// dot/underscore/uppercase. Anything else cannot be a real slug of any kind, so
+// reject it before any API round-trip instead of burning calls that all 404. This is what stops
 // scanners probing `.env`, `.ssh`, `docker-compose.yaml`, `*.php` etc —
 // RESERVED_VENDOR_SLUGS alone only covers known words, not the infinite space
 // of file-extension guesses.