@usequeek/theme-kit 0.1.0

package/components/image.tsx

@@ -0,0 +1,149 @@
+'use client';
+
+import { useContext, useState, type ImgHTMLAttributes } from 'react';
+import { StorefrontContext } from '../provider';
+import type { ImageVariants } from '../types/media';
+import { resolveBrandPalette } from '../utils/brand-palette';
+import { resolveImageSources, type ImageIntent } from '../utils/image-srcset';
+import { resolvePlaceholder, type PlaceholderVariant } from '../utils/placeholder-resolver';
+
+/**
+ * Generic fallback used when the caller does not provide a `placeholder` prop.
+ * Kept for backward compatibility with existing <Image> call sites that have not
+ * yet been wired up to the Smart Placeholder system.
+ */
+const PLACEHOLDER_SVG = `data:image/svg+xml,${encodeURIComponent(
+  `<svg xmlns="http://www.w3.org/2000/svg" width="400" height="400" viewBox="0 0 400 400">
+    <rect width="400" height="400" fill="#f0f0f0"/>
+    <g transform="translate(150,150)" opacity="0.3">
+      <rect x="0" y="10" width="100" height="80" rx="8" fill="none" stroke="#999" stroke-width="4"/>
+      <circle cx="30" cy="35" r="10" fill="#999"/>
+      <polyline points="10,75 40,50 60,65 90,40" fill="none" stroke="#999" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+    </g>
+  </svg>`,
+)}`;
+
+export interface PlaceholderProp {
+  label?: string;
+  sublabel?: string;
+  width: number;
+  height: number;
+  variant?: PlaceholderVariant;
+}
+
+type ImageProps = ImgHTMLAttributes<HTMLImageElement> & {
+  fallback?: string;
+  placeholder?: PlaceholderProp;
+  /**
+   * The backend's srcset-ready tier map (product.media.image_variants,
+   * vendor.logo_variants, collection.image_variants, mediaIndex[url], …).
+   * Purely additive: when absent — as it is at every call site that hasn't been
+   * migrated, and whenever the backend legitimately sends null (off-host image,
+   * SVG, legacy upload) — this component behaves exactly as it did before.
+   */
+  variants?: ImageVariants | null;
+  /**
+   * What surface this image renders on. Drives which tier is preferred and what
+   * `sizes` is emitted. Only meaningful alongside `variants`. Defaults to 'raw'
+   * ("best available single url, no responsive selection") so passing `variants`
+   * without an `intent` can never accidentally downgrade a hero.
+   */
+  intent?: ImageIntent;
+};
+
+/**
+ * Where the <img> currently is in the fallback chain:
+ *   'primary'  — the resolved/passed src
+ *   'original' — retrying variants.original.url after the primary 404'd
+ *   'failed'   — give up, render `fallback` or the Smart Placeholder
+ */
+type LoadStage = 'primary' | 'original' | 'failed';
+
+export function Image({ fallback, placeholder, variants, intent = 'raw', onError, ...props }: ImageProps) {
+  const [stage, setStage] = useState<LoadStage>('primary');
+  // Read context directly — returns null outside a StorefrontProvider
+  // (test environments, isolated captures) without throwing.
+  const storefront = useContext(StorefrontContext);
+
+  const resolved = resolveImageSources(variants, intent);
+
+  // The resolved tier WINS over an explicitly-passed `src`. That's the whole
+  // point of threading `variants` down: the collapsed `src` field is the thing
+  // being downgraded away from. It's safe because resolveImageSources() enforces
+  // the intent ceiling — a capped intent can never resolve to `original`, so the
+  // result is always <= what `src` already implied. Call sites keep passing
+  // `src` unchanged; it stays the fallback for null/partial maps.
+  const primarySrc = resolved.src ?? (typeof props.src === 'string' ? props.src : undefined) ?? props.src;
+
+  // Reset the fallback chain when the underlying image changes (a reused card in
+  // a virtualized rail, a variant swap on the PDP) — without this, a component
+  // that already fell back to the placeholder for image A stays stuck on the
+  // placeholder forever even after being reused for a working image B. Render-
+  // phase derived-state, per React's "adjusting state when props change" — no
+  // extra commit, no effect.
+  const [lastKey, setLastKey] = useState<typeof primarySrc>(primarySrc);
+  if (primarySrc !== lastKey) {
+    setLastKey(primarySrc);
+    if (stage !== 'primary') setStage('primary');
+  }
+
+  const originalUrl = variants?.original?.url;
+  // Only worth a retry if it's a genuinely different url from the one that failed.
+  const canRetryOriginal = typeof originalUrl === 'string' && originalUrl !== '' && originalUrl !== primarySrc;
+
+  const hasSrc = !!primarySrc;
+  const needsPlaceholder = !hasSrc || stage === 'failed';
+
+  let placeholderSrc = fallback ?? PLACEHOLDER_SVG;
+
+  if (needsPlaceholder && placeholder) {
+    const palette = resolveBrandPalette(storefront?.config ?? null);
+    const font = storefront?.config?.brand?.font?.body ?? storefront?.config?.brand?.font?.heading;
+    placeholderSrc = resolvePlaceholder({
+      width: placeholder.width,
+      height: placeholder.height,
+      label: placeholder.label,
+      sublabel: placeholder.sublabel,
+      variant: placeholder.variant,
+      palette,
+      font,
+    });
+  }
+
+  let effectiveSrc = primarySrc;
+  // CRITICAL: srcSet/sizes must be dropped on every non-primary stage. A srcSet
+  // OUTRANKS src in the browser's selection algorithm, so leaving it in place
+  // while swapping src would make the browser re-pick the very candidate that
+  // just failed — the fallback would never render and onError would loop.
+  let effectiveSrcSet = resolved.srcSet;
+  let effectiveSizes = resolved.sizes;
+
+  if (stage === 'original') {
+    effectiveSrc = originalUrl;
+    effectiveSrcSet = undefined;
+    effectiveSizes = undefined;
+  }
+  if (needsPlaceholder) {
+    effectiveSrc = placeholderSrc;
+    effectiveSrcSet = undefined;
+    effectiveSizes = undefined;
+  }
+
+  return (
+    <img
+      {...props}
+      src={effectiveSrc}
+      srcSet={effectiveSrcSet}
+      sizes={effectiveSizes}
+      onError={(e) => {
+        // 2-step chain: preferred tier → variants.original → placeholder.
+        if (stage === 'primary') {
+          setStage(canRetryOriginal ? 'original' : 'failed');
+        } else if (stage === 'original') {
+          setStage('failed');
+        }
+        onError?.(e);
+      }}
+    />
+  );
+}

package/components/markdown.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import type { ComponentPropsWithoutRef } from 'react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { Image } from './image';
+
+/**
+ * Rich long-form markdown renderer for article bodies and callouts. Uses
+ * `react-markdown` + `remark-gfm` so headings, nested lists, code fences,
+ * tables, blockquotes, task lists, and inline formatting all render properly.
+ *
+ * Raw HTML is NOT enabled (react-markdown's default) — content is sanitized.
+ *
+ * Inline markdown images are routed through the core <Image> component so the
+ * Smart Placeholder / fallback system applies (never a bare, unoptimized
+ * <img>). Short-form snippets (footers, product blurbs) keep using the
+ * lightweight `renderMarkdown` helper in `lib/core/utils/markdown`.
+ */
+function MarkdownImage({ src, alt }: ComponentPropsWithoutRef<'img'>): JSX.Element | null {
+  if (!src || typeof src !== 'string') {
+    return null;
+  }
+
+  return (
+    <Image
+      src={src}
+      alt={alt ?? ''}
+      className="core-markdown__img"
+      loading="lazy"
+      placeholder={{ label: alt || undefined, width: 1200, height: 800, variant: 'photo' }}
+    />
+  );
+}
+
+function MarkdownLink({ href, children, ...rest }: ComponentPropsWithoutRef<'a'>): JSX.Element {
+  const isExternal = typeof href === 'string' && /^https?:\/\//.test(href);
+
+  return (
+    <a href={href} {...(isExternal ? { target: '_blank', rel: 'noopener noreferrer' } : {})} {...rest}>
+      {children}
+    </a>
+  );
+}
+
+export function Markdown({ children, className }: { children: string; className?: string }): JSX.Element {
+  return (
+    <div className={className}>
+      <ReactMarkdown remarkPlugins={[remarkGfm]} components={{ img: MarkdownImage, a: MarkdownLink }}>
+        {children ?? ''}
+      </ReactMarkdown>
+    </div>
+  );
+}

package/components/product-media-frame.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import { Image, type PlaceholderProp } from './image';
+import type { ImageIntent } from '../utils/image-srcset';
+import type { MediaFrame } from '../utils/product-media';
+
+interface ProductMediaFrameProps {
+  frame: MediaFrame;
+  className?: string;
+  placeholder?: PlaceholderProp;
+  /** 'main' (the selected/current frame) plays with controls. 'thumbnail'
+   *  renders muted with no controls — `preload="metadata"` makes the browser
+   *  show the video's first frame as a static image without playing it, the
+   *  same trick a poster image would achieve, with no separate poster asset. */
+  variant?: 'main' | 'thumbnail';
+  /** Override the intent derived from `variant` (e.g. a theme rendering the
+   *  main frame inside a narrow split-pane rather than a full-width hero). */
+  intent?: ImageIntent;
+}
+
+export function ProductMediaFrame({
+  frame,
+  className,
+  placeholder,
+  variant = 'main',
+  intent,
+}: ProductMediaFrameProps): JSX.Element {
+  if (frame.type === 'video') {
+    return (
+      <video
+        className={className}
+        src={frame.url}
+        aria-label={frame.alt}
+        controls={variant === 'main'}
+        muted={variant === 'thumbnail'}
+        playsInline
+        preload="metadata"
+      />
+    );
+  }
+
+  // Thumbnail strips render at ~64-90px across every theme — the `thumb` tier
+  // (a fixed-src, never-in-a-srcset tier by contract) is exactly right there.
+  const resolvedIntent: ImageIntent = intent ?? (variant === 'thumbnail' ? 'avatar' : 'hero');
+
+  return (
+    <Image
+      className={className}
+      src={frame.url}
+      alt={frame.alt}
+      placeholder={placeholder}
+      variants={frame.variants}
+      intent={resolvedIntent}
+    />
+  );
+}

package/components/variant-picker.css

@@ -0,0 +1,84 @@
+/* ============================================================
+   VariantPicker — shared option-selection UI (QR ordering sheet,
+   default theme's quick-view modal). Prefix: qk-variant-.
+   Reads --brand-* directly (not a context-scoped token set like
+   --qr- or --qka-) so it renders correctly regardless of which
+   surface mounts it. Mirrors quick-add-page.css's qka-option/qka-swatch
+   rules — same visual language, kept as a separate small file since
+   this component is reused outside that page's scope.
+   ============================================================ */
+
+.qk-variant-option {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.qk-variant-option + .qk-variant-option {
+  margin-top: 12px;
+}
+
+.qk-variant-option__label {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--brand-text-muted, #6b7280);
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.qk-variant-option__selected {
+  font-weight: 400;
+  text-transform: none;
+  letter-spacing: normal;
+  color: var(--brand-text, #1a1a1a);
+}
+
+.qk-variant-option__values {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.qk-variant-swatch {
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  border: 2px solid color-mix(in srgb, var(--brand-text, #1a1a1a) 12%, transparent);
+  padding: 0;
+  cursor: pointer;
+  overflow: hidden;
+  background-size: cover;
+  background-position: center;
+}
+
+.qk-variant-swatch.is-selected {
+  border-color: var(--brand-primary, #229879);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--brand-primary, #229879) 30%, transparent);
+}
+
+.qk-variant-swatch--image img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+.qk-variant-option__btn {
+  padding: 8px 14px;
+  border-radius: 999px;
+  border: 1px solid color-mix(in srgb, var(--brand-text, #1a1a1a) 12%, transparent);
+  background: var(--brand-surface, #ffffff);
+  color: var(--brand-text, #1a1a1a);
+  font-size: 0.85rem;
+  cursor: pointer;
+  transition: border-color 0.15s ease, background 0.15s ease;
+}
+
+.qk-variant-option__btn.is-selected {
+  border-color: var(--brand-primary, #229879);
+  background: color-mix(in srgb, var(--brand-primary, #229879) 12%, var(--brand-surface, #ffffff));
+  font-weight: 600;
+}

package/components/variant-picker.tsx

@@ -0,0 +1,107 @@
+'use client';
+
+import type { Product, ProductVariant } from '../types/product';
+import './variant-picker.css';
+
+interface VariantPickerProps {
+  product: Product;
+  selectedOptions: Record<string, string>;
+  onSelect: (optionName: string, value: string) => void;
+  className?: string;
+}
+
+/**
+ * Renders a product's option groups as color swatch / image swatch / text
+ * buttons — standard e-commerce priority: color_code first, else a
+ * representative image, else plain text. Extracted from quick-add-page.tsx
+ * (the channel/chat add-to-cart flow, the one place that already got this
+ * right) so the other two surfaces missing a picker entirely — the QR
+ * ordering sheet and the default theme's quick-view modal — can reuse it
+ * instead of a third reimplementation. Pair with `matchVariant()`
+ * (lib/core/utils/match-variant.ts) to resolve `selectedOptions` into a real
+ * `ProductVariant`, and gate the add action on that being non-null before
+ * calling `addProduct`/`addItemWithAddons` — a variant-enabled product added
+ * without one fails the cart save server-side (DiscountService's
+ * VariantSelectionException) rather than merely being "no variant"; there
+ * is no valid no-selection state to fall back to.
+ */
+export function VariantPicker({ product, selectedOptions, onSelect, className }: VariantPickerProps): JSX.Element | null {
+  if (product.options.length === 0) return null;
+
+  return (
+    <div className={className}>
+      {product.options.map((option) => {
+        const isColor = option.type === 'color' || option.values.some((v) => v.color_code);
+        const selectedValue = selectedOptions[option.name];
+
+        return (
+          <div className="qk-variant-option" key={option.name}>
+            <span className="qk-variant-option__label">
+              {option.name}
+              {selectedValue ? (
+                <span className="qk-variant-option__selected">
+                  {option.values.find((v) => v.value === selectedValue)?.label ?? selectedValue}
+                </span>
+              ) : null}
+            </span>
+            <div className="qk-variant-option__values">
+              {option.values.map((val) => {
+                const isSelected = selectedValue === val.value;
+                const handleSelect = (): void => onSelect(option.name, val.value);
+
+                if (isColor && val.color_code) {
+                  return (
+                    <button
+                      key={val.value}
+                      type="button"
+                      className={`qk-variant-swatch${isSelected ? ' is-selected' : ''}`}
+                      style={{ background: val.color_code }}
+                      title={val.label}
+                      aria-label={val.label}
+                      onClick={handleSelect}
+                    />
+                  );
+                }
+
+                if (val.image) {
+                  return (
+                    <button
+                      key={val.value}
+                      type="button"
+                      className={`qk-variant-swatch qk-variant-swatch--image${isSelected ? ' is-selected' : ''}`}
+                      title={val.label}
+                      aria-label={val.label}
+                      onClick={handleSelect}
+                    >
+                      <img src={val.image} alt={val.label} />
+                    </button>
+                  );
+                }
+
+                return (
+                  <button
+                    key={val.value}
+                    type="button"
+                    className={`qk-variant-option__btn${isSelected ? ' is-selected' : ''}`}
+                    onClick={handleSelect}
+                  >
+                    {val.label}
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/** True once every one of the product's option groups has a selected value —
+ *  the gate to check alongside `matchVariant(...) !== null` before allowing
+ *  an add. Centralized so both call sites stay in sync on the definition. */
+export function allVariantOptionsSelected(product: Product, selectedOptions: Record<string, string>): boolean {
+  return product.options.every((option) => Boolean(selectedOptions[option.name]));
+}
+
+export type { ProductVariant };

package/design-token-preview.tsx

@@ -0,0 +1,81 @@
+'use client';
+
+import { useEffect, type RefObject } from 'react';
+import { expandDesignTokens } from './utils/brand';
+import type { DesignTokens } from './types/vendor';
+
+interface DesignTokenPreviewMessage {
+  __queekEditor: true;
+  kind: 'design-tokens';
+  tokens?: DesignTokens | null;
+}
+
+interface StylableTarget {
+  style: {
+    setProperty(name: string, value: string): void;
+  };
+}
+
+/**
+ * SECURITY: only the exact editor shape is accepted — everything else
+ * (including other `postMessage` traffic already on this window, e.g. the
+ * `edit-mode-active.tsx` block-select/refresh bridge) is ignored.
+ */
+export function isDesignTokenPreviewMessage(data: unknown): data is DesignTokenPreviewMessage {
+  if (!data || typeof data !== 'object') return false;
+  const candidate = data as Record<string, unknown>;
+  return candidate.__queekEditor === true && candidate.kind === 'design-tokens';
+}
+
+/**
+ * Wires a `message` listener that overlays live `--var` writes onto
+ * `target.style` whenever a matching editor message arrives. Pure DOM
+ * wiring (no React) so it is directly unit-testable without a browser
+ * environment. Returns the disposer.
+ */
+export function attachDesignTokenPreviewListener(target: StylableTarget): () => void {
+  const onMessage = (event: MessageEvent): void => {
+    if (!isDesignTokenPreviewMessage(event.data)) return;
+
+    const vars = expandDesignTokens(event.data.tokens);
+    for (const [key, value] of Object.entries(vars)) {
+      target.style.setProperty(key, value);
+    }
+  };
+
+  window.addEventListener('message', onMessage);
+  return () => window.removeEventListener('message', onMessage);
+}
+
+/**
+ * Ephemeral live-preview overlay for the merchant editor. Active ONLY when
+ * embedded: the web dashboard's real preview iframe (`window.parent !==
+ * window`), or the mobile app's top-level WebView, which opts in explicitly
+ * via `?host=native` since it has no real parent frame to detect — real
+ * public storefront visits set neither, so the listener never installs
+ * (zero overhead). On a matching `{__queekEditor:true, kind:'design-tokens',
+ * tokens}` message, expands the tokens and writes every `--var` straight
+ * onto the brand-root element's inline style, overlaying (not replacing)
+ * the SSR vars from `getBrandCssVariables`. Never persisted — a normal
+ * navigation/refresh reloads the real config.
+ *
+ * Frozen protocol: queek_backend `.agent/.tmp/live-preview-protocol.md`.
+ */
+export function DesignTokenPreviewListener({
+  targetRef,
+}: {
+  targetRef: RefObject<HTMLElement | null>;
+}): null {
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined;
+    const isEmbedded = window.parent !== window || new URLSearchParams(location.search).get('host') === 'native';
+    if (!isEmbedded) return undefined;
+
+    const target = targetRef.current;
+    if (!target) return undefined;
+
+    return attachDesignTokenPreviewListener(target);
+  }, [targetRef]);
+
+  return null;
+}