@usequeek/theme-kit 0.1.11 → 0.1.13

package/README.md

@@ -93,6 +93,35 @@ export default function ProductPage({ product, metafieldDefinitions }: ProductPa
 - Dynamic sources (`$source` refs) resolve server-side; block data always
   reaches the theme as literals — nothing to handle.
 
+## App blocks slot
+
+Product pages render merchant-placed app blocks through the slot — never app
+code:
+
+```tsx
+import { AppBlocks } from '@usequeek/theme-kit/apps';
+
+export default function ProductPage({ product }: ProductPageProps) {
+  return <AppBlocks target="product" productId={product.slug} />;
+}
+```
+
+- MUST: place `<AppBlocks target="product" productId={...} />` on the
+  product page. `target` is product-only in phase 1 — no other slot exists.
+  `productId` scopes availability reads and deep links to the shown product;
+  omit `vendorSlug` (the host resolves the store itself).
+- The host registers its placement component once through `AppBlocksProvider`
+  (`renderBlocks`); the slot renders whatever the host registered, or nothing
+  when no provider is mounted — never an error, never a shifted layout.
+- Empty and error states render nothing: a store with no placements ships no
+  markup and fires no request; a slow or dead app collapses to its fallback
+  and never breaks the page. No app HTML/JS ever reaches the theme — blocks
+  are Queek-rendered primitives (date/time/select) plus a deep-link CTA.
+- Style only: blocks emit `core-app-block` with `__title`, `__description`,
+  `__box`, `__skeleton*`, `__fallback*`, `__field`, `__label`, `__input`,
+  `__slots`/`__slot`, `__empty`, `__cta`, `__retry` and `__image` hooks. No
+  kit CSS ships for these — style them in your theme.
+
 ## Attribution: Powered by Queek
 
 Every storefront is a billboard — every footer variant of every theme renders

package/apps.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { createContext, useContext, type ComponentType, type JSX, type ReactNode } from 'react';
+
+/**
+ * Where a theme renders installed app blocks. Themes import this module,
+ * never app code — which framework and which storefront serves the blocks
+ * is Queek's decision, and a theme written against this slot keeps working
+ * when that changes. Only the host's registration does.
+ *
+ *   import { AppBlocks } from '@usequeek/theme-kit/apps';
+ *   <AppBlocks target="product" productId={product.slug} />
+ *
+ * The slot is deliberately presentation-free: the host registers its real
+ * placement component (fetch, loading shell, Queek-rendered blocks) through
+ * `AppBlocksProvider`, and the slot renders whatever the host registered.
+ * No provider (or none yet on the server) renders nothing — never an error,
+ * never a shifted layout.
+ */
+
+export type AppBlocksTarget = 'product';
+
+export interface AppBlocksRendererProps {
+  target: AppBlocksTarget;
+  productId?: string;
+  vendorSlug?: string;
+}
+
+export type AppBlocksRenderer = ComponentType<AppBlocksRendererProps>;
+
+const AppBlocksContext = createContext<AppBlocksRenderer | null>(null);
+
+/** The host wraps the theme tree and registers its placement component. */
+export function AppBlocksProvider({
+  renderBlocks,
+  children,
+}: {
+  renderBlocks: AppBlocksRenderer;
+  children: ReactNode;
+}): JSX.Element {
+  return <AppBlocksContext.Provider value={renderBlocks}>{children}</AppBlocksContext.Provider>;
+}
+
+/** The theme-facing slot: renders the host's component, or nothing. */
+export function AppBlocks({ target, productId, vendorSlug }: AppBlocksRendererProps): JSX.Element | null {
+  const RenderBlocks = useContext(AppBlocksContext);
+  if (RenderBlocks === null) return null;
+  return <RenderBlocks target={target} productId={productId} vendorSlug={vendorSlug} />;
+}

package/client.ts

@@ -7,6 +7,7 @@
 
 export * from './provider';
 export * from './navigation';
+export * from './apps';
 export * from './page-renderer';
 export * from './edit-mode';
 export * from './theme-variant-resolver';

package/hooks/use-products.ts

@@ -145,12 +145,14 @@ export function useProducts(options?: ProductQuery & {
 
 /**
  * Full product detail (the same `/products/{slug}` request the PDP itself
- * uses), including the real `media.gallery` — the list/collection endpoints
- * `useProducts` calls only ever return `media.{image,thumbnail}` (see
+ * uses), including the full ordered detail `media.images` list — the
+ * list/collection endpoints `useProducts` calls only ever return the capped
+ * `media.images` list (`media.listing.images_limit`, config/media.php:15)
+ * plus `media.{image,thumbnail}` (see
  * Customer\ProductResource::buildBaseMediaPayload vs buildDetailMediaPayload
  * in queek_backend). Single-product spotlight blocks (e.g. glow's `featured`
  * variant) need this instead of substituting image/thumbnail as a fake
- * 2-image gallery.
+ * 2-image list.
  */
 /**
  * Fetch one product by SLUG.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

package/tests/apps.test.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import * as apps from '../apps';
+import { AppBlocks, AppBlocksProvider } from '../apps';
+
+describe('apps — the theme-facing app-block slot', () => {
+  it('is exactly the provider, the slot, and the shared types', () => {
+    expect(Object.keys(apps).sort()).toEqual(['AppBlocks', 'AppBlocksProvider']);
+  });
+
+  it('renders nothing without a host registration (SSR-safe)', () => {
+    const html = renderToStaticMarkup(
+      React.createElement(AppBlocks, { target: 'product', productId: 'p1' }),
+    );
+
+    expect(html).toBe('');
+  });
+
+  it('renders whatever the host registered, with the slot props', () => {
+    function HostBlocks({ target, productId }: { target: 'product'; productId?: string }) {
+      return <div data-host-blocks={`${target}:${productId ?? ''}`} />;
+    }
+
+    const html = renderToStaticMarkup(
+      <AppBlocksProvider renderBlocks={HostBlocks}>
+        <AppBlocks target="product" productId="p1" vendorSlug="glow" />
+      </AppBlocksProvider>,
+    );
+
+    expect(html).toContain('data-host-blocks="product:p1"');
+  });
+});

package/tests/product-images.test.ts

@@ -55,7 +55,38 @@ describe('normalizeProduct images', () => {
     expect(product.media.images?.map((i) => i.url)).toEqual(['https://cdn/x/side.jpg']);
   });
 
-  it('falls back to gallery/image for old payloads: primary first, dupes removed', () => {
+  it('ignores a legacy gallery key: images come from images only', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          images: [{ id: 11, url: 'https://cdn/x/primary.jpg', alt: 'Front' }],
+          gallery: [
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+            { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
+          ],
+        } as LegacyProductLike['media'],
+      }),
+    );
+
+    expect(product.media.images?.map((i) => i.url)).toEqual(['https://cdn/x/primary.jpg']);
+    expect(product.media).not.toHaveProperty('gallery');
+  });
+
+  it('rejects a misspelled images key at compile time instead of silently yielding []', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          // @ts-expect-error `imagess` is not a media key — the narrowed type turns this typo into a compile error, not a [].
+          imagess: [{ id: 1, url: 'https://cdn/x/a.jpg' }],
+        },
+      }),
+    );
+
+    expect(product.media.images).toEqual([]);
+  });
+
+  it('derives nothing from image/gallery on old payloads: no images list means []', () => {
     const product = normalizeProduct(
       raw({
         image: 'https://cdn/x/primary.jpg',
@@ -66,41 +97,36 @@ describe('normalizeProduct images', () => {
             { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
             { id: 13, url: '', alt: 'Blank' },
           ],
-        },
+        } as LegacyProductLike['media'],
       }),
     );
 
-    expect(product.media.images?.map((i) => i.url)).toEqual([
-      'https://cdn/x/primary.jpg',
-      'https://cdn/x/side.jpg',
-    ]);
-    expect(product.media.images?.[0].id).toBe('main');
+    expect(product.media.images).toEqual([]);
+    expect(product.media).not.toHaveProperty('gallery');
+    // The primary shortcut itself is untouched.
+    expect(product.media.image).toBe('https://cdn/x/primary.jpg');
   });
 
-  it('falls back to a raw-URL-only single and to [] when there is no imagery', () => {
-    const single = normalizeProduct(raw({ image: 'https://cdn/x/only.jpg' }));
-    expect(single.media.images?.map((i) => i.url)).toEqual(['https://cdn/x/only.jpg']);
-
+  it('yields [] for a payload with no imagery at all and no gallery key', () => {
     const none = normalizeProduct(raw({}));
+
     expect(none.media.images).toEqual([]);
-    expect(none.media.gallery).toEqual([]);
+    expect(none.media).not.toHaveProperty('gallery');
   });
 
-  it('falls back when a provided images list is entirely blank', () => {
+  it('yields [] when a provided images list is entirely blank, even with gallery present', () => {
     const product = normalizeProduct(
       raw({
         media: {
           image: 'https://cdn/x/primary.jpg',
           gallery: [{ id: 12, url: 'https://cdn/x/side.jpg' }],
           images: [{ id: 11, url: '' }],
-        },
+        } as LegacyProductLike['media'],
       }),
     );
 
-    expect(product.media.images?.map((i) => i.url)).toEqual([
-      'https://cdn/x/primary.jpg',
-      'https://cdn/x/side.jpg',
-    ]);
+    expect(product.media.images).toEqual([]);
+    expect(product.media).not.toHaveProperty('gallery');
   });
 });
 
@@ -137,47 +163,61 @@ describe('getHoverImage / getSlideshowImages', () => {
 });
 
 describe('buildMediaFrames reads images', () => {
-  it('renders identical frames for a legacy payload and its images-carrying twin', () => {
-    const legacy = normalizeProduct(
+  it('renders identical frames with and without a legacy gallery key present', () => {
+    const images = [
+      { id: 11, url: 'https://cdn/x/primary.jpg', alt: 'Ankara Gown' },
+      { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+      { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
+    ];
+    const withGallery = normalizeProduct(
       raw({
         media: {
           image: 'https://cdn/x/primary.jpg',
           original: 'https://cdn/x/primary-orig.jpg',
-          gallery: [
-            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
-            { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
-          ],
-        },
+          gallery: [{ id: 99, url: 'https://cdn/x/stale.jpg', alt: 'Stale' }],
+          images,
+        } as LegacyProductLike['media'],
       }),
     );
-    delete legacy.media.images;
 
-    const next = normalizeProduct(
+    const stripped = normalizeProduct(
       raw({
         media: {
           image: 'https://cdn/x/primary.jpg',
           original: 'https://cdn/x/primary-orig.jpg',
-          gallery: [
-            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
-            { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
-          ],
-          images: [
-            { id: 11, url: 'https://cdn/x/primary.jpg', alt: 'Ankara Gown' },
-            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
-            { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
-          ],
+          images,
         },
       }),
     );
 
-    const legacyUrls = buildMediaFrames(legacy).map((f) => f.url);
-    const nextUrls = buildMediaFrames(next).map((f) => f.url);
-    expect(nextUrls).toEqual(legacyUrls);
-    expect(nextUrls).toEqual([
+    const withUrls = buildMediaFrames(withGallery).map((f) => f.url);
+    const strippedUrls = buildMediaFrames(stripped).map((f) => f.url);
+    expect(withUrls).toEqual(strippedUrls);
+    expect(withUrls).toEqual([
       'https://cdn/x/primary-orig.jpg',
       'https://cdn/x/side.jpg',
       'https://cdn/x/back.jpg',
     ]);
+    expect(withUrls).not.toContain('https://cdn/x/stale.jpg');
+  });
+
+  it('builds no frames from a gallery-only payload: gallery urls never render', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          gallery: [
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+            { id: 13, url: 'https://cdn/x/back.jpg', alt: 'Back' },
+          ],
+        } as LegacyProductLike['media'],
+      }),
+    );
+
+    // Only the media.image primary single-frame fallback survives — the
+    // gallery urls are ignored, not derived into images.
+    expect(product.media.images).toEqual([]);
+    expect(buildMediaFrames(product).map((f) => f.url)).toEqual(['https://cdn/x/primary.jpg']);
   });
 
   it('prefers the view tier off images entries and appends video last', () => {

package/types/product.ts

@@ -32,7 +32,7 @@ export interface ProductShop {
  * One entry of the ordered `images` list (backend
  * `CustomerProductMedia::orderedImages()`): primary first,
  * `{id, url, alt, variants}`. The listing payload caps the list
- * (`media.listing.images_limit`); detail/PDP carries the full gallery.
+ * (`media.listing.images_limit`); detail/PDP carries the full list.
  */
 export interface ProductImage {
   id: string | number;
@@ -45,10 +45,10 @@ export interface ProductMedia {
   thumbnail: string | null;
   image: string | null;
   original?: string | null;
-  /** The ONE ordered product-image list, primary first. Present on both list
-   *  and detail responses once the backend emits it; the normalizer derives
-   *  it from `gallery`/`image` for older payloads, so readers must treat it
-   *  as always available and never build a second ordering. */
+  /** The ONE ordered product-image list, primary first. Emitted by the
+   *  backend on kit-consumed list/detail (preloaded) payloads and built by
+   *  the normalizer from `images` only — readers must treat it as always
+   *  available and never build a second ordering. */
   images?: ProductImage[];
   primary_variant_image?: string | null;
   video_url?: string | null;
@@ -62,19 +62,6 @@ export interface ProductMedia {
   image_variants?: ImageVariants | null;
   /** Sibling to `primary_variant_image`, same contract. */
   primary_variant_image_variants?: ImageVariants | null;
-  /**
-   * @deprecated Use `images` instead — frozen legacy alias of the same
-   *  ordered list (primary first), kept for existing clients. Never extend.
-   */
-  gallery?: Array<{
-    id: string | number;
-    url: string;
-    alt?: string;
-    /** Per-gallery-item tier map (ProductResource::buildGalleryPayload).
-     *  Detail responses only — the list payload has no `gallery` at all.
-     *  Note `url` here is already the CARD url server-side, not the original. */
-    variants?: ImageVariants | null;
-  }>;
 }
 
 export interface ProductInventory {
@@ -293,6 +280,9 @@ export interface LegacyProductLike {
   pricing?: Partial<ProductPricing>;
   inventory?: Partial<ProductInventory>;
   flags?: Partial<ProductFlags>;
+  // A runtime legacy `gallery` key (still emitted by the backend detail
+  // payload) arrives via the cast path only — never re-add it here, and
+  // never derive `images` from it. Tests cast gallery-bearing literals.
   media?: Partial<ProductMedia>;
   categories?: Array<Partial<ProductCategory>>;
   options?: Array<{

package/utils/product-media.ts

@@ -46,15 +46,17 @@ export function getHoverImage(product: Product): string | null {
 }
 
 /**
- * Builds the ordered list of PDP gallery frames for a product: main image,
- * then gallery images, then the product video (if any) appended last — was
- * duplicated verbatim as `buildFrames`/`buildGalleryFrames` in every theme's
- * pages/product.tsx; centralized here per the project's reuse-over-duplication
- * rule. Pair with `ProductMediaFrame` to render whatever comes back.
+ * Builds the ordered list of PDP media frames for a product from the ONE
+ * ordered `media.images` list (primary first), then the product video (if
+ * any) appended last — was duplicated verbatim as
+ * `buildFrames`/`buildGalleryFrames` in every theme's pages/product.tsx;
+ * centralized here per the project's reuse-over-duplication rule. Pair with
+ * `ProductMediaFrame` to render whatever comes back.
  *
- * Reads `media.images` (primary first) when present and falls back to the
- * legacy main+`gallery` pair for older payloads — same frames either way, so
- * no visual change, only the data source moves to the ONE ordered list.
+ * `images` is the only frame source: a legacy `gallery` key is never read.
+ * When `images` is empty the `media.image` primary still yields a single
+ * frame so imageless-list payloads keep their primary — no second ordering
+ * is ever built.
  */
 export function buildMediaFrames(product: Product): MediaFrame[] {
   const frames: MediaFrame[] = [];
@@ -98,20 +100,6 @@ export function buildMediaFrames(product: Product): MediaFrame[] {
       });
     }
 
-    if (product.media.gallery) {
-      for (const item of product.media.gallery) {
-        const itemVariants = item.variants ?? null;
-        frames.push({
-          id: String(item.id),
-          // item.url is already the CARD url server-side (480px) — too small for a
-          // main hero frame, which is why the `view` tier is preferred here too.
-          url: heroUrl(itemVariants) ?? item.url,
-          alt: item.alt ?? product.title,
-          type: 'image',
-          variants: itemVariants,
-        });
-      }
-    }
   }
 
   if (frames.length === 0 && product.media.thumbnail) {

package/utils/product-normalizer.ts

@@ -215,63 +215,36 @@ function cleanUrl(value: unknown): string | null {
 }
 
 /**
- * The ONE ordered product-image list, primary first. A backend that already
- * emits `media.images` wins verbatim (order preserved, entries cleaned);
- * older payloads fall back to the `gallery`/`image` pair — primary first,
- * then gallery items, skipping blanks and url-dupes of the primary. Never
- * an empty-string url, never a null: no-media products get `[]`.
+ * The ONE ordered product-image list, primary first, built from
+ * `media.images` ONLY (order preserved, entries cleaned). A legacy `gallery`
+ * key on the payload is ignored — never derived, never passed through.
+ * Never an empty-string url, never a null: products without an `images`
+ * list get `[]`.
  */
 function normalizeImages(raw: LegacyProductLike): ProductImage[] {
   const media = raw.media ?? {};
   const title = typeof raw.title === 'string' ? raw.title : '';
 
   const provided = media.images;
-  if (Array.isArray(provided) && provided.length > 0) {
-    const cleaned = provided.flatMap((entry, index): ProductImage[] => {
-      const url = entry ? cleanUrl(entry.url) : null;
-      if (!url) {
-        return [];
-      }
-
-      return [
-        {
-          id: entry.id ?? `image-${index}`,
-          url,
-          alt: cleanUrl(entry.alt) ?? title,
-          variants: entry.variants ?? null,
-        },
-      ];
-    });
-    if (cleaned.length > 0) {
-      return cleaned;
-    }
-  }
-
-  const primary = cleanUrl(media.image) ?? cleanUrl(raw.image);
-  const seen = new Set<string>();
-  const items: ProductImage[] = [];
-
-  if (primary) {
-    items.push({ id: 'main', url: primary, alt: title, variants: media.image_variants ?? null });
-    seen.add(primary);
+  if (!Array.isArray(provided) || provided.length === 0) {
+    return [];
   }
 
-  const gallery = Array.isArray(media.gallery) ? media.gallery : [];
-  gallery.forEach((entry, index) => {
+  return provided.flatMap((entry, index): ProductImage[] => {
     const url = entry ? cleanUrl(entry.url) : null;
-    if (!url || seen.has(url)) {
-      return;
+    if (!url) {
+      return [];
     }
-    seen.add(url);
-    items.push({
-      id: entry.id ?? `gallery-${index}`,
-      url,
-      alt: cleanUrl(entry.alt) ?? title,
-      variants: entry.variants ?? null,
-    });
-  });
 
-  return items;
+    return [
+      {
+        id: entry.id ?? `image-${index}`,
+        url,
+        alt: cleanUrl(entry.alt) ?? title,
+        variants: entry.variants ?? null,
+      },
+    ];
+  });
 }
 
 export function normalizeProduct(raw: LegacyProductLike): Product {
@@ -322,13 +295,9 @@ export function normalizeProduct(raw: LegacyProductLike): Product {
       // covers a preview/demo payload that happens to nest them there too.
       video_url: raw.media?.video_url ?? raw.video_url ?? null,
       video_poster_url: raw.media?.video_poster_url ?? raw.video_poster_url ?? null,
-      // The ONE ordered list (primary first) — backend `images` verbatim when
-      // present, else derived from gallery/image above. `gallery` stays as
-      // the deprecated frozen alias for existing readers.
+      // The ONE ordered list (primary first) — backend `images` verbatim,
+      // cleaned. No `gallery` passthrough: legacy keys are ignored.
       images: normalizeImages(raw),
-      // Pass-through: gallery items carry their own `variants` (ProductResource::
-      // buildGalleryPayload) and are not field-whitelisted here.
-      gallery: raw.media?.gallery ?? [],
     },
     inventory: {
       in_stock: toBool(raw.inventory?.in_stock, toBool(raw.in_stock, toNumber(raw.stock, 0) > 0)),