@usequeek/theme-kit 0.1.21 → 0.1.23

package/tests/menu-placement.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { computePlacement, type PlacementInput } from '../utils/menu-placement';
+
+const VIEW = { width: 1000, height: 800 };
+const POP = { width: 240, height: 300 };
+
+function place(over: Partial<PlacementInput> & Pick<PlacementInput, 'trigger'>) {
+  return computePlacement({ popover: POP, viewport: VIEW, side: 'bottom', align: 'end', dir: 'ltr', ...over });
+}
+
+/** A 100x44 trigger whose top-left is (left, top). */
+const box = (left: number, top: number) => ({ left, top, right: left + 100, bottom: top + 44 });
+
+describe('computePlacement', () => {
+  it('keeps the preferred placement when it fits', () => {
+    expect(place({ trigger: box(700, 10) })).toMatchObject({ side: 'bottom', align: 'end', shift: 0 });
+  });
+
+  it('flips up when there is no room below and more above', () => {
+    const p = place({ trigger: box(700, 600) });
+    expect(p.side).toBe('top');
+    expect(p.available).toBe(600 - 8 - 8);
+  });
+
+  it('footers opening up flip down when there is no room above', () => {
+    expect(place({ trigger: box(700, 20), side: 'top' }).side).toBe('bottom');
+    expect(place({ trigger: box(700, 600), side: 'top' }).side).toBe('top');
+  });
+
+  it('keeps the side with more room (and caps the height) when neither fits', () => {
+    const p = place({ trigger: box(700, 300), popover: { width: 240, height: 700 } });
+    expect(p.side).toBe('bottom');
+    expect(p.available).toBe(800 - 344 - 8 - 8);
+  });
+
+  it('aligns to the trigger end (right edge in ltr) and flips alignment on overflow', () => {
+    // end: left = 800 - 240 = 560, fits.
+    expect(place({ trigger: box(700, 10) })).toMatchObject({ align: 'end', shift: 0 });
+    // trigger near the left edge: end would start at 40 - 140 < 16; start fits.
+    expect(place({ trigger: box(40, 10) })).toMatchObject({ align: 'start', shift: 0 });
+  });
+
+  it('mirrors in rtl: end is the left edge', () => {
+    // rtl end: left = trigger.left = 40 fits.
+    expect(place({ trigger: box(40, 10), dir: 'rtl' })).toMatchObject({ align: 'end', shift: 0 });
+    // trigger at the right edge: rtl end would overflow; start (right edge aligned) fits.
+    expect(place({ trigger: box(880, 10), dir: 'rtl' })).toMatchObject({ align: 'start', shift: 0 });
+  });
+
+  it('shifts into the gutter when neither alignment fits', () => {
+    // 240 wide in a 260 viewport, trigger in the middle: both overflow somewhere.
+    const p = computePlacement({
+      trigger: box(80, 10),
+      popover: { width: 240, height: 100 },
+      viewport: { width: 260, height: 800 },
+      side: 'bottom',
+      align: 'end',
+      dir: 'ltr',
+    });
+    // end: left edge at 180 - 240 = -60, shifted +76 to the 16px gutter.
+    expect(p).toMatchObject({ align: 'end', shift: 76 });
+  });
+});

package/tests/orders-walk.test.ts

@@ -2,9 +2,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { fetchOrders } from '../api/orders';
 
 /**
- * `GET store/orders` answers the ONE storefront list envelope (pagination
- * Slice 4b, founder 28/9/26): `has_more` + `next_cursor` top-level, no
- * `links`, no paginator `meta`. The kit reads the page it asked for.
+ * `GET store/orders` answers the ONE storefront list envelope: `has_more` +
+ * `next_cursor` top-level, no `links`, no paginator `meta`. The kit reads the
+ * page it asked for.
  */
 describe('fetchOrders walk state', () => {
   afterEach(() => vi.unstubAllGlobals());
@@ -23,7 +23,7 @@ describe('fetchOrders walk state', () => {
     }));
     vi.stubGlobal('fetch', fetchMock);
 
-    const page = await fetchOrders('kili-foods', 2, 'ongoing');
+    const page = await fetchOrders('demo-store', 2, 'ongoing');
 
     const url = String((fetchMock.mock.calls[0] as unknown[])[0]);
     expect(url).toContain('/client/store/orders');
@@ -39,7 +39,7 @@ describe('fetchOrders walk state', () => {
     const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ data: [], has_more: false, next_cursor: null }) }));
     vi.stubGlobal('fetch', fetchMock);
 
-    const page = await fetchOrders('kili-foods', 1, 'all');
+    const page = await fetchOrders('demo-store', 1, 'all');
 
     expect(String((fetchMock.mock.calls[0] as unknown[])[0])).not.toContain('status=');
     expect(page.has_more).toBe(false);

package/tests/page-renderer-signature.test.tsx

@@ -27,7 +27,7 @@ describe('PageRenderer', () => {
       { type: 'content', data: { markdown: 'Fresh meals, delivered' }, productsPromise: circularThenable(), metaobjectsPromise: circularThenable() },
     ] as unknown as Block[];
     const theme = { getBlock: () => () => null } as unknown as ThemeModule;
-    const store = { vendor: { id: 'v1', slug: 'kili-foods' }, config: {}, menus: [], basePath: '', pagesChrome: {} };
+    const store = { vendor: { id: 'v1', slug: 'demo-store' }, config: {}, menus: [], basePath: '', pagesChrome: {} };
 
     const html = renderToStaticMarkup(
       <StorefrontContext.Provider value={store as never}>

package/tests/powered-by-queek.test.tsx

@@ -27,9 +27,9 @@ describe('PoweredByQueek', () => {
   });
 
   it('tags the link with the store slug as utm_campaign', () => {
-    const html = render(undefined, { id: 'uuid-1', slug: 'kili-foods' });
+    const html = render(undefined, { id: 'uuid-1', slug: 'demo-store' });
 
-    expect(html).toContain(`href="${BASE}&utm_campaign=kili-foods"`);
+    expect(html).toContain(`href="${BASE}&utm_campaign=demo-store"`);
     expect(html).toContain('rel="noopener noreferrer"');
   });
 
@@ -60,6 +60,6 @@ describe('PoweredByQueek', () => {
 
   it('renders nothing when hidden', () => {
     expect(render({ hidden: true })).toBe('');
-    expect(render({ hidden: true }, { id: 'uuid-1', slug: 'kili-foods' })).toBe('');
+    expect(render({ hidden: true }, { id: 'uuid-1', slug: 'demo-store' })).toBe('');
   });
 });

package/tests/powered-by-url.test.ts

@@ -7,13 +7,13 @@ function params(url: string): Record<string, string> {
 
 describe('poweredByQueekUrl', () => {
   it('keeps the business-page destination and adds source, medium and campaign', () => {
-    const url = poweredByQueekUrl('kili-foods');
+    const url = poweredByQueekUrl('demo-store');
 
     expect(url.startsWith(`${POWERED_BY_QUEEK_URL}?`)).toBe(true);
     expect(params(url)).toEqual({
       utm_source: 'powered_by',
       utm_medium: 'storefront',
-      utm_campaign: 'kili-foods',
+      utm_campaign: 'demo-store',
     });
   });
 

package/tests/public-surface.test.ts

@@ -20,10 +20,7 @@ function barrelModules(file: string): Set<string> {
  * `index.ts` + `client.ts` declare the surface a theme may build against — the
  * set that ships as `@usequeek/theme-kit`.
  *
- * This is the kit-internal half of the contract: every module the barrels
- * declare must exist. (The storefront repo holds the other half —
- * `core-public-surface.test.ts` there asserts the barrels cover every module
- * the themes actually import.)
+ * Every module the barrels declare must exist.
  */
 describe('core public surface (kit-internal)', () => {
   const declared = new Set([...barrelModules('index.ts'), ...barrelModules('client.ts')]);

package/tests/shopper-chrome-strings.test.tsx

@@ -1,10 +1,9 @@
 /**
  * Shopper-chrome theme strings (checkout / auth / blog) — English-safety guard.
  *
- * Stage A: every state below was rendered against the PRE-migration code and
- * stored in `tests/fixtures/shopper-chrome-baseline.json`. Each case asserts
- * `.toBe` equality against that stored OLD markup, so ANY English change
- * (value, markup, attribute, plural) fails here. S4 drift guard + S7 proof.
+ * Each state below is rendered and compared with the markup stored in
+ * `tests/fixtures/shopper-chrome-baseline.json` (`.toBe` equality), so ANY
+ * English change (value, markup, attribute, plural) fails here.
  */
 import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
@@ -112,7 +111,7 @@ const AVATAR_USER = {
 function render(children: ReactNode): string {
   return renderToStaticMarkup(
     <StorefrontProvider
-      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
       config={{} as never}
       menus={[]}
     >
@@ -262,7 +261,7 @@ describe('shopper chrome English safety (checkout/auth/blog)', () => {
     });
   }
 
-  // S4 value guard: ShareButtons renders its copied branch only after a
+  // Value guard: ShareButtons renders its copied branch only after a
   // client-side clipboard write (internal useState, no prop), so no static
   // baseline can capture it. Pin the English through the real `t` instead —
   // any change to blog.share.copied fails here.

package/tests/storefront-client-scope.test.ts

@@ -4,11 +4,11 @@ import { join } from 'node:path';
 import { request } from '../sdk/client';
 
 /**
- * The storefront must ONLY ever call the `/v1/client/*` backend scope. That scope's
- * ResolveClientContext middleware resolves the vendor AND forces the platform
- * (storefront/instore_qr) — so prices are always the storefront's, never the
- * marketplace commission-inclusive price. Legacy v1 routes (/products, /vendors/*,
- * /categories, ...) bypass that middleware → wrong platform → wrong price.
+ * The storefront must ONLY ever call the `/v1/client/*` API scope. That scope
+ * resolves the vendor AND forces the platform (storefront/instore_qr) — so prices
+ * are always the storefront's, never the marketplace commission-inclusive price.
+ * Legacy v1 routes (/products, /vendors/*, /categories, ...) skip that
+ * resolution → wrong platform → wrong price.
  *
  * This guard prevents that whole class of bug from ever returning.
  */

package/tests/theme-hook-placement.test.tsx

@@ -1,5 +1,5 @@
 /**
- * Hook-placement rule (checkout / auth / blog slice) — S2 enforcement.
+ * Hook-placement rule for the checkout / auth / blog components.
  *
  * Rule: every `useThemeStrings()` call must sit at the top level of a
  * PascalCase component or a `use*` hook: no enclosing if / ternary / loop /
@@ -15,7 +15,7 @@ import ts from 'typescript';
 
 const kitRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 
-// Files this slice migrated: each must call useThemeStrings() exactly once.
+// Files that use theme strings: each must call useThemeStrings() exactly once.
 const EXPECTED_FILES = [
   'components/checkout/checkout-contact.tsx',
   'components/checkout/default-checkout-shell.tsx',

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

@@ -23,7 +23,7 @@ function render(
 ): string {
   return renderToStaticMarkup(
     <StorefrontProvider
-      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
       config={{} as never}
       menus={[]}
       {...(options?.locale !== undefined ? { locale: options.locale } : {})}
@@ -39,7 +39,7 @@ function Title(): JSX.Element {
   return <h1>{t('cart.title')}</h1>;
 }
 
-describe('client surface: StorefrontProvider strings + useThemeStrings (decision 4b)', () => {
+describe('client surface: StorefrontProvider strings + useThemeStrings', () => {
   it('renders the active locale through the hook', () => {
     expect(render(<Title />, { locale: 'fr', strings: FR_STRINGS })).toContain('<h1>Votre panier</h1>');
   });
@@ -105,7 +105,7 @@ describe('client surface through ThemeMount', () => {
   });
 });
 
-describe('manifest.strings travels with the theme (decision 15)', () => {
+describe('manifest.strings travels with the theme', () => {
   const MANIFEST_EN: ThemeStringsDictionary = {
     theme: {
       hero: { title: 'Fresh from the farm' },
@@ -216,10 +216,10 @@ describe('manifest.strings travels with the theme (decision 15)', () => {
     // No `strings` key at all: this literal must satisfy StorefrontContextValue
     // (it failed to compile while the field was required in 0.1.18).
     const value = {
-      vendor: { id: 'v1', slug: 'kili-foods', name: 'Kili Foods', logo: null } as VendorProfile,
+      vendor: { id: 'v1', slug: 'demo-store', name: 'Demo Store', logo: null } as VendorProfile,
       config: { theme: 'stub', brand: {} } as StorefrontConfig,
       menus: [],
-      basePath: '/kili-foods',
+      basePath: '/demo-store',
       pagesChrome: {},
       locale: null,
     };

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

@@ -17,7 +17,7 @@ const EN = enDefault as unknown as ThemeStringsDictionary;
 function render(children: ReactNode, strings: ThemeStringsDictionary | null): string {
   return renderToStaticMarkup(
     <StorefrontProvider
-      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
       config={{} as never}
       menus={[]}
       {...(strings ? { strings } : {})}

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

@@ -79,7 +79,7 @@ describe('typed keys: createThemeT (additive, opt-in)', () => {
   });
 
   it('drifts with the dictionary: the union is exactly the flattened keys', () => {
-    // Compile-time proof (positive direction; the negative direction — typos
+    // 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>> = [

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]);
@@ -240,12 +240,9 @@ describe('default English dictionary budget (backend varchar(64))', () => {
   flatten(enDefault, '', pairs);
 
   it('ships the ~106-string core dictionary (intentional growth, still budgeted)', () => {
-    // Dictionary budget: the checkout/auth/blog shopper-chrome slice added 31
-    // keys and removed 1 orphaned pre-existing key (auth.code.sent, 0 usages,
-    // superseded by auth.code.lead): 76 -> 106, commit 5cb67dd + orphan removal.
-    // The ceiling stays tight (+9 headroom): any further growth must bump it
-    // here deliberately with its own justification, which keeps guarding
-    // against uncontrolled growth (backend varchar(64) per-key budget below).
+    // 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).toBeLessThanOrEqual(115);
   });
@@ -257,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);
   });
 
@@ -272,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;
@@ -335,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/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;

package/types/theme.ts

@@ -254,9 +254,8 @@ export interface ThemeManifestVariant {
    * in vendor.ts) this variant's rendered markup actually consumes via CSS
    * vars, i.e. which controls a per-section `block.tokens` override on THIS
    * variant will visibly change. Authored next to the component/CSS that
-   * consumes the vars so it can't drift — flows verbatim through
-   * generate-theme-registry.ts → registry.json → Laravel's Theme.variants →
-   * ThemeManifestService (mirrors `fields`).
+   * consumes the vars so it can't drift — flows verbatim from the manifest
+   * through the theme registry to the API (mirrors `fields`).
    *
    * Granular per sub-control, NOT per parent dimension — `'shape'` is not a
    * valid entry; declare `'shape.radius'` and/or `'shape.border_weight'`
@@ -269,19 +268,17 @@ export interface ThemeManifestVariant {
    *
    * No back-compat default: an omitted `editable` (or an omitted leaf) means
    * NOT stylable for that control — every variant in every theme has an
-   * explicit, audited array as of the 2026-08-03 granular pass.
+   * explicit, audited array.
    */
   editable?: DesignTokenAxisPath[];
   /**
-   * Business buckets this variant is a strong fit for, as
-   * `config/category_packs.php` keys ONLY (queek_backend): food | supermarket |
-   * product | pharmacy | laundry | delivery | service | gas-refill |
-   * local_market. Omitted = universal. Authored next to the component (same
-   * anti-drift placement as `fields`/`editable`) and flows verbatim through
-   * generate-theme-registry.ts -> registry.json -> Laravel's Theme.variants ->
-   * ThemeManifestService, where BuildHomepageTool's scored resolver boosts a
-   * bucket match when auto-building a store. The backend matches buckets with
-   * `_`/`-` treated as equivalent.
+   * Business buckets this variant is a strong fit for, as category-pack keys
+   * ONLY: food | supermarket | product | pharmacy | laundry | delivery |
+   * service | gas-refill | local_market. Omitted = universal. Authored next to
+   * the component (same anti-drift placement as `fields`/`editable`) and flows
+   * verbatim through the theme registry to the API, where the AI store builder
+   * boosts a bucket match when auto-building a store. The API matches buckets
+   * with `_`/`-` treated as equivalent.
    */
   best_for?: string[];
   /**
@@ -342,13 +339,11 @@ export interface ThemeManifest {
   features?: string[];
   images?: Record<string, ThemeImageSpec>;
   /**
-   * Theme's default semantic design-token set (design-token-contract.md,
-   * queek_backend `.agent/.tmp/`) — the theme's current look expressed as
-   * tokens. Surfaced via `ThemeManifestService`/registry.json as the
-   * baseline the backend resolver layers vendor `tokens` overrides onto
-   * (theme defaults ← legacy fields ← vendor overrides). Optional during
-   * the pilot rollout — themes without it fall back to the storefront
-   * injector's own hardcoded defaults (`lib/core/utils/brand.ts`).
+   * Theme's default semantic design-token set — the theme's current look
+   * expressed as tokens. Surfaced through the theme registry as the baseline
+   * the API resolver layers vendor `tokens` overrides onto (theme defaults ←
+   * legacy fields ← vendor overrides). Optional — themes without it fall back
+   * to the token injector's own hardcoded defaults (`utils/brand.ts`).
    */
   tokens?: DesignTokens;
   /**
@@ -358,19 +353,25 @@ export interface ThemeManifest {
    * Same shape as the kit core English default
    * (nested objects by dot-path, or flat dotted keys; CLDR plural maps
    * allowed); keys follow the shared grammar (dotted lowercase, <= 40
-   * chars) because the backend overlay stores `<theme-slug>.<key>` in a
-   * varchar(64).
+   * chars) because merchant overrides are stored as `<theme-slug>.<key>` in a
+   * 64-character field.
    *
    * The kit layers it between the host-loaded locale dictionaries and the
    * kit core English, so ANY host that mounts the theme (vendor layout,
    * theme preview, CLI dev preview) renders the theme's English with zero
    * host cooperation — a host that passes nothing still shows English,
    * never empty labels. ENGLISH ONLY: non-English packs stay host-loaded
-   * per locale and are never bundled into the theme. Optional during the
-   * migration — a manifest without it behaves exactly as before (kit core
-   * English, then `''` for unknown keys).
+   * per locale and are never bundled into the theme. Optional — a manifest
+   * without it falls back to the kit core English, then `''` for unknown keys.
    */
   strings?: ThemeStringsDictionary;
+  /**
+   * Set to `'theme'` when the theme places the kit's `LanguageSwitcher`
+   * itself. The storefront then does not render its own floating language
+   * control, so the shopper sees exactly one. Optional — a manifest without
+   * it keeps the storefront's control for multi-language stores.
+   */
+  languageSwitcher?: 'theme';
 }
 
 /**