@usequeek/theme-kit 0.1.20 → 0.1.22

package/tests/theme-strings-pseudo.test.tsx

@@ -0,0 +1,171 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import type { JSX, ReactNode } from 'react';
+import { describe, expect, it } from 'vitest';
+import enDefault from '../locales/en.default.json';
+import { StorefrontProvider, useThemeStrings } from '../provider';
+import { defaultThemeStrings, t, type ThemeStringsDictionary } from '../strings/theme-strings';
+import {
+  assertNoEnglishLeak,
+  findEnglishLeaks,
+  isPseudoLocalized,
+  pseudoLocalize,
+  pseudoLocalizeText,
+} from '../strings/pseudo-locale';
+
+const EN = enDefault as unknown as ThemeStringsDictionary;
+
+function render(children: ReactNode, strings: ThemeStringsDictionary | null): string {
+  return renderToStaticMarkup(
+    <StorefrontProvider
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
+      config={{} as never}
+      menus={[]}
+      {...(strings ? { strings } : {})}
+    >
+      {children}
+    </StorefrontProvider>,
+  );
+}
+
+function Title(): JSX.Element {
+  const t = useThemeStrings();
+  return <h1>{t('cart.title')}</h1>;
+}
+
+describe('pseudoLocalize (pure dictionary transform)', () => {
+  it('accent-maps, expands ~30% and wraps in markers', () => {
+    expect(pseudoLocalizeText('Your cart')).toBe('[!! Ÿòùŕ çàŕţ~~~ !!]');
+  });
+
+  it('preserves {placeholders} byte-for-byte and still interpolates', () => {
+    const pseudo = pseudoLocalizeText('{count} items');
+    expect(pseudo).toBe('[!! {count} ìţèṁš~~~~ !!]');
+    expect(pseudo).toContain('{count}');
+    expect(t([{ v: pseudo }], 'v', { count: 3 }, 'en')).toBe('[!! 3 ìţèṁš~~~~ !!]');
+  });
+
+  it('preserves `{{` / `}}` escapes (structure survives, literal is pseudo)', () => {
+    const pseudo = pseudoLocalizeText('a {{b}} c');
+    expect(pseudo).toContain('{{');
+    expect(pseudo).toContain('}}');
+    // Same interpolation behaviour as the source: escapes still escape.
+    expect(t([{ v: pseudo }], 'v', {}, 'en')).toBe('[!! à {ƀ} ç~~~ !!]');
+  });
+
+  it('keeps plural-map shape (one key, every form pseudo)', () => {
+    const dict: ThemeStringsDictionary = {
+      items: { count: { one: '{count} item', other: '{count} items' } },
+    };
+    const pseudo = pseudoLocalize(dict);
+    expect(Object.keys((pseudo['items'] as Record<string, unknown>)['count'] as object)).toEqual([
+      'one',
+      'other',
+    ]);
+    const forms = (pseudo['items'] as { count: { one: string; other: string } }).count;
+    expect(forms.one).toContain('{count}');
+    expect(isPseudoLocalized(forms.one)).toBe(true);
+    expect(isPseudoLocalized(forms.other)).toBe(true);
+    // t() still selects forms from the pseudo dictionary.
+    expect(t([pseudo], 'items.count', { count: 1 }, 'en')).toContain('1');
+    expect(t([pseudo], 'items.count', { count: 5 }, 'en')).toContain('5');
+  });
+
+  it('recurses nested objects and never touches keys (incl. flat dotted keys)', () => {
+    const dict = {
+      cart: { title: 'Your cart', empty: { message: 'Your cart is empty.' } },
+      'flat.key': 'Flat value',
+    } as unknown as ThemeStringsDictionary;
+    const pseudo = pseudoLocalize(dict);
+    expect(Object.keys(pseudo).sort()).toEqual(['cart', 'flat.key']);
+    expect(Object.keys(pseudo['cart'] as object).sort()).toEqual(['empty', 'title']);
+    expect(t([pseudo], 'flat.key')).toBe(pseudoLocalizeText('Flat value'));
+  });
+
+  it('leaves empty values empty (an intentional empty renders no node)', () => {
+    expect(pseudoLocalizeText('')).toBe('');
+    const pseudo = pseudoLocalize({ hidden: { label: '' } });
+    expect((pseudo['hidden'] as { label: string }).label).toBe('');
+  });
+
+  it('expands very long values by ~30% (1000-char budget value)', () => {
+    const long = 'a'.repeat(1000);
+    const pseudo = pseudoLocalizeText(long);
+    const core = pseudo.slice('[!! '.length, -' !!]'.length);
+    expect(core.length).toBe(1000 + Math.round(1000 * 0.3));
+  });
+
+  it('leaves unicode (non-Latin, emoji) intact, wrapped', () => {
+    const pseudo = pseudoLocalizeText('こんにちは世界 🛒');
+    expect(pseudo).toContain('こんにちは世界');
+    expect(pseudo).toContain('🛒');
+    expect(isPseudoLocalized(pseudo)).toBe(true);
+  });
+
+  it('rtl option wraps the core in U+202B … U+202C', () => {
+    const pseudo = pseudoLocalizeText('Your cart', { rtl: true });
+    expect(pseudo.includes('\u202B')).toBe(true);
+    expect(pseudo.includes('\u202C')).toBe(true);
+    expect(isPseudoLocalized(pseudo)).toBe(true);
+  });
+
+  it('custom markers are honoured by the scan', () => {
+    const pseudo = pseudoLocalizeText('Your cart', { prefix: '‹', suffix: '›' });
+    expect(pseudo.startsWith('‹')).toBe(true);
+    expect(isPseudoLocalized(pseudo)).toBe(false);
+    expect(isPseudoLocalized(pseudo, { prefix: '‹', suffix: '›' })).toBe(true);
+    expect(findEnglishLeaks(`<h1>${pseudo}</h1>`, { pseudo: { prefix: '‹', suffix: '›' } })).toEqual(
+      [],
+    );
+  });
+});
+
+describe('English leak scan (reusable theme-test primitive)', () => {
+  it('a fully pseudo render is clean', () => {
+    const html = render(<Title />, pseudoLocalize(EN));
+    expect(html).not.toContain('Your cart');
+    expect(findEnglishLeaks(html)).toEqual([]);
+    expect(() => assertNoEnglishLeak(html)).not.toThrow();
+  });
+
+  it('a hard-coded English string is reported (the control that proves the scan fails)', () => {
+    function Leaky(): JSX.Element {
+      const t = useThemeStrings();
+      return (
+        <main>
+          <h1>{t('cart.title')}</h1>
+          <p>Hard-coded checkout copy</p>
+        </main>
+      );
+    }
+    const html = render(<Leaky />, pseudoLocalize(EN));
+    expect(findEnglishLeaks(html)).toEqual(['Hard-coded checkout copy']);
+    expect(() => assertNoEnglishLeak(html)).toThrow(/Hard-coded checkout copy/);
+  });
+
+  it('flags hard-coded user-visible attributes (aria-label, placeholder)', () => {
+    const html = `<button aria-label="Close dialog">×</button><input placeholder="Search products" />`;
+    expect(findEnglishLeaks(html)).toEqual(['Close dialog', 'Search products']);
+    expect(findEnglishLeaks(html, { includeAttributes: false })).toEqual([]);
+  });
+
+  it('ignores numbers, symbols and pseudo-wrapped attributes', () => {
+    const html = render(<Title />, pseudoLocalize(EN));
+    expect(findEnglishLeaks(`<span>₦5,000</span><span>2 / 5</span>${html}`)).toEqual([]);
+  });
+
+  it('allowlists brand names and codes', () => {
+    const html = `<footer><span>${pseudoLocalizeText('Powered by')}</span><span>Queek</span></footer>`;
+    expect(findEnglishLeaks(html)).toEqual(['Queek']);
+    expect(findEnglishLeaks(html, { allowlist: ['Queek'] })).toEqual([]);
+    expect(findEnglishLeaks(html, { allowlist: [/^Q/] })).toEqual([]);
+  });
+
+  it('pseudo of the real English default keeps every key (renamed-key drift fails here)', () => {
+    const pseudo = pseudoLocalize(EN);
+    expect(Object.keys(pseudo).sort()).toEqual(Object.keys(EN).sort());
+    // Spot values still resolve through t() — a changed English default that
+    // was not rebuilt into pseudo expectations fails loudly, never silently.
+    expect(t([pseudo], 'cart.title')).toBe(pseudoLocalizeText('Your cart'));
+    expect(t([defaultThemeStrings], 'cart.title')).toBe('Your cart');
+  });
+});

package/tests/theme-strings-typed.test.tsx

@@ -0,0 +1,97 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import type { JSX } from 'react';
+import { describe, expect, it } from 'vitest';
+import enDefault from '../locales/en.default.json';
+import {
+  createThemeT,
+  defaultThemeStrings,
+  t,
+  type ThemeStringKey,
+  type ThemeStringsDictionary,
+} from '../strings/theme-strings';
+import { StorefrontProvider, useThemeStrings } from '../provider';
+
+/** Small theme-shaped dictionary exercising nesting, plurals and flat keys. */
+const THEME_EN = {
+  cart: {
+    title: 'Your cart',
+    empty: { message: 'Your cart is empty.' },
+  },
+  items: {
+    count: { one: '{count} item', other: '{count} items' },
+  },
+  'flat.key': 'Flat value',
+  greet: 'Hello {name}!',
+} as const;
+
+describe('typed keys: createThemeT (additive, opt-in)', () => {
+  it('delegates to the wrapped t (values, vars, plurals identical)', () => {
+    const dict = THEME_EN as unknown as ThemeStringsDictionary;
+    const tt = createThemeT<typeof THEME_EN>((key, vars, locale) => t([dict], key, vars, locale));
+
+    expect(tt('cart.title')).toBe('Your cart');
+    expect(tt('greet', { name: 'Ada' })).toBe('Hello Ada!');
+    expect(tt('items.count', { count: 1 })).toBe('1 item');
+    expect(tt('items.count', { count: 5 })).toBe('5 items');
+    expect(tt('flat.key')).toBe('Flat value');
+  });
+
+  it('wraps the client useThemeStrings() hook result', () => {
+    function Title(): JSX.Element {
+      const tUntyped = useThemeStrings();
+      const tt = createThemeT<typeof THEME_EN>(tUntyped);
+      return <h1>{tt('cart.title')}</h1>;
+    }
+    const html = renderToStaticMarkup(
+      <StorefrontProvider
+        vendor={{ id: 'v1', slug: 's', name: 'S' } as never}
+        config={{} as never}
+        menus={[]}
+        strings={THEME_EN as unknown as ThemeStringsDictionary}
+      >
+        <Title />
+      </StorefrontProvider>,
+    );
+    expect(html).toContain('<h1>Your cart</h1>');
+  });
+
+  it('accepts every real en.default.json key (valid keys pass)', () => {
+    const tt = createThemeT<typeof enDefault>((key, vars, locale) =>
+      t([defaultThemeStrings], key, vars, locale),
+    );
+    // A sample across nesting depths — each must compile AND render English.
+    expect(tt('cart.title')).toBe('Your cart');
+    expect(tt('cart.empty.message')).toBe('Your cart is empty.');
+    expect(tt('checkout.contact.label')).toBe('Contact');
+    expect(tt('auth.login.title')).toBe('Sign in');
+    expect(tt('blog.share.copy')).toBe('Copy link');
+  });
+
+  it('existing untyped t(key) callers keep compiling (key: string)', () => {
+    const anyKey: string = `cart.title`;
+    // A dynamic string — not a literal — still flows through the untyped fn.
+    expect(t([defaultThemeStrings], anyKey)).toBe('Your cart');
+    // A broad dictionary collapses the typed helper back to `string` (untyped).
+    const loose = createThemeT<ThemeStringsDictionary>((key, vars, locale) =>
+      t([defaultThemeStrings], key, vars, locale),
+    );
+    expect(loose(anyKey)).toBe('Your cart');
+  });
+
+  it('drifts with the dictionary: the union is exactly the flattened keys', () => {
+    // Compile-time check (positive direction; the negative direction — typos
+    // fail — lives in tests/theme-typed-keys.fixture.ts via @ts-expect-error
+    // so `npm run typecheck` stays green).
+    const keys: Array<ThemeStringKey<typeof THEME_EN>> = [
+      'cart.title',
+      'cart.empty.message',
+      'items.count',
+      'flat.key',
+      'greet',
+    ];
+    expect(keys).toHaveLength(5);
+    // Renaming/removing a key above breaks this file AND the fixture: a
+    // renamed English key is a contract change, not a silent drift.
+    expect(keys).toContain('cart.title');
+  });
+});

package/tests/theme-strings.test.tsx

@@ -43,7 +43,7 @@ const FR_THEME = {
   'cart.empty.browse': 'Voir les produits',
 } as unknown as ThemeStringsDictionary;
 
-describe('t() fallback order (decision 3)', () => {
+describe('t() fallback order', () => {
   it('returns the first hit across override, theme, core, default', async () => {
     const bound = await createThemeStrings({
       locale: 'fr',
@@ -223,7 +223,7 @@ describe('RTL dir (locale catalogue)', () => {
   });
 });
 
-describe('default English dictionary budget (backend varchar(64))', () => {
+describe('default English dictionary budget (64-character stored key)', () => {
   function flatten(node: unknown, prefix: string, out: Array<[string, string]>): void {
     if (typeof node === 'string') {
       out.push([prefix, node]);
@@ -239,9 +239,12 @@ describe('default English dictionary budget (backend varchar(64))', () => {
   const pairs: Array<[string, string]> = [];
   flatten(enDefault, '', pairs);
 
-  it('ships the ~75-string core skeleton', () => {
+  it('ships the ~106-string core dictionary (intentional growth, still budgeted)', () => {
+    // Dictionary budget: the ceiling stays tight (+9 headroom): any further
+    // growth must bump it here deliberately with its own justification, which
+    // guards against uncontrolled growth (64-character stored-key budget below).
     expect(pairs.length).toBeGreaterThanOrEqual(70);
-    expect(pairs.length).toBeLessThan(100);
+    expect(pairs.length).toBeLessThanOrEqual(115);
   });
 
   it('every key fits the dotted-lowercase grammar and the 40-char budget', () => {
@@ -251,7 +254,7 @@ describe('default English dictionary budget (backend varchar(64))', () => {
       expect(key, `grammar: ${key}`).toMatch(/^[a-z0-9]+(\.[a-z0-9]+)*$/);
       expect(key.length, `budget: ${key}`).toBeLessThanOrEqual(THEME_STRING_KEY_MAX_LENGTH);
     }
-    // `<theme-slug>.<key>` must fit varchar(64): 40 + 1 + 23.
+    // `<theme-slug>.<key>` must fit the 64-character stored key: 40 + 1 + 23.
     expect(Math.max(...pairs.map(([k]) => k.length))).toBeLessThanOrEqual(40);
   });
 
@@ -266,7 +269,7 @@ describe('default English dictionary budget (backend varchar(64))', () => {
   });
 });
 
-describe('per-locale loading gate (decision 5)', () => {
+describe('per-locale loading gate', () => {
   function sourceFiles(dir: string, out: string[] = []): string[] {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       if (entry.name === 'node_modules') continue;
@@ -329,7 +332,7 @@ describe('per-locale loading gate (decision 5)', () => {
   });
 });
 
-describe('server surface: bound t with NO provider (decision 4a)', () => {
+describe('server surface: bound t with NO provider', () => {
   function Greeting({ bound, name }: { bound: BoundThemeStrings; name: string }): JSX.Element {
     return (
       <main>

package/tests/theme-typed-keys.fixture.ts

@@ -0,0 +1,76 @@
+/**
+ * Type-level test (tsd-style via tsc): a typo key FAILS and a valid key
+ * PASSES. This file must stay green under `npm run typecheck` — every
+ * `@ts-expect-error` below is consumed only if the marked line is a type
+ * error, so deleting the error (or breaking the helper) fails the gate.
+ *
+ * NOTE: intentionally self-contained (no `locales/*.json` import) so the
+ * per-locale bundle gate keeps counting exactly one static locale importer
+ * (`strings/theme-strings.ts`).
+ */
+import {
+  createThemeT,
+  t,
+  type ThemeStringKey,
+  type ThemeStringsDictionary,
+} from '../strings/theme-strings';
+
+const strings = {
+  cart: {
+    title: 'Your cart',
+    empty: { message: 'Your cart is empty.' },
+  },
+  items: {
+    count: { one: '{count} item', other: '{count} items' },
+  },
+  'flat.key': 'Flat value',
+} as const;
+
+type K = ThemeStringKey<typeof strings>;
+
+// The union is EXACTLY the flattened keys (mutual assignability proves it:
+// adding or dropping a key on either side breaks this file).
+type Expected = 'cart.title' | 'cart.empty.message' | 'items.count' | 'flat.key';
+const exact1: Expected = null as unknown as K;
+const exact2: K = null as unknown as Expected;
+void exact1;
+void exact2;
+
+// Valid keys pass …
+const okTitle: K = 'cart.title';
+const okNested: K = 'cart.empty.message';
+const okPlural: K = 'items.count';
+const okFlat: K = 'flat.key';
+void okTitle;
+void okNested;
+void okPlural;
+void okFlat;
+
+// … and plural sub-forms are NOT keys (the map is one key) …
+ // @ts-expect-error - 'items.count.one' is a form, not a key
+const badForm: K = 'items.count.one';
+void badForm;
+
+// … a typo key fails …
+ // @ts-expect-error - typo: 'cart.titl' is not a key
+const badTypo: K = 'cart.titl';
+void badTypo;
+
+// … and an unknown key fails.
+ // @ts-expect-error - 'no.such.key' is not a key
+const badUnknown: K = 'no.such.key';
+void badUnknown;
+
+// The typed binding enforces the same at the call site.
+const dict = strings as unknown as ThemeStringsDictionary;
+const tt = createThemeT<typeof strings>((key, vars, locale) => t([dict], key, vars, locale));
+tt('cart.title');
+tt('items.count', { count: 2 });
+// @ts-expect-error - typo key fails through createThemeT too
+tt('cart.titl');
+
+// A broad dictionary stays untyped (existing dynamic-key callers compile).
+declare const anyKey: string;
+const loose = createThemeT<ThemeStringsDictionary>((key, vars, locale) => t([dict], key, vars, locale));
+loose(anyKey);
+t([dict], anyKey);

package/tests/use-shop-prefetch.test.tsx

@@ -34,7 +34,7 @@ function Grid(props: Parameters<typeof useShop>[0]): JSX.Element {
 
 function render(children: ReactNode, opts: { prefetch?: ShopPrefetch | null; preview?: Product[] } = {}): string {
   const store = {
-    vendor: { id: 'v1', slug: 'kili-foods', name: 'Kili Foods' },
+    vendor: { id: 'v1', slug: 'demo-store', name: 'Demo Store' },
     config: {},
     menus: [],
     previewData: opts.preview ? { products: opts.preview } : undefined,

package/theme-mount.tsx

@@ -7,18 +7,13 @@ import { ThemeProvider } from './theme-context';
 /**
  * Renders a theme. THE MINIMUM A THEME NEEDS TO BE SEEN.
  *
- * Without this, installing `@usequeek/theme-kit` gave a developer every hook,
- * store, type and shared block — and no way to actually mount what they built.
- * The component that does it, `VendorShell`, lives in the storefront app, so it
- * was never part of what shipped. A theme could be written and typechecked from
- * outside this repo but never rendered.
+ * It mounts a theme's header, page and footer inside the kit's provider, so a
+ * theme written and typechecked outside a Queek storefront can still be rendered.
  *
- * DELIBERATELY SMALLER THAN VendorShell. That composes the same three pieces and
- * then layers on the Queek storefront's own chrome — checkout header, cart and
- * auth modals, toasts, WhatsApp chat, analytics, the merchant edit-mode bridge.
- * None of that is a theme's concern, and pulling it in would drag the whole app
- * into the package. What is left is the actual contract: a Layout wrapping a
- * header, the page, and a footer.
+ * DELIBERATELY SMALL. It leaves out the Queek storefront's own chrome — checkout
+ * header, cart and auth modals, toasts, WhatsApp chat, analytics, the merchant
+ * edit-mode bridge. None of that is a theme's concern. What is left is the
+ * actual contract: a Layout wrapping a header, the page, and a footer.
  *
  * Themes render inside a boundary because a theme's header and footer are
  * SIBLINGS of the page, so a crash in either escapes any boundary the page sets

package/types/block.ts

@@ -42,7 +42,7 @@ export interface GalleryBlockData {
   heading?: string | null;
   description?: string | null;
   /** Block-level (not per-slide) hero display controls — currently only
-   *  glow's 'slider'/'thumb-rail' variants read these; harmless no-op
+   *  some themes' 'slider'/'thumb-rail' variants read these; harmless no-op
    *  elsewhere. */
   zoom_effect?: boolean | null;
   overlay?: 'none' | 'light' | 'medium' | 'strong' | null;
@@ -62,7 +62,7 @@ export interface GalleryBlockData {
     /** YouTube/Vimeo/direct file URL — takes over from `url` as the slide's
      * media when set, with `url` still used as the poster/fallback. Only
      * takes effect on themes/variants that render a single full-bleed slide
-     * (e.g. glow's `slider`/`thumb-rail` with exactly 1 image) — a
+     * (e.g. a `slider`/`thumb-rail` variant with exactly 1 image) — a
      * multi-slide carousel would autoplay every slide's video concurrently
      * since inactive slides stay mounted, not unmounted. */
     video?: string | null;
@@ -258,7 +258,7 @@ export interface MetaobjectsBlockData {
  * Server-seeded resolution for a `metaobjects` block — the entries of
  * `data.type` plus the definition meta needed to decide whether each card
  * links out (`definition.has_pages`). Mirrors `MetaobjectsResolved` shape
- * used by `hydrateProductBlocks` in the storefront.
+ * used by `hydrateProductBlocks` in the host app.
  */
 export interface MetaobjectsResolved {
   entries: MetaobjectEntry[];
@@ -293,17 +293,17 @@ export type Block<T extends BlockType = BlockType> = {
   /**
    * Section-scoped design-token overrides — only the keys set here are
    * applied; everything else inherits the global tokens via the CSS
-   * cascade. See `expandDesignTokensPartial` in `lib/core/utils/brand.ts`.
+   * cascade. See `expandDesignTokensPartial` in `utils/brand.ts`.
    */
   tokens?: Partial<DesignTokens>;
   /**
    * Stable in-page-scroll target — a menu item's `meta.anchor` links here.
-   * Lowercase-kebab, enforced by the backend (ValidStorefrontBlocks).
+   * Lowercase-kebab, enforced by the API.
    */
   anchor_id?: string;
   /**
    * Server-seeded product data for `products` blocks — set by
-   * `hydrateProductBlocks` (lib/core/api/products.ts) before blocks reach
+   * the host's `hydrateProductBlocks` before blocks reach
    * `PageRenderer`, which awaits it via `use()` inside a per-block
    * `<Suspense>` boundary. Lives on the block, not inside `data`, so it never
    * gets spread into theme components as a prop. Absent for every other
@@ -312,7 +312,7 @@ export type Block<T extends BlockType = BlockType> = {
   productsPromise?: Promise<Product[]>;
   /**
    * Server-seeded entries + definition meta for `metaobjects` blocks — set
-   * by `hydrateProductBlocks` alongside `productsPromise`. Same contract:
+   * by the host's `hydrateProductBlocks` alongside `productsPromise`. Same rule:
    * absent for every other block type and for any route that hasn't been
    * wired to hydrate; the renderer falls back to rendering nothing (themes
    * never fetch metaobjects client-side).

package/types/media.ts

@@ -1,21 +1,20 @@
 /**
- * The srcset-ready tier map emitted by the backend's MediaVariantMap
- * (queek_backend: app/Services/Media/MediaVariantMap.php). Sits BESIDE the
- * existing collapsed url fields (media.image, vendor.logo, collection.image, …),
- * which are unchanged — this is purely additive.
+ * The srcset-ready tier map emitted by the API. Sits BESIDE the existing
+ * collapsed url fields (media.image, vendor.logo, collection.image, …), which
+ * are unchanged — this is purely additive.
  *
- * Contract (enforced backend-side, relied on here):
+ * Contract (enforced API-side, relied on here):
  *  1. All 5 keys are ALWAYS present when the map itself is non-null.
  *  2. A tier that doesn't exist is the WHOLE VALUE null — never a partial
  *     object, never a fallback url. Skip it; never synthesize a filename.
  *  3. `original` is never null when the map is non-null. Modeled as
  *     `ImageVariantTier | null` anyway rather than a type-level invariant:
- *     making it non-nullable would buy zero runtime safety against a backend
+ *     making it non-nullable would buy zero runtime safety against an API
  *     regression while forcing every consumer through a `!` or a cast. The
  *     invariant is documented, not encoded.
  *  4. `w`/`h` are `min(tier_cap, original.width)` and the proportional height —
  *     so on a small original SEVERAL TIERS LEGITIMATELY SHARE A WIDTH. That is
- *     correct backend behavior, and the reason resolveImageSources() dedupes
+ *     correct API behavior, and the reason resolveImageSources() dedupes
  *     srcset candidates by width (duplicate `w` descriptors make a srcset
  *     non-deterministic).
  *  5. `thumb` ALWAYS has `w: null, h: null` — it's a legacy 150→240px tier with
@@ -25,7 +24,7 @@
  *     url, SVG, some legacy uploads). Consumers fall back to the existing
  *     collapsed field, exactly as today.
  *
- * Tier caps (queek_backend config/media.php `variant_widths`):
+ * Tier caps (px):
  *   thumb ~240 (uncapped/legacy) · card 480 · card2x 800 · view 1600 · original raw
  */
 export interface ImageVariantTier {
@@ -44,7 +43,7 @@ export type ImageVariants = {
 
 /**
  * The flat url→variants sidecar on a Page/Post response
- * (StorePageResource::toArray → 'media_index'). Keyed by the EXACT raw url
+ * (the `media_index` field). Keyed by the EXACT raw url
  * string as it appears in that same response's `content[]` block JSON —
  * block schemas were not changed, so a consumer looks up
  * `mediaIndex[url] ?? null` per raw url it finds in block content.

package/types/product.ts

@@ -29,8 +29,7 @@ export interface ProductShop {
 }
 
 /**
- * One entry of the ordered `images` list (backend
- * `CustomerProductMedia::orderedImages()`): primary first,
+ * One entry of the ordered `images` list: primary first,
  * `{id, url, alt, variants}`. The listing payload caps the list
  * (`media.listing.images_limit`); detail/PDP carries the full list.
  */
@@ -53,11 +52,9 @@ export interface ProductMedia {
   primary_variant_image?: string | null;
   video_url?: string | null;
   /** Falls back to `image` server-side when the vendor hasn't set an explicit
-   *  poster (ProductResource::resolveVideoPosterUrl) — always a usable value
-   *  whenever video_url is set. */
+   *  poster — always a usable value whenever video_url is set. */
   video_poster_url?: string | null;
-  /** Srcset tier map for `image` (ProductResource::buildBaseMediaPayload /
-   *  buildDetailMediaPayload — present on BOTH list and detail responses).
+  /** Srcset tier map for `image` (present on BOTH list and detail responses).
    *  null when the primary image isn't Media-backed. */
   image_variants?: ImageVariants | null;
   /** Sibling to `primary_variant_image`, same contract. */
@@ -268,9 +265,8 @@ export interface LegacyProductLike {
   vendor_id?: string;
   thumbnail?: string | null;
   image?: string | null;
-  // Sibling top-level fields on the real backend payload (ProductResource::
-  // buildBasePayload) — NOT nested under `media` server-side, unlike
-  // image/thumbnail which are sent in both places.
+  // Sibling top-level fields on the real API payload — NOT nested under
+  // `media` server-side, unlike image/thumbnail which are sent in both places.
   video_url?: string | null;
   video_poster_url?: string | null;
   stock?: number;
@@ -296,9 +292,9 @@ export interface LegacyProductLike {
       // also send it as a {optionName: value} map (normalizeVariantOptionValues handles both) —
       // intersecting the two types directly collapses to an unsatisfiable type, hence the Omit.
       option_values?: ProductVariantOptionValue[] | Record<string, string>;
-      // The backend sends a variant's own price/stock as FLAT fields (see
-      // ProductResource::resolveShopVariants), never nested under pricing/inventory —
-      // those nested keys only exist if some other caller pre-shapes the payload.
+      // The API sends a variant's own price/stock as FLAT fields, never nested
+      // under pricing/inventory — those nested keys only exist if some other
+      // caller pre-shapes the payload.
       price?: number;
       discount_price?: number;
       compare_at_price?: number | null;