@usequeek/theme-kit 0.1.10 → 0.1.12

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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

@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'vitest';
+import type { LegacyProductLike, Product } from '../types/product';
+import { normalizeProduct } from '../utils/product-normalizer';
+import { buildMediaFrames, getHoverImage, getSlideshowImages } from '../utils/product-media';
+
+function raw(overrides: LegacyProductLike = {}): LegacyProductLike {
+  return { id: 'p1', title: 'Ankara Gown', slug: 'ankara-gown', ...overrides };
+}
+
+function viewVariants(url: string) {
+  return {
+    thumb: null,
+    card: { url: '/card.jpg', w: 480, h: 480 },
+    card2x: { url: '/card2x.jpg', w: 800, h: 800 },
+    view: { url, w: 1600, h: 1600 },
+    original: { url: '/orig.jpg', w: 2400, h: 2400 },
+  };
+}
+
+describe('normalizeProduct images', () => {
+  it('carries backend images verbatim, ordered primary-first', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          thumbnail: 'https://cdn/x/thumb.jpg',
+          images: [
+            { id: 11, url: 'https://cdn/x/primary.jpg', alt: 'Front', variants: null },
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side', variants: viewVariants('https://cdn/x/side-view.jpg') },
+          ],
+        },
+      }),
+    );
+
+    expect(product.media.images).toHaveLength(2);
+    expect(product.media.images?.[0]).toMatchObject({ id: 11, url: 'https://cdn/x/primary.jpg' });
+    expect(product.media.images?.[1]?.variants).toMatchObject({ view: { url: 'https://cdn/x/side-view.jpg' } });
+    // The featured shortcut is untouched.
+    expect(product.media.image).toBe('https://cdn/x/primary.jpg');
+  });
+
+  it('drops blank entries from a provided images list', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          images: [
+            { id: 11, url: '', alt: 'Blank' },
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+          ],
+        },
+      }),
+    );
+
+    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', () => {
+    const product = normalizeProduct(
+      raw({
+        image: 'https://cdn/x/primary.jpg',
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          gallery: [
+            { id: 11, url: 'https://cdn/x/primary.jpg', alt: 'Dupe of primary' },
+            { id: 12, url: 'https://cdn/x/side.jpg', alt: 'Side' },
+            { id: 13, url: '', alt: 'Blank' },
+          ],
+        },
+      }),
+    );
+
+    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');
+  });
+
+  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']);
+
+    const none = normalizeProduct(raw({}));
+    expect(none.media.images).toEqual([]);
+    expect(none.media.gallery).toEqual([]);
+  });
+
+  it('falls back when a provided images list is entirely blank', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          gallery: [{ id: 12, url: 'https://cdn/x/side.jpg' }],
+          images: [{ id: 11, url: '' }],
+        },
+      }),
+    );
+
+    expect(product.media.images?.map((i) => i.url)).toEqual([
+      'https://cdn/x/primary.jpg',
+      'https://cdn/x/side.jpg',
+    ]);
+  });
+});
+
+describe('getHoverImage / getSlideshowImages', () => {
+  const product = (urls: string[]): Product =>
+    normalizeProduct(
+      raw({
+        media: {
+          image: urls[0] ?? null,
+          images: urls.map((url, i) => ({ id: i + 1, url })),
+        },
+      }),
+    );
+
+  it('returns images[1] and null unless two images exist', () => {
+    expect(getHoverImage(product([]))).toBeNull();
+    expect(getHoverImage(product(['https://cdn/x/a.jpg']))).toBeNull();
+    expect(getHoverImage(product(['https://cdn/x/a.jpg', 'https://cdn/x/b.jpg']))).toBe(
+      'https://cdn/x/b.jpg',
+    );
+  });
+
+  it('returns the ordered slideshow list', () => {
+    const list = getSlideshowImages(product(['https://cdn/x/a.jpg', 'https://cdn/x/b.jpg']));
+    expect(list.map((i) => i.url)).toEqual(['https://cdn/x/a.jpg', 'https://cdn/x/b.jpg']);
+  });
+
+  it('treats a missing images key as no slideshow', () => {
+    const legacy = normalizeProduct(raw({ image: 'https://cdn/x/a.jpg' }));
+    delete legacy.media.images;
+    expect(getSlideshowImages(legacy)).toEqual([]);
+    expect(getHoverImage(legacy)).toBeNull();
+  });
+});
+
+describe('buildMediaFrames reads images', () => {
+  it('renders identical frames for a legacy payload and its images-carrying twin', () => {
+    const legacy = 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' },
+          ],
+        },
+      }),
+    );
+    delete legacy.media.images;
+
+    const next = 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' },
+          ],
+        },
+      }),
+    );
+
+    const legacyUrls = buildMediaFrames(legacy).map((f) => f.url);
+    const nextUrls = buildMediaFrames(next).map((f) => f.url);
+    expect(nextUrls).toEqual(legacyUrls);
+    expect(nextUrls).toEqual([
+      'https://cdn/x/primary-orig.jpg',
+      'https://cdn/x/side.jpg',
+      'https://cdn/x/back.jpg',
+    ]);
+  });
+
+  it('prefers the view tier off images entries and appends video last', () => {
+    const product = normalizeProduct(
+      raw({
+        media: {
+          image: 'https://cdn/x/primary.jpg',
+          images: [
+            { id: 11, url: 'https://cdn/x/primary.jpg', variants: viewVariants('https://cdn/x/primary-view.jpg') },
+            { id: 12, url: 'https://cdn/x/side.jpg' },
+          ],
+          video_url: 'https://cdn/x/clip.mp4',
+        },
+      }),
+    );
+
+    const frames = buildMediaFrames(product);
+    expect(frames.map((f) => f.type)).toEqual(['image', 'image', 'video']);
+    expect(frames[0].url).toBe('https://cdn/x/primary-view.jpg');
+    expect(frames[2].url).toBe('https://cdn/x/clip.mp4');
+  });
+});

package/types/product.ts

@@ -28,10 +28,28 @@ export interface ProductShop {
   rating_count: number;
 }
 
+/**
+ * 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.
+ */
+export interface ProductImage {
+  id: string | number;
+  url: string;
+  alt?: string;
+  variants?: ImageVariants | null;
+}
+
 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. */
+  images?: ProductImage[];
   primary_variant_image?: string | null;
   video_url?: string | null;
   /** Falls back to `image` server-side when the vendor hasn't set an explicit
@@ -44,6 +62,10 @@ 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;

package/utils/product-media.ts

@@ -1,5 +1,5 @@
 import type { ImageVariants } from '../types/media';
-import type { Product } from '../types/product';
+import type { Product, ProductImage } from '../types/product';
 
 export interface MediaFrame {
   id: string;
@@ -21,47 +21,96 @@ function heroUrl(variants: ImageVariants | null | undefined): string | null {
   return variants?.view?.url ?? variants?.card2x?.url ?? null;
 }
 
+/**
+ * The ordered `media.images` list with blanks dropped — the single source
+ * for card hover/slideshow reads. Empty for products with no imagery at all.
+ */
+export function getSlideshowImages(product: Product): ProductImage[] {
+  const images = product.media.images;
+  if (!Array.isArray(images)) {
+    return [];
+  }
+
+  return images.filter(
+    (entry): entry is ProductImage =>
+      !!entry && typeof entry.url === 'string' && entry.url !== '',
+  );
+}
+
+/**
+ * The card hover-swap source: the second ordered image. Null unless the
+ * product carries at least two images — callers render the primary alone.
+ */
+export function getHoverImage(product: Product): string | null {
+  return getSlideshowImages(product)[1]?.url ?? 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.
+ *
+ * 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.
  */
 export function buildMediaFrames(product: Product): MediaFrame[] {
   const frames: MediaFrame[] = [];
-  const mainVariants = product.media.image_variants ?? null;
+  const images = getSlideshowImages(product);
 
-  if (product.media.image) {
-    frames.push({
-      id: 'main',
-      // WAS: `product.media.original ?? product.media.image` — which shipped the
-      // full raw original into every theme's PDP hero, unconditionally. Now the
-      // capped `view` tier (<=1600px webp) wins whenever the backend has one,
-      // and `original ?? image` survives untouched as the fallback for
-      // non-Media-backed images (external url, SVG, legacy upload) where
-      // image_variants is null. Themes that read `frame.url` directly get the
-      // downgrade for free; those that render through ProductMediaFrame also
-      // get a real srcset off `variants`.
-      url: heroUrl(mainVariants) ?? product.media.original ?? product.media.image,
-      alt: product.title,
-      type: 'image',
-      variants: mainVariants,
-    });
-  }
-
-  if (product.media.gallery) {
-    for (const item of product.media.gallery) {
+  if (images.length > 0) {
+    images.forEach((item, index) => {
       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,
+        id: index === 0 ? 'main' : String(item.id),
+        // Same hero-tier preference as the legacy path below: the capped
+        // `view` tier wins whenever the backend has one, and the raw
+        // `original` survives as the primary's fallback for non-Media-backed
+        // images where `variants` is null.
+        url:
+          heroUrl(itemVariants) ??
+          (index === 0 ? (product.media.original ?? item.url) : item.url),
         alt: item.alt ?? product.title,
         type: 'image',
         variants: itemVariants,
       });
+    });
+  } else {
+    const mainVariants = product.media.image_variants ?? null;
+
+    if (product.media.image) {
+      frames.push({
+        id: 'main',
+        // WAS: `product.media.original ?? product.media.image` — which shipped the
+        // full raw original into every theme's PDP hero, unconditionally. Now the
+        // capped `view` tier (<=1600px webp) wins whenever the backend has one,
+        // and `original ?? image` survives untouched as the fallback for
+        // non-Media-backed images (external url, SVG, legacy upload) where
+        // image_variants is null. Themes that read `frame.url` directly get the
+        // downgrade for free; those that render through ProductMediaFrame also
+        // get a real srcset off `variants`.
+        url: heroUrl(mainVariants) ?? product.media.original ?? product.media.image,
+        alt: product.title,
+        type: 'image',
+        variants: mainVariants,
+      });
+    }
+
+    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,
+        });
+      }
     }
   }
 

package/utils/product-normalizer.ts

@@ -3,6 +3,7 @@ import type {
   MetafieldValue,
   Product,
   ProductCategory,
+  ProductImage,
   ProductOption,
   ProductPricing,
   ProductVariantOptionValue,
@@ -209,6 +210,70 @@ function normalizeMetafields(raw: LegacyProductLike): Record<string, MetafieldVa
   return source as Record<string, MetafieldValue>;
 }
 
+function cleanUrl(value: unknown): string | null {
+  return typeof value === 'string' && value !== '' ? value : 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 `[]`.
+ */
+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);
+  }
+
+  const gallery = Array.isArray(media.gallery) ? media.gallery : [];
+  gallery.forEach((entry, index) => {
+    const url = entry ? cleanUrl(entry.url) : null;
+    if (!url || seen.has(url)) {
+      return;
+    }
+    seen.add(url);
+    items.push({
+      id: entry.id ?? `gallery-${index}`,
+      url,
+      alt: cleanUrl(entry.alt) ?? title,
+      variants: entry.variants ?? null,
+    });
+  });
+
+  return items;
+}
+
 export function normalizeProduct(raw: LegacyProductLike): Product {
   const shopId = String(raw.shop_id ?? raw.vendor_id ?? raw.shop?.id ?? raw.vendor?.id ?? '');
 
@@ -257,6 +322,10 @@ 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.
+      images: normalizeImages(raw),
       // Pass-through: gallery items carry their own `variants` (ProductResource::
       // buildGalleryPayload) and are not field-whitelisted here.
       gallery: raw.media?.gallery ?? [],