@usequeek/theme-kit 0.1.0

package/utils/image-srcset.ts

@@ -0,0 +1,157 @@
+import type { ImageVariantTier, ImageVariantTierName, ImageVariants } from '../types/media';
+
+/**
+ * What surface is this image being rendered on. Chosen by the CALL SITE, which
+ * is the only thing that knows the CSS box — the helper never guesses.
+ *
+ * `card2x` is its own intent rather than just a rung on `card`'s ladder: the
+ * tier names and the intent names are deliberately decoupled. `card` and
+ * `card2x` build the SAME srcset ladder; they differ only in `sizes`, because
+ * this codebase has two genuinely different card sizes — the grid card
+ * (~320px CSS) and the featured/poster card (~620px CSS). Both would
+ * otherwise get the identical 480px `card` url, visibly soft on the poster
+ * ones.
+ */
+export type ImageIntent = 'avatar' | 'card' | 'card2x' | 'modal' | 'hero' | 'raw';
+
+export interface ResolvedImageSources {
+  src: string | undefined;
+  srcSet: string | undefined;
+  sizes: string | undefined;
+}
+
+const NONE: ResolvedImageSources = { src: undefined, srcSet: undefined, sizes: undefined };
+
+/** Ascending by cap. `thumb` is excluded by contract rule 5; `original` is
+ *  excluded on purpose — it is uncapped and unoptimized (raw jpg/png, possibly
+ *  6000px), so letting a browser pick it off a srcset is the exact regression
+ *  this whole effort exists to remove. `original` survives only as a last-resort
+ *  `src` for the `raw` intent and as the onError step-2 retry. */
+const SRCSET_TIERS = ['card', 'card2x', 'view'] as const;
+type SrcSetTier = (typeof SRCSET_TIERS)[number];
+
+/**
+ * DOWNGRADE-ONLY ENFORCEMENT. The largest tier an intent is ever allowed to
+ * reach — for both `src` and `srcSet`. A capped intent can never resolve to
+ * `original`, so wiring `intent="card"` onto a call site that today ships the
+ * full original is guaranteed to be a downgrade or a no-op, never an upgrade.
+ */
+const INTENT_CEILING: Record<ImageIntent, SrcSetTier | null> = {
+  avatar: null, // fixed src off `thumb`, no srcset (rule 5)
+  card: 'card2x',
+  card2x: 'view',
+  modal: 'card2x',
+  hero: 'view',
+  raw: null, // "best single url, no responsive selection"
+};
+
+/**
+ * `sizes` per intent, derived from a survey of the 9 themes' real CSS grid
+ * breakpoints, validated against the real tier caps (480 / 800 / 1600):
+ *
+ *  card    @768px→384css: DPR1→card(480) · DPR2→768→card2x(800)
+ *          @1100px→363css: DPR2→726→card2x · desktop 320css: DPR2→640→card2x
+ *  card2x  @768px→768css: DPR2→1536→view(1600) · desktop 620css: DPR2→1240→view
+ *  modal   420css: DPR1→420→card(480) · DPR2→840→card2x(800, the ceiling)
+ *  hero    desktop 700css: DPR1→700→view · DPR2→1400→view(1600)
+ *
+ * `modal` is written as a media query (`(max-width: 456px) 92vw, 420px`,
+ * arithmetically identical to `min(420px, 92vw)`: 420/0.92 = 456.5) rather
+ * than relying on CSS math functions inside `sizes` — support for those is
+ * uneven, and a `sizes` the parser rejects silently degrades to 100vw, i.e.
+ * the browser picks the LARGEST candidate, the opposite of what we want.
+ */
+const INTENT_SIZES: Record<ImageIntent, string | undefined> = {
+  avatar: undefined,
+  card: '(max-width: 768px) 50vw, (max-width: 1100px) 33vw, 320px',
+  card2x: '(max-width: 768px) 100vw, (max-width: 1100px) 50vw, 620px',
+  modal: '(max-width: 456px) 92vw, 420px',
+  hero: '(max-width: 900px) calc(100vw - 32px), 700px',
+  raw: undefined,
+};
+
+/** Preference order for the plain `src`. Every list respects INTENT_CEILING —
+ *  no capped intent can reach `original`. */
+const INTENT_SRC_ORDER: Record<ImageIntent, ImageVariantTierName[]> = {
+  avatar: ['thumb', 'card'],
+  card: ['card', 'card2x'],
+  card2x: ['card2x', 'view', 'card'],
+  modal: ['card2x', 'card'],
+  // Deliberately NO 'card' fallback: `hero` callers (buildMediaFrames'
+  // heroUrl()) already fall back to the true raw original — a genuinely
+  // sharper image — when view/card2x don't exist yet for a product. If this
+  // list included 'card' here, resolveImageSources would silently win over
+  // that caller-provided `src` with the much smaller 480px tier, undoing the
+  // very fallback the caller carefully picked. Returning undefined instead
+  // lets the Image component's `resolved.src ?? props.src` defer to it.
+  hero: ['view', 'card2x'],
+  raw: ['original', 'view', 'card2x', 'card', 'thumb'],
+};
+
+function usableTier(tier: ImageVariantTier | null | undefined): tier is ImageVariantTier {
+  return !!tier && typeof tier.url === 'string' && tier.url.trim() !== '';
+}
+
+/**
+ * Resolves a tier map + a surface intent into the three <img> attributes.
+ *
+ * Guarantees:
+ *  - null/undefined `variants` → every field undefined, so the caller's own
+ *    `src` prop keeps winning and behavior is byte-identical to today.
+ *  - never emits `thumb` in a srcset.
+ *  - never invents a url; null tiers are simply skipped.
+ *  - never exceeds the intent's ceiling (downgrade-only).
+ *  - dedupes candidates that collapsed to the same width on a small original,
+ *    and drops the srcset entirely if fewer than 2 distinct widths survive
+ *    (a 1-candidate srcset is pure byte overhead).
+ *  - only emits `sizes` alongside a real `srcSet`.
+ */
+export function resolveImageSources(
+  variants: ImageVariants | null | undefined,
+  intent: ImageIntent,
+): ResolvedImageSources {
+  if (!variants) {
+    return NONE;
+  }
+
+  let src: string | undefined;
+  for (const name of INTENT_SRC_ORDER[intent]) {
+    const tier = variants[name];
+    if (usableTier(tier)) {
+      src = tier.url;
+      break;
+    }
+  }
+
+  const ceiling = INTENT_CEILING[intent];
+  if (ceiling === null) {
+    return { src, srcSet: undefined, sizes: undefined };
+  }
+
+  const limit = SRCSET_TIERS.indexOf(ceiling);
+  const byWidth = new Map<number, string>();
+  for (let i = 0; i <= limit; i += 1) {
+    const tier = variants[SRCSET_TIERS[i]];
+    // A tier with no usable width can't carry a `w` descriptor, and mixing
+    // `w` and bare descriptors in one srcset makes the whole attribute invalid.
+    if (!usableTier(tier) || typeof tier.w !== 'number' || !Number.isFinite(tier.w) || tier.w <= 0) {
+      continue;
+    }
+    // First writer wins: SRCSET_TIERS is ascending by cap, so at a collapsed
+    // width the lower-cap encode (the smaller file) is the one we keep.
+    if (!byWidth.has(tier.w)) {
+      byWidth.set(tier.w, tier.url);
+    }
+  }
+
+  if (byWidth.size < 2) {
+    return { src, srcSet: undefined, sizes: undefined };
+  }
+
+  const srcSet = [...byWidth.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([w, url]) => `${url} ${w}w`)
+    .join(', ');
+
+  return { src, srcSet, sizes: INTENT_SIZES[intent] };
+}

package/utils/markdown.tsx

@@ -0,0 +1,237 @@
+import type { JSX } from 'react';
+import { Fragment } from 'react';
+
+/**
+ * Strip markdown syntax to plain text. Use for previews / single-line contexts
+ * (cards, modals, meta descriptions) where formatting must not appear.
+ */
+export function stripMarkdown(text: string): string {
+  return text
+    .replace(/!\[[^\]]*\]\([^)]+\)/g, '') // images
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // links → label
+    .replace(/(\*\*|__)(.*?)\1/g, '$2') // bold
+    .replace(/(\*|_)(.*?)\1/g, '$2') // italic
+    .replace(/`([^`]+)`/g, '$1') // inline code
+    .replace(/^#{1,6}\s+/gm, '') // headings
+    .replace(/^\s*[-*+]\s+/gm, '') // unordered list markers
+    .replace(/^\s*\d+\.\s+/gm, '') // ordered list markers
+    .replace(/^\s*>\s?/gm, '') // blockquote markers
+    .replace(/\n{2,}/g, ' ')
+    .replace(/\n/g, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+// Matches ![alt](url) image, **bold**, __bold__, *italic*, _italic_, `code`, [label](url).
+// Image before link (image is a superset starting with `!`); bold before italic.
+const INLINE_RE = /(!\[[^\]]*\]\([^)]+\)|\*\*[^*]+\*\*|__[^_]+__|\*[^*]+\*|_[^_]+_|`[^`]+`|\[[^\]]+\]\([^)]+\))/g;
+
+// A root-relative internal link ("/about") is correct as-is on a real vendor's
+// own domain (where the storefront IS the domain root), but the exact same
+// content also renders inside `/preview/[theme]/*`, where the theme's own
+// pages live under a `/preview/<slug>` prefix — without this, every internal
+// link written into admin-editable markdown (footer columns, taglines, page
+// content) 404s in preview. Only touches root-relative paths; external URLs,
+// hash anchors, and empty basePath (the real-vendor case) pass through
+// untouched.
+function withBasePath(href: string, basePath?: string): string {
+  if (!basePath || !href.startsWith('/') || href.startsWith('//')) return href;
+  return `${basePath}${href}`;
+}
+
+function parseInline(text: string, keyPrefix: string, basePath?: string): React.ReactNode[] {
+  const parts = text.split(INLINE_RE).filter(Boolean);
+
+  return parts.map((part, index) => {
+    const key = `${keyPrefix}-${index}`;
+
+    if ((part.startsWith('**') && part.endsWith('**')) || (part.startsWith('__') && part.endsWith('__'))) {
+      return <strong key={key}>{part.slice(2, -2)}</strong>;
+    }
+
+    if ((part.startsWith('*') && part.endsWith('*')) || (part.startsWith('_') && part.endsWith('_'))) {
+      return <em key={key}>{part.slice(1, -1)}</em>;
+    }
+
+    if (part.startsWith('`') && part.endsWith('`')) {
+      return <code key={key}>{part.slice(1, -1)}</code>;
+    }
+
+    const imageMatch = part.match(/^!\[([^\]]*)\]\(([^)]+)\)$/);
+    if (imageMatch) {
+      const [, alt, src] = imageMatch;
+      // eslint-disable-next-line @next/next/no-img-element
+      return (
+        <img
+          key={key}
+          src={src}
+          alt={alt}
+          loading="lazy"
+          style={{ maxWidth: '100%', height: 'auto', display: 'block' }}
+        />
+      );
+    }
+
+    const linkMatch = part.match(/^\[([^\]]+)\]\(([^)]+)\)$/);
+    if (linkMatch) {
+      const [, label, href] = linkMatch;
+      const isExternal = href.startsWith('http://') || href.startsWith('https://');
+      return (
+        <a key={key} href={withBasePath(href, basePath)} {...(isExternal ? { target: '_blank', rel: 'noopener noreferrer' } : {})}>
+          {label}
+        </a>
+      );
+    }
+
+    return <Fragment key={key}>{part}</Fragment>;
+  });
+}
+
+// Render the lines of a single paragraph block, preserving single line breaks as <br>.
+function renderParagraphLines(block: string, keyPrefix: string, basePath?: string): React.ReactNode[] {
+  const lines = block.split('\n');
+  return lines.flatMap((line, i) => {
+    const content = parseInline(line, `${keyPrefix}-l${i}`, basePath);
+    return i < lines.length - 1
+      ? [...content, <br key={`${keyPrefix}-br${i}`} />]
+      : content;
+  });
+}
+
+// Split a GFM table row into trimmed cells, tolerating optional leading/trailing pipes.
+function tableCells(row: string): string[] {
+  return row.replace(/^\s*\|/, '').replace(/\|\s*$/, '').split('|').map((c) => c.trim());
+}
+
+/**
+ * Render a GFM-style table block, or null if it isn't one. Shape:
+ *   | Head A | Head B |
+ *   | --- | --- |
+ *   | a1 | b1 |
+ */
+function renderTable(block: string, key: string, basePath?: string): JSX.Element | null {
+  const rows = block.split('\n').map((l) => l.trim()).filter(Boolean);
+  if (rows.length < 2 || !rows[0].includes('|')) return null;
+  // Second line must be the separator: only |, -, :, and spaces, with at least one dash.
+  if (!/^\|?[\s:|-]+\|?$/.test(rows[1]) || !rows[1].includes('-')) return null;
+
+  const headers = tableCells(rows[0]);
+  const bodyRows = rows.slice(2).map(tableCells);
+
+  return (
+    <table key={key}>
+      <thead>
+        <tr>
+          {headers.map((h, i) => (
+            <th key={i}>{parseInline(h, `${key}-h${i}`, basePath)}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {bodyRows.map((cells, r) => (
+          <tr key={r}>
+            {cells.map((c, i) => (
+              <td key={i}>{parseInline(c, `${key}-r${r}-${i}`, basePath)}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+// A heading only ever occupies its own first line — `block.match` here is
+// deliberately anchored to the start of the block (not per-line via `m`), so
+// a block is a heading only when IT, not some later line, opens with 1-3 `#`.
+// Anything after that first line (list, paragraph, even another heading) is
+// real content of its own, not part of the heading text — see renderBlock.
+const HEADING_RE = /^(#{1,3})[ \t]+([^\n]*)(?:\n([\s\S]*))?$/;
+
+/**
+ * Render one blank-line-delimited block into its element(s) — usually one,
+ * but a heading with no blank line before whatever follows it yields two:
+ * the heading (its first line only) plus that remainder re-processed through
+ * this same function. Without the split, "### Heading\n- item\n- item" (no
+ * blank line — the shape a merchant's pasted copy actually produces) read as
+ * ONE heading whose text was the literal list, since `block.startsWith('### ')`
+ * used to consume the whole block, list markers and all.
+ */
+function renderBlock(block: string, key: string, basePath?: string): JSX.Element[] {
+  const headingMatch = block.match(HEADING_RE);
+  if (headingMatch) {
+    const [, hashes, headingText, rest] = headingMatch;
+    const headingKey = `${key}-h`;
+    const inline = parseInline(headingText, headingKey, basePath);
+    const heading =
+      hashes.length === 1 ? <h1 key={headingKey}>{inline}</h1> :
+      hashes.length === 2 ? <h2 key={headingKey}>{inline}</h2> :
+      <h3 key={headingKey}>{inline}</h3>;
+
+    if (!rest || !rest.trim()) return [heading];
+    return [heading, ...renderBlock(rest.trim(), `${key}-r`, basePath)];
+  }
+
+  return [renderNonHeadingBlock(block, key, basePath)];
+}
+
+function renderNonHeadingBlock(block: string, key: string, basePath?: string): JSX.Element {
+  // Horizontal rule — a line of only ---, *** or ___ (3+).
+  if (/^(-{3,}|\*{3,}|_{3,})$/.test(block)) return <hr key={key} />;
+
+  // GFM table — a header row, a |---|---| separator, then body rows. Without
+  // this the pipes render as literal text (the "markdown not rendered" case).
+  const tableEl = renderTable(block, key, basePath);
+  if (tableEl) return tableEl;
+
+  // Unordered list — every non-empty line starts with -, * or +
+  const lines = block.split('\n').map((l) => l.trim()).filter(Boolean);
+  if (lines.length > 0 && lines.every((l) => /^[-*+]\s+/.test(l))) {
+    return (
+      <ul key={key}>
+        {lines.map((line, i) => (
+          <li key={i}>{parseInline(line.replace(/^[-*+]\s+/, ''), `${key}-${i}`, basePath)}</li>
+        ))}
+      </ul>
+    );
+  }
+
+  // Ordered list — every non-empty line starts with "N. "
+  if (lines.length > 0 && lines.every((l) => /^\d+\.\s+/.test(l))) {
+    return (
+      <ol key={key}>
+        {lines.map((line, i) => (
+          <li key={i}>{parseInline(line.replace(/^\d+\.\s+/, ''), `${key}-${i}`, basePath)}</li>
+        ))}
+      </ol>
+    );
+  }
+
+  // Blockquote — every non-empty line starts with ">"
+  if (lines.length > 0 && lines.every((l) => /^>\s?/.test(l))) {
+    const inner = lines.map((l) => l.replace(/^>\s?/, '')).join('\n');
+    return <blockquote key={key}>{renderParagraphLines(inner, key, basePath)}</blockquote>;
+  }
+
+  return <p key={key}>{renderParagraphLines(block, key, basePath)}</p>;
+}
+
+/**
+ * Convert a markdown string to React elements. Supports headings, bold, italic,
+ * inline code, links, ordered/unordered lists, blockquotes, tables, horizontal
+ * rules, and line breaks. Returns block-level elements — render inside a wrapper.
+ *
+ * `basePath` prefixes root-relative links (`/about`) so the same admin-authored
+ * content works both on a real vendor's own domain (basePath '') and inside
+ * `/preview/[theme]/*` (basePath `/preview/<slug>`) — see `withBasePath` above.
+ * Optional and additive; omit it and behavior is unchanged.
+ */
+export function renderMarkdown(markdown: string, basePath?: string): JSX.Element[] {
+  if (!markdown || !markdown.trim()) return [];
+
+  return markdown
+    .replace(/\r\n/g, '\n')
+    .split(/\n{2,}/)
+    .map((block) => block.trim())
+    .filter(Boolean)
+    .flatMap((block, index) => renderBlock(block, String(index), basePath));
+}

package/utils/match-variant.ts

@@ -0,0 +1,31 @@
+import type { Product, ProductVariant } from '../types/product';
+
+/**
+ * Same `selectedOptions -> variant` matching every theme's product page
+ * duplicates inline (see each theme's pages/product.tsx) — centralized here
+ * so it's usable (and testable) outside a themed page, e.g. the quick-add page.
+ */
+export function matchVariant(
+  variants: ProductVariant[],
+  selectedOptions: Record<string, string>,
+): ProductVariant | null {
+  if (variants.length === 0) return null;
+
+  return (
+    variants.find((variant) =>
+      variant.option_values.every((ov) => selectedOptions[ov.option_name] === ov.value),
+    ) ?? null
+  );
+}
+
+/**
+ * True when a product cannot be added to a cart without a chosen variant.
+ *
+ * `variants_count` is checked alongside `variants` on purpose: a product from a
+ * LIST payload carries the count but not the array (the array arrives with the
+ * detail fetch), and a quick-add from a card must still be refused rather than
+ * sending a variant-required line with no variant.
+ */
+export function productRequiresVariant(product: Product): boolean {
+  return (product.variants?.length ?? 0) > 0 || (product.variants_count ?? 0) > 0;
+}

package/utils/menu-link.ts

@@ -0,0 +1,41 @@
+import type { MenuItem } from '../types/menu';
+
+/**
+ * Stable React key for a menu item. `label` alone isn't unique — two
+ * distinct collections (or two anchors on the same page) can share a
+ * display label, which then collides as a React key and can silently
+ * drop/duplicate the rendered item. `index` is the final tiebreaker since
+ * MenuItem carries no id and the list order is stable per render.
+ */
+export function menuItemKey(item: MenuItem, index: number): string {
+  return `${item.type}:${item.ref ?? ''}:${item.meta?.anchor ?? ''}:${index}`;
+}
+
+export function menuItemToHref(item: MenuItem, basePath: string = ''): string {
+  switch (item.type) {
+    case 'page': {
+      const href = `${basePath}/${item.ref}`;
+      const anchor = item.meta?.anchor;
+      // href may already end in "/" (the home page's ref is normalized to
+      // "/" — see MenuResource::normalizeHomeRefs) — never emit a doubled
+      // slash before the fragment.
+      return anchor ? `${href.replace(/\/$/, '')}#${anchor}` : href;
+    }
+    case 'collection':
+      return `${basePath}/collections/${item.ref}`;
+    case 'collections':
+      return `${basePath}/collections`;
+    case 'shop':
+      return `${basePath}/shop`;
+    case 'blog':
+      return `${basePath}/blog`;
+    case 'post':
+      return `${basePath}/blog/${item.ref}`;
+    case 'gallery':
+      return `${basePath}/gallery/${item.ref}`;
+    case 'url':
+      return item.ref ?? '#';
+    default:
+      return '#';
+  }
+}

package/utils/placeholder-resolver.ts

@@ -0,0 +1,184 @@
+/**
+ * Smart placeholder resolver — generates theme-aware SVG data URIs
+ * for empty image slots. Keeps vendor stores looking intentional, never broken.
+ *
+ * Purely visual. Text fallbacks for block content live in the block components.
+ */
+
+export type PlaceholderVariant = 'photo' | 'banner' | 'card' | 'square';
+
+export interface PlaceholderPalette {
+  from: string;
+  to: string;
+  text: string;
+}
+
+export interface PlaceholderContext {
+  width: number;
+  height: number;
+  label?: string;
+  sublabel?: string;
+  palette?: PlaceholderPalette;
+  font?: string;
+  variant?: PlaceholderVariant;
+}
+
+const NEUTRAL_PALETTE: PlaceholderPalette = {
+  from: '#e8e4df',
+  to: '#c9c3ba',
+  text: '#1a1a1a',
+};
+
+const MAX_LABEL_LENGTH = 40;
+const MIN_LABEL_DIMENSION = 200;
+
+/**
+ * Escape a string for safe insertion inside an SVG text node.
+ */
+function escapeSvgText(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Truncate a label if it exceeds the max display length.
+ */
+function truncateLabel(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length <= MAX_LABEL_LENGTH) return trimmed;
+  return `${trimmed.slice(0, MAX_LABEL_LENGTH - 1).trimEnd()}…`;
+}
+
+/**
+ * Compute relative luminance of a hex color (sRGB → linear → relative luminance).
+ * Returns 0..1. Used to decide whether text should be white or black over a gradient.
+ */
+function relativeLuminance(hex: string): number {
+  const cleaned = hex.replace('#', '');
+  if (cleaned.length !== 3 && cleaned.length !== 6) return 0.5;
+  const expanded =
+    cleaned.length === 3
+      ? cleaned
+          .split('')
+          .map((c) => c + c)
+          .join('')
+      : cleaned;
+
+  const r = parseInt(expanded.slice(0, 2), 16) / 255;
+  const g = parseInt(expanded.slice(2, 4), 16) / 255;
+  const b = parseInt(expanded.slice(4, 6), 16) / 255;
+
+  const channel = (c: number): number => (c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+/**
+ * Compute contrast ratio between two colors per WCAG 2.1.
+ * Returns a number >= 1. 4.5 is the AA threshold for normal text.
+ */
+function contrastRatio(fg: string, bg: string): number {
+  const fgLum = relativeLuminance(fg);
+  const bgLum = relativeLuminance(bg);
+  const brighter = Math.max(fgLum, bgLum);
+  const darker = Math.min(fgLum, bgLum);
+  return (brighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Pick a readable text color over a given gradient. Flips to black/white
+ * when contrast is insufficient.
+ */
+function readableText(requestedText: string, gradientFrom: string, gradientTo: string): string {
+  // Average the two gradient stops as the effective background luminance.
+  const effectiveBg = relativeLuminance(gradientFrom) * 0.5 + relativeLuminance(gradientTo) * 0.5;
+
+  // Contrast against the effective background midpoint.
+  const midLum = effectiveBg;
+  const requestedLum = relativeLuminance(requestedText);
+  const ratio = (Math.max(midLum, requestedLum) + 0.05) / (Math.min(midLum, requestedLum) + 0.05);
+
+  if (ratio >= 4.5) return requestedText;
+
+  // Pick the color with the highest contrast against the midpoint.
+  return midLum > 0.5 ? '#0a0a0a' : '#ffffff';
+}
+
+/**
+ * Generate a theme-aware SVG placeholder and return it as a data URI.
+ * Safe to embed inline as an <img src> — no network request, no cache concerns.
+ */
+export function resolvePlaceholder(ctx: PlaceholderContext): string {
+  const width = Math.max(1, Math.round(ctx.width));
+  const height = Math.max(1, Math.round(ctx.height));
+  const palette = ctx.palette ?? NEUTRAL_PALETTE;
+  const font = ctx.font ?? 'system-ui, -apple-system, "Segoe UI", sans-serif';
+  const textColor = readableText(palette.text, palette.from, palette.to);
+
+  const minDim = Math.min(width, height);
+  const showLabel = minDim >= MIN_LABEL_DIMENSION && !!ctx.label;
+  const labelText = ctx.label ? escapeSvgText(truncateLabel(ctx.label)) : '';
+  const sublabelText = ctx.sublabel && showLabel ? escapeSvgText(truncateLabel(ctx.sublabel)) : '';
+
+  // Font size scales with the smaller dimension, capped sensibly.
+  const fontSize = Math.round(Math.max(14, Math.min(minDim / 12, 48)));
+  const sublabelSize = Math.round(fontSize * 0.55);
+
+  // Gradient angle varies by variant for subtle visual difference.
+  const variant = ctx.variant ?? 'photo';
+  const gradientAngle =
+    variant === 'banner' ? '90 0 0' : variant === 'card' ? '135 0 0' : variant === 'square' ? '45 0 0' : '120 0 0';
+
+  // Subtle noise overlay — low opacity, decorative.
+  const noiseId = `n${variant}${width}${height}`.replace(/[^a-z0-9]/gi, '');
+  const gradientId = `g${noiseId}`;
+
+  const parts: string[] = [];
+  parts.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`);
+  parts.push('<defs>');
+  parts.push(
+    `<linearGradient id="${gradientId}" gradientTransform="rotate(${gradientAngle})"><stop offset="0%" stop-color="${palette.from}"/><stop offset="100%" stop-color="${palette.to}"/></linearGradient>`,
+  );
+  parts.push(
+    `<filter id="${noiseId}"><feTurbulence type="fractalNoise" baseFrequency="0.9" numOctaves="2" seed="2"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.08 0"/></filter>`,
+  );
+  parts.push('</defs>');
+  parts.push(`<rect width="${width}" height="${height}" fill="url(#${gradientId})"/>`);
+  parts.push(`<rect width="${width}" height="${height}" filter="url(#${noiseId})"/>`);
+
+  if (showLabel) {
+    const cx = width / 2;
+    const cy = sublabelText ? height / 2 - sublabelSize / 2 : height / 2;
+    parts.push(
+      `<text x="${cx}" y="${cy}" font-family="${escapeSvgText(font)}" font-size="${fontSize}" font-weight="500" fill="${textColor}" text-anchor="middle" dominant-baseline="middle" letter-spacing="0.02em">${labelText}</text>`,
+    );
+    if (sublabelText) {
+      parts.push(
+        `<text x="${cx}" y="${cy + fontSize * 0.9}" font-family="${escapeSvgText(font)}" font-size="${sublabelSize}" font-weight="400" fill="${textColor}" fill-opacity="0.65" text-anchor="middle" dominant-baseline="middle">${sublabelText}</text>`,
+      );
+    }
+  }
+
+  parts.push('</svg>');
+
+  const svg = parts.join('');
+  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
+}
+
+/**
+ * Exposed for tests. Not part of the public API.
+ */
+export const __internal = {
+  escapeSvgText,
+  truncateLabel,
+  relativeLuminance,
+  contrastRatio,
+  readableText,
+  NEUTRAL_PALETTE,
+  MAX_LABEL_LENGTH,
+  MIN_LABEL_DIMENSION,
+};