@usequeek/theme-kit 0.1.5 → 0.1.6

package/README.md

@@ -3,7 +3,7 @@
 The framework a Queek storefront theme is built against: hooks, stores, headless
 flows (auth, cart, checkout), types and the block renderer.
 
-**Ships TypeScript source, not a build.** 78 of its 115 modules carry a
+**Ships TypeScript source, not a build.** Most of its modules carry a
 `'use client'` directive, and that directive is the whole contract with the React
 Server Components boundary — bundlers routinely strip or hoist it when a library
 is pre-compiled, which turns a client module into a server one silently. The
@@ -15,8 +15,16 @@ map. One was tried: with source-shipped `.ts`/`.tsx` an extensionless wildcard
 target does not resolve, and spelling out extensions cannot cover both. Legacy
 resolution under `moduleResolution: bundler` handles it. The cost is that the
 package has no subpath encapsulation, so what a theme may import is enforced by
-`tests/core-public-surface.test.ts` in the storefront repo instead — which is
-where the real contract lives anyway. Revisit if this is ever published.
+convention plus tests: `tests/public-surface.test.ts` here (barrels declare
+only modules that exist) and `core-public-surface.test.ts` in the storefront
+repo (barrels cover every module the themes actually import).
+
+Every module that annotates a return as `JSX.Element` does
+`import type { JSX } from 'react'` — React 19 removed the global `JSX`
+namespace, and 0.1.0 shipped broken for every external consumer by relying on
+the storefront app's `next-env.d.ts` to provide it. `scripts/verify-package.ts`
+packs the current source and typechecks a real theme against it from a sandbox,
+so that class of breakage fails here instead of after publishing.
 
 ## Use
 
@@ -30,8 +38,50 @@ to DECLARE the public surface — what a theme is allowed to build against — b
 importing through them pulls every client module into one chunk and was measured
 to break the app's build. Import the module you want.
 
+Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks.css`
+(framework-owned blocks), plus per-component CSS next to its component
+(`components/variant-picker.css`, `apps/apps.css`).
+
+## Consumers
+
+- **The Queek storefront** (`usequeek/queek-storefront`) installs this package
+  from the npm registry (`"@usequeek/theme-kit": "^x.y.z"`) and transpiles it
+  via `transpilePackages`. Its vitest config inlines the package
+  (`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx`
+  source is transformed like first-party code.
+- **External theme developers** start from `packages/theme-starter` in the
+  storefront repo, which builds standalone against a packed tarball of this
+  source. Anyone testing a theme with vitest needs the same `inline` line;
+  anyone compiling one needs `moduleResolution: bundler` + `jsx: react-jsx`.
+
 ## Boundary
 
 The kit must never import the storefront app, its themes, or `lib/storefront`.
-That one-way rule is enforced by `tests/core-storefront-boundary.test.ts` in the
-storefront repo, and it is why this package can be extracted at all.
+That one-way rule is what makes this package extractable at all.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit, standalone — no storefront files
+npm test            # vitest run
+npm run verify-package  # pack current source, typecheck a real theme against it
+```
+
+## Release
+
+The package is public on npm; the repo is private. Publishing runs on tags via
+`.github/workflows/publish.yml` (needs the `NPM_TOKEN` secret):
+
+```bash
+# 1. Bump version in package.json and commit
+# 2. Tag and push the tag — the workflow typechecks, tests, verify-packages,
+#    then `npm publish --access public`:
+git tag v0.1.6
+git push origin main --tags
+```
+
+The storefront then bumps its dependency to match the published version
+(`yarn add @usequeek/theme-kit@^0.1.6` + lockfile) and pushes separately —
+never the other way round: the app must only ever depend on a version that
+actually exists on the registry.

package/client.ts

@@ -12,6 +12,7 @@ export * from './theme-variant-resolver';
 export * from './shared-blocks';
 export * from './components/blog';
 export * from './components/image';
+export * from './components/product-metafields';
 export * from './components/product-media-frame';
 export * from './components/variant-picker';
 export * from './components/auth/auth-flow';

package/components/product-metafields.tsx

@@ -0,0 +1,213 @@
+import type { JSX } from 'react';
+import type {
+  MetafieldScalar,
+  MetafieldValue,
+  MetaobjectEntry,
+  Product,
+} from '../types/product';
+
+export interface ProductMetafieldDefinitionLabels {
+  [key: string]: { name: string; type: string };
+}
+
+export interface ProductMetafieldsProps {
+  product: Product;
+  definitions?: ProductMetafieldDefinitionLabels;
+}
+
+/**
+ * Core-owned product metafields section — the AuthFlow pattern: themes
+ * import-and-place it, never re-implement it.
+ *
+ * Renders the product's presented metafields (all types), with linked
+ * metaobject entries as cards. Renders nothing when there are no visible
+ * values. Markup carries `core-metafields*` classes so each theme styles it
+ * in its own `theme.css` (framework-owned styling contract) — no theme CSS
+ * lives in core.
+ */
+
+function isEntry(value: unknown): value is MetaobjectEntry {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    typeof (value as MetaobjectEntry).display_name === 'string' &&
+    typeof (value as MetaobjectEntry).handle === 'string'
+  );
+}
+
+/** `care_instructions` → `Care instructions`; unknown handles label from the key. */
+export function humaniseMetafieldKey(key: string): string {
+  const words = key.replace(/[_-]+/g, ' ').trim();
+  if (words === '') return key;
+
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+function labelFor(key: string, definitions?: ProductMetafieldDefinitionLabels): string {
+  const name = definitions?.[key]?.name?.trim();
+  return name && name !== '' ? name : humaniseMetafieldKey(key);
+}
+
+function typeFor(key: string, definitions?: ProductMetafieldDefinitionLabels): string {
+  return definitions?.[key]?.type ?? '';
+}
+
+function isVisibleScalar(value: MetafieldScalar): boolean {
+  if (typeof value === 'string') return value.trim() !== '';
+  return true;
+}
+
+function isVisibleValue(value: MetafieldValue): boolean {
+  if (value === null || value === undefined) return false;
+  if (Array.isArray(value)) return value.some((item) => (isEntry(item) ? true : isVisibleScalar(item as MetafieldScalar)));
+  if (isEntry(value)) return true;
+  return isVisibleScalar(value as MetafieldScalar);
+}
+
+function normaliseBoolean(value: MetafieldValue): boolean | null {
+  if (typeof value === 'boolean') return value;
+  if (value === 1 || value === '1' || value === 'true') return true;
+  if (value === 0 || value === '0' || value === 'false') return false;
+  return null;
+}
+
+const IMAGE_URL_PATTERN = /^https?:\/\/\S+\.(jpg|jpeg|png|gif|webp|avif)(\?\S*)?$/i;
+
+function renderScalar(value: MetafieldScalar, key: string, label: string, type: string): JSX.Element {
+  if (typeof value === 'boolean' || (type === 'boolean' && normaliseBoolean(value) !== null)) {
+    const yes = typeof value === 'boolean' ? value : normaliseBoolean(value) === true;
+    return <p className="core-metafields__text">{yes ? 'Yes' : 'No'}</p>;
+  }
+
+  const text = String(value);
+
+  if (type === 'url') {
+    return /^https?:\/\//i.test(text) ? (
+      <a className="core-metafields__link" href={text} target="_blank" rel="noopener noreferrer">
+        {text}
+      </a>
+    ) : (
+      <p className="core-metafields__text">{text}</p>
+    );
+  }
+
+  if (type === 'media_id') {
+    return /^https?:\/\//i.test(text) ? (
+      // Media values arrive as resolved URLs (media contract) — plain <img>:
+      // this is core, not a theme, so the themes' <Image> rule doesn't apply.
+      <img className="core-metafields__image" src={text} alt={label} loading="lazy" />
+    ) : (
+      <p className="core-metafields__text">{text}</p>
+    );
+  }
+
+  if (type === 'date') {
+    const time = new Date(text).getTime();
+    return (
+      <p className="core-metafields__text">
+        {Number.isNaN(time) ? text : new Date(time).toLocaleDateString()}
+      </p>
+    );
+  }
+
+  if (type === 'multi_line_text' || type === 'rich_text') {
+    return <pre className="core-metafields__pre">{text}</pre>;
+  }
+
+  // Entry sub-fields carry no per-field type — an image-looking URL renders
+  // as an image, everything else as text.
+  if (type === '' && IMAGE_URL_PATTERN.test(text)) {
+    return <img className="core-metafields__image" src={text} alt={label} loading="lazy" />;
+  }
+
+  return <p className="core-metafields__text">{text}</p>;
+}
+
+function renderEntryField(value: MetafieldScalar | MetafieldScalar[], fieldKey: string): JSX.Element {
+  if (Array.isArray(value)) {
+    return (
+      <ul className="core-metafields__list">
+        {value.map((item, index) => (
+          // Entry values are flat scalars; the index is stable per render.
+          // eslint-disable-next-line react/no-array-index-key
+          <li key={index} className="core-metafields__list-item">
+            {typeof item === 'boolean' ? (item ? 'Yes' : 'No') : String(item)}
+          </li>
+        ))}
+      </ul>
+    );
+  }
+
+  return renderScalar(value, fieldKey, humaniseMetafieldKey(fieldKey), '');
+}
+
+function EntryCard({ entry }: { entry: MetaobjectEntry }): JSX.Element {
+  const fields = entry.fields && typeof entry.fields === 'object' ? entry.fields : {};
+
+  return (
+    <article className="core-metafields__entry-card">
+      <h4 className="core-metafields__entry-title">{entry.display_name}</h4>
+      {Object.entries(fields).map(([fieldKey, fieldValue]) => (
+        <div className="core-metafields__entry-field" key={fieldKey}>
+          <span className="core-metafields__entry-field-label">{humaniseMetafieldKey(fieldKey)}</span>
+          <div className="core-metafields__entry-field-value">
+            {renderEntryField(fieldValue as MetafieldScalar | MetafieldScalar[], fieldKey)}
+          </div>
+        </div>
+      ))}
+    </article>
+  );
+}
+
+function renderValue(value: MetafieldValue, fieldKey: string, label: string, type: string): JSX.Element {
+  if (isEntry(value)) {
+    return <EntryCard entry={value} />;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length > 0 && value.every((item) => isEntry(item))) {
+      return (
+        <div className="core-metafields__entry-grid">
+          {(value as MetaobjectEntry[]).map((entry) => (
+            <EntryCard key={`${entry.type}:${entry.p_id}`} entry={entry} />
+          ))}
+        </div>
+      );
+    }
+
+    return (
+      <ul className="core-metafields__list">
+        {(value as MetafieldScalar[]).map((item, index) => (
+          // Presented lists are value snapshots; the index is stable per render.
+          // eslint-disable-next-line react/no-array-index-key
+          <li key={index} className="core-metafields__list-item">
+            {typeof item === 'boolean' ? (item ? 'Yes' : 'No') : String(item)}
+          </li>
+        ))}
+      </ul>
+    );
+  }
+
+  return renderScalar(value as MetafieldScalar, fieldKey, label, type);
+}
+
+export function ProductMetafields({ product, definitions }: ProductMetafieldsProps): JSX.Element | null {
+  const metafields = product.metafields && typeof product.metafields === 'object' ? product.metafields : {};
+  const visible = Object.entries(metafields).filter(([, value]) => isVisibleValue(value as MetafieldValue));
+
+  if (visible.length === 0) return null;
+
+  return (
+    <section className="core-metafields" aria-label="Product details">
+      {visible.map(([key, value]) => (
+        <div className="core-metafields__field" key={key}>
+          <h3 className="core-metafields__label">{labelFor(key, definitions)}</h3>
+          <div className="core-metafields__value">
+            {renderValue(value as MetafieldValue, key, labelFor(key, definitions), typeFor(key, definitions))}
+          </div>
+        </div>
+      ))}
+    </section>
+  );
+}

package/next-reference.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pulls in Next.js's own published global types (RequestInit.next, image
+ * types, …) from the `next` PEER dependency — the same
+ * `/// <reference types="next" />` every Next app gets via next-env.d.ts.
+ *
+ * The kit runs inside Next apps, so depending on Next's own type package is
+ * correct. Depending on the storefront's next-env.d.ts (as the kit implicitly
+ * did before extraction — the file the kit free-rode on when 0.1.0 shipped
+ * broken) is what must never happen again. This file is that dependency,
+ * written down.
+ */
+/// <reference types="next" />

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/usequeek/queek-storefront.git",
-    "directory": "packages/theme-kit"
+    "url": "git+https://github.com/usequeek/theme-kit.git"
   },
   "publishConfig": {
     "access": "public"
@@ -38,5 +37,22 @@
     "react-markdown": "^10.0.0",
     "remark-gfm": "^4.0.0",
     "html-to-image": "^1.11.0"
+  },
+  "devDependencies": {
+    "@queekai/client-sdk": "^0.3.0",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "next": "^16.0.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "verify-package": "tsx scripts/verify-package.ts"
   }
 }

package/scripts/verify-package.ts

@@ -0,0 +1,104 @@
+/**
+ * Consumes the kit the way an OUTSIDER does, from a packed tarball.
+ *
+ * WHY THIS EXISTS. @usequeek/theme-kit@0.1.0 was published and was broken for
+ * every external consumer:
+ *
+ *     node_modules/@usequeek/theme-kit/provider.tsx(58,5):
+ *     error TS2503: Cannot find namespace 'JSX'.
+ *
+ * 42 modules annotated returns as `JSX.Element`, relying on a GLOBAL JSX
+ * namespace that came from the storefront app's `next-env.d.ts` — not from
+ * React. Inside the storefront repo the kit free-rode on that file, so tsc,
+ * the tests, the build and the render smoke were ALL green. The workspace
+ * supplies exactly the file whose absence is the bug, which is why no in-repo
+ * check could ever have found it. (Every module now does
+ * `import type { JSX } from 'react'`, and this script proves it.)
+ *
+ * It packs the CURRENT SOURCE rather than installing the published version, so
+ * it fails before a broken version ships instead of after. Installing from the
+ * registry would only ever test the last release.
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// The kit package is `"type": "module"`, so `__dirname` does not exist here.
+// (The storefront copy of this script could use it only because that package
+// is CJS.)
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const KIT = ROOT;
+
+function run(cmd: string, args: string[], cwd: string): string {
+  return execFileSync(cmd, args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function main(): void {
+  const sandbox = mkdtempSync(join(tmpdir(), 'kit-consumer-'));
+  let failed = false;
+
+  try {
+    const kitPkg = JSON.parse(readFileSync(join(KIT, 'package.json'), 'utf-8')) as {
+      name: string; version: string; peerDependencies?: Record<string, string>;
+    };
+
+    console.log(`verify-package: packing ${kitPkg.name}@${kitPkg.version} and consuming it as an outsider`);
+    run('npm', ['pack', '--pack-destination', sandbox], KIT);
+    const tarball = readdirSync(sandbox).find((f) => f.endsWith('.tgz'));
+    if (!tarball) throw new Error('npm pack produced no tarball');
+
+    // Peers are declared by the kit; pin the ones the fixture needs to compile.
+    const peers = kitPkg.peerDependencies ?? {};
+    writeFileSync(join(sandbox, 'package.json'), JSON.stringify({
+      name: 'kit-consumer', private: true, version: '1.0.0',
+      dependencies: {
+        [kitPkg.name]: `file:./${tarball}`,
+        '@queekai/client-sdk': peers['@queekai/client-sdk'] ?? '*',
+        next: '^16.0.0', react: '^19.0.0', 'react-dom': '^19.0.0',
+      },
+      devDependencies: { typescript: '^5', '@types/react': '^19', '@types/react-dom': '^19', '@types/node': '^22' },
+    }, null, 2));
+
+    // `bundler` resolution + no ambient Next types — exactly what a theme
+    // developer's own project looks like. NOT this repo's tsconfig.
+    writeFileSync(join(sandbox, 'tsconfig.json'), JSON.stringify({
+      compilerOptions: {
+        target: 'ES2017', lib: ['dom', 'dom.iterable', 'esnext'], jsx: 'react-jsx',
+        module: 'esnext', moduleResolution: 'bundler', strict: true, noEmit: true,
+        skipLibCheck: true, esModuleInterop: true, isolatedModules: true,
+      },
+      include: ['app/**/*.ts', 'app/**/*.tsx'],
+    }, null, 2));
+
+    mkdirSync(join(sandbox, 'app'), { recursive: true });
+    writeFileSync(join(sandbox, 'app/theme.tsx'), readFileSync(join(ROOT, 'tests/fixtures/external-theme.tsx'), 'utf-8'));
+
+    console.log('verify-package: installing from the tarball…');
+    run('npm', ['install', '--no-audit', '--no-fund'], sandbox);
+
+    console.log('verify-package: typechecking a real theme against it…');
+    try {
+      run(join(sandbox, 'node_modules/.bin/tsc'), ['--noEmit'], sandbox);
+      console.log(`\n✓ ${kitPkg.name} is consumable from outside this repo.`);
+    } catch (error) {
+      const out = (error as { stdout?: string; stderr?: string });
+      console.error('\n✗ the packed kit does NOT work for an external consumer:\n');
+      console.error((out.stdout ?? '') + (out.stderr ?? ''));
+      console.error('Errors inside node_modules/@usequeek/theme-kit are PACKAGE bugs — the kit is');
+      console.error('relying on something only this repo provides. Errors in app/theme.tsx mean the');
+      console.error('fixture drifted from the real API.');
+      failed = true;
+    }
+  } catch (error) {
+    console.error('✗ verify-package failed to run:', (error as Error).message);
+    failed = true;
+  } finally {
+    rmSync(sandbox, { recursive: true, force: true });
+  }
+
+  process.exit(failed ? 1 : 0);
+}
+
+main();

package/sdk/queek-client.ts

@@ -39,11 +39,40 @@ const platformFetch: typeof fetch = (input, init) => {
   if (init?.headers) {
     const headers = new Headers(init.headers);
     headers.set('X-Platform', getActivePlatform());
-    return fetch(input, { ...init, headers });
+    return fetch(input, { ...init, headers }).then(captureRequestId);
   }
-  return fetch(input, init);
+  return fetch(input, init).then(captureRequestId);
 };
 
+/**
+ * Every API response carries a backend request id. The SDK's `request()` returns
+ * only the parsed body, so this wrapper — the one place every SDK call's raw
+ * Response passes through — is where it can be read at all. Kept as the last-seen
+ * value: the storefront has no error-reporting integration (no Sentry), so the
+ * only consumer today is the checkout failure log, which is exactly the report a
+ * customer support ticket needs to be traceable to a backend request.
+ */
+const REQUEST_ID_HEADERS = ['x-request-id', 'x-correlation-id', 'request-id'];
+
+let lastRequestId: string | null = null;
+
+function captureRequestId(response: Response): Response {
+  for (const name of REQUEST_ID_HEADERS) {
+    const value = response.headers.get(name);
+    if (value) {
+      lastRequestId = value;
+      break;
+    }
+  }
+
+  return response;
+}
+
+/** The backend request id of the most recent SDK call, when it sent one. */
+export function getLastRequestId(): string | null {
+  return lastRequestId;
+}
+
 let cachedClient: QueekClientInstance | null = null;
 let cachedSlug: string | null = null;
 

package/sdk/server-store-client.ts

@@ -105,6 +105,11 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
   const product = /^\/products\/([^/]+)(?:\/related)?$/.exec(path);
   if (product) return policy(60, 'products', `product:${product[1]}`);
 
+  // Product metafield definitions (the labels/types the core-owned
+  // <ProductMetafields /> section renders values under). Merchant-edited,
+  // shared across visitors — cached like pages, busted by revalidation.
+  if (path === '/metafield-definitions') return policy(300, 'metafields');
+
   return null;
 }
 

package/tests/fixtures/external-theme.tsx

@@ -0,0 +1,69 @@
+// A real theme, written the way an external developer would, against the
+// PUBLISHED package only — no access to the storefront repo.
+import type { JSX } from 'react';
+import type { ThemeModule, HeaderProps, FooterProps } from '@usequeek/theme-kit/types/theme';
+import type { Product } from '@usequeek/theme-kit/types/product';
+import { useCart } from '@usequeek/theme-kit/hooks/use-cart';
+import { useProducts } from '@usequeek/theme-kit/hooks/use-products';
+import { useStorefront } from '@usequeek/theme-kit/provider';
+import { useHref } from '@usequeek/theme-kit/hooks/use-href';
+import { formatMoney } from '@usequeek/theme-kit/utils/format';
+import { Image } from '@usequeek/theme-kit/components/image';
+import { ThemeMount } from '@usequeek/theme-kit/theme-mount';
+
+export function Header({ menu, showCart }: HeaderProps): JSX.Element {
+  const { vendor } = useStorefront();
+  const { items } = useCart();
+  const href = useHref();
+
+  return (
+    <header>
+      <a href={href('/')}>{vendor?.name}</a>
+      {menu.map((item) => <a key={item.label} href={item.ref ?? '#'}>{item.label}</a>)}
+      {showCart ? <span>{items.length}</span> : null}
+    </header>
+  );
+}
+
+export function Footer({ copyright }: FooterProps): JSX.Element {
+  return <footer>{copyright}</footer>;
+}
+
+export function ProductCard({ product }: { product: Product }): JSX.Element {
+  const { addProduct } = useCart();
+
+  return (
+    <article>
+      <Image src={product.media.thumbnail ?? ''} alt={product.title} />
+      <h3>{product.title}</h3>
+      <span>{formatMoney(product.pricing.sale_amount, product.currency)}</span>
+      <button type="button" onClick={() => addProduct(product, 1)}>Add to cart</button>
+    </article>
+  );
+}
+
+export function Grid(): JSX.Element {
+  const { products, isLoading } = useProducts();
+  if (isLoading) return <p>Loading…</p>;
+
+  return <div>{products.map((p) => <ProductCard key={p.id} product={p} />)}</div>;
+}
+
+export const theme: Pick<ThemeModule, 'Header' | 'Footer'> = { Header, Footer };
+
+/**
+ * Mounting the theme — the thing an external developer could not do before
+ * ThemeMount existed, because the component that does it lived in the
+ * storefront app rather than the package.
+ */
+export function Preview({ theme: mod, children }: { theme: ThemeModule; children: JSX.Element }): JSX.Element {
+  return (
+    <ThemeMount
+      theme={mod}
+      headerProps={{ announcement: null, logo: null, menu: [], showSearch: true, showCart: true, showAccount: true, showOffers: true }}
+      footerProps={{ copyright: '© Demo Store' }}
+    >
+      {children}
+    </ThemeMount>
+  );
+}

package/tests/markdown-render.test.ts

@@ -0,0 +1,47 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { renderMarkdown } from '../utils/markdown';
+
+/**
+ * Backend CT16 (queek_backend/.agent/frontend-chat/sessions/storefront-contact-block/chat.json):
+ * a heading immediately followed by other content, with no blank line between them, gets
+ * swallowed whole into the heading — `utils/markdown.tsx` used to treat an entire
+ * blank-line-delimited block as heading text the moment it matched a heading prefix. Real
+ * merchant copy (Jhema Wears' short_description) writes "### Our Offerings\n- item\n- item"
+ * with no blank line, which is common, valid markdown — the list must not disappear into the h3.
+ */
+
+function html(markdown: string): string {
+  return renderToStaticMarkup(React.createElement(React.Fragment, null, ...renderMarkdown(markdown)));
+}
+
+describe('renderMarkdown heading + trailing-content handling', () => {
+  it('a heading immediately followed by a list (no blank line) renders both, not one heading swallowing the list', () => {
+    const out = html(
+      '### Our Offerings\n- Latest fashion apparel for men, women, and children\n- Accessories to complement every outfit',
+    );
+
+    expect(out).toContain('<h3');
+    expect(out).toContain('Our Offerings');
+    expect(out).toContain('<ul');
+    expect(out).toContain('<li>Latest fashion apparel for men, women, and children</li>');
+    expect(out).toContain('<li>Accessories to complement every outfit</li>');
+    expect(out).not.toMatch(/<h3[^>]*>[^<]*Latest fashion/);
+  });
+
+  it('a heading immediately followed by a paragraph (no blank line) renders both, not one heading swallowing the text', () => {
+    const out = html('## Our Story\nWe hand-pick every piece.');
+
+    expect(out).toBe('<h2>Our Story</h2><p>We hand-pick every piece.</p>');
+  });
+
+  it('a heading with nothing after it still renders alone (regression guard)', () => {
+    expect(html('## Our Story')).toBe('<h2>Our Story</h2>');
+  });
+
+  it('a heading followed by a blank-line-separated paragraph still renders as two blocks (regression guard)', () => {
+    const out = html('## Our Story\n\nWe hand-pick every piece.');
+    expect(out).toBe('<h2>Our Story</h2><p>We hand-pick every piece.</p>');
+  });
+});

package/tests/product-metafields.test.tsx

@@ -0,0 +1,154 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { ProductMetafields } from '../components/product-metafields';
+import type { MetafieldValue, Product } from '../types/product';
+
+function makeProduct(metafields?: Record<string, MetafieldValue>): Product {
+  return {
+    shop_id: 'shop-1',
+    id: 'product-1',
+    p_id: 1,
+    title: 'Test product',
+    slug: 'test-product',
+    excerpt: null,
+    description: null,
+    kind: 'physical',
+    status: 'active',
+    barcode: null,
+    currency: 'NGN',
+    pricing: {
+      base_amount: 1000,
+      sale_amount: 800,
+      compare_at_amount: 1000,
+      discount_amount: 200,
+      discount_percent: 20,
+      is_price_from: false,
+      tax_inclusive: false,
+      price_range: { min_amount: 800, max_amount: 800 },
+    },
+    shop: { id: 'shop-1', name: 'Shop', slug: 'shop', logo: null, rating: 0, rating_count: 0 },
+    media: { thumbnail: null, image: null },
+    inventory: { in_stock: true, tracking: false, quantity: 5 },
+    variants_count: 0,
+    review_summary: { rating: 0, review_count: 0 },
+    flags: { featured: false, is_marketplace: false, is_wholesale: false, is_new: false },
+    categories: [],
+    options: [],
+    variants: [],
+    addons: [],
+    reviews: [],
+    metafields,
+    created_at: null,
+    updated_at: null,
+  };
+}
+
+function render(metafields?: Record<string, MetafieldValue>, definitions?: Record<string, { name: string; type: string }>): string {
+  return renderToStaticMarkup(React.createElement(ProductMetafields, { product: makeProduct(metafields), definitions }));
+}
+
+describe('ProductMetafields', () => {
+  it('renders nothing when the product has no metafields', () => {
+    expect(render(undefined)).toBe('');
+    expect(render({})).toBe('');
+  });
+
+  it('renders nothing when every value is empty', () => {
+    expect(render({ fabric: '', tags: [] })).toBe('');
+  });
+
+  it('renders text with the definition label', () => {
+    const html = render(
+      { fabric: 'Ankara cotton' },
+      { fabric: { name: 'Fabric', type: 'single_line_text' } },
+    );
+
+    expect(html).toContain('core-metafields');
+    expect(html).toContain('Fabric');
+    expect(html).toContain('Ankara cotton');
+    expect(html).toContain('<p');
+  });
+
+  it('falls back to a humanised key label for unknown handles', () => {
+    const html = render({ care_instructions: 'Hand wash only' });
+
+    expect(html).toContain('Care instructions');
+    expect(html).toContain('Hand wash only');
+  });
+
+  it('renders multi_line and rich text preformatted', () => {
+    expect(render({ notes: 'line one\nline two' }, { notes: { name: 'Notes', type: 'multi_line_text' } })).toContain('<pre');
+    expect(render({ story: '<p>rich</p>' }, { story: { name: 'Story', type: 'rich_text' } })).toContain('<pre');
+  });
+
+  it('renders scalar lists as bullets', () => {
+    const html = render({ tags: ['cotton', 'handmade'] }, { tags: { name: 'Tags', type: 'list.single_line_text' } });
+
+    expect(html).toContain('<ul');
+    expect(html).toContain('<li');
+    expect(html).toContain('cotton');
+    expect(html).toContain('handmade');
+  });
+
+  it('renders booleans as Yes/No', () => {
+    expect(render({ gift: true }, { gift: { name: 'Gift wrap', type: 'boolean' } })).toContain('>Yes<');
+    expect(render({ gift: false }, { gift: { name: 'Gift wrap', type: 'boolean' } })).toContain('>No<');
+  });
+
+  it('renders dates localised instead of raw ISO', () => {
+    const html = render({ drop: '2026-09-20' }, { drop: { name: 'Drop date', type: 'date' } });
+
+    expect(html).not.toContain('2026-09-20');
+    expect(html).toContain('2026');
+  });
+
+  it('renders urls as links', () => {
+    const html = render({ lookbook: 'https://example.com/look' }, { lookbook: { name: 'Lookbook', type: 'url' } });
+
+    expect(html).toContain('<a');
+    expect(html).toContain('href="https://example.com/look"');
+  });
+
+  it('renders media_id as an image', () => {
+    const html = render({ swatch: 'https://cdn.example.com/swatch.jpg' }, { swatch: { name: 'Swatch', type: 'media_id' } });
+
+    expect(html).toContain('<img');
+    expect(html).toContain('src="https://cdn.example.com/swatch.jpg"');
+  });
+
+  it('renders a linked entry as a card with its fields', () => {
+    const html = render(
+      {
+        designer: {
+          p_id: 1000,
+          type: 'designer',
+          handle: 'adaeze',
+          display_name: 'Adaeze',
+          fields: { name: 'Adaeze', instagram: '@adaeze' },
+        },
+      },
+      { designer: { name: 'Designer', type: 'metaobject_reference' } },
+    );
+
+    expect(html).toContain('core-metafields__entry-card');
+    expect(html).toContain('Adaeze');
+    expect(html).toContain('@adaeze');
+  });
+
+  it('renders a list of entries as a grid of cards', () => {
+    const html = render(
+      {
+        ingredients: [
+          { p_id: 1, type: 'ingredient', handle: 'shea', display_name: 'Shea', fields: { name: 'Shea' } },
+          { p_id: 2, type: 'ingredient', handle: 'cocoa', display_name: 'Cocoa', fields: { name: 'Cocoa' } },
+        ],
+      },
+      { ingredients: { name: 'Ingredients', type: 'list.metaobject_reference' } },
+    );
+
+    expect(html).toContain('core-metafields__entry-grid');
+    expect(html).toContain('Shea');
+    expect(html).toContain('Cocoa');
+  });
+});

package/tests/public-surface.test.ts

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const ROOT = resolve(__dirname, '..');
+
+/**
+ * The barrels re-export by RELATIVE path — the kit carries no `@/` alias, so it
+ * resolves when imported from outside this repo. `./types/theme` and
+ * `@usequeek/theme-kit/types/theme` name the same module; normalise to the second.
+ */
+function barrelModules(file: string): Set<string> {
+  const source = readFileSync(join(ROOT, file), 'utf8');
+  return new Set(
+    [...source.matchAll(/from '\.\/([^']+)'/g)].map((m) => m[1]),
+  );
+}
+
+/**
+ * `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.)
+ */
+describe('core public surface (kit-internal)', () => {
+  const declared = new Set([...barrelModules('index.ts'), ...barrelModules('client.ts')]);
+
+  it('declares nothing that no longer exists', () => {
+    const missing = [...declared].filter(
+      (mod) => !['.ts', '.tsx', '/index.ts', '/index.tsx'].some((ext) => existsSync(join(ROOT, mod + ext))),
+    );
+
+    expect(missing).toEqual([]);
+  });
+});

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

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+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.
+ *
+ * This guard prevents that whole class of bug from ever returning.
+ */
+describe('storefront API scope guard', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('refuses any backend route outside /v1/client', async () => {
+    for (const badPath of ['/products/abc', '/vendors/foo/products', '/categories', '/vendors/foo/collections/x/products']) {
+      await expect(request('http://api/api/v1', badPath)).rejects.toThrow(/only call \/v1\/client/);
+    }
+  });
+
+  it('allows /client/* routes through', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: true, json: async () => ({ data: [] }) });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(request('http://api/api/v1', '/client/store/products')).resolves.toEqual({ data: [] });
+    expect(fetchMock).toHaveBeenCalledOnce();
+  });
+
+  it('does not reintroduce a raw v1-route client (createServerClient)', () => {
+    const root = process.cwd();
+    const sdk = readFileSync(join(root, 'sdk/client.ts'), 'utf8');
+    expect(sdk).not.toContain('export function createServerClient');
+
+    const apiDir = join(root, 'api');
+    for (const file of readdirSync(apiDir).filter((name) => name.endsWith('.ts'))) {
+      const src = readFileSync(join(apiDir, file), 'utf8');
+      expect(src, `${file} must not use the removed createServerClient (v1 routes)`).not.toContain('createServerClient');
+    }
+  });
+});

package/types/product.ts

@@ -157,6 +157,32 @@ export interface ProductFlags {
   is_new: boolean;
 }
 
+/** A scalar metafield value (single_line_text, boolean, date, url, …). */
+export type MetafieldScalar = string | number | boolean;
+
+/**
+ * One metaobject entry linked through a `metaobject_reference` /
+ * `list.metaobject_reference` metafield. Presented by the backend
+ * (MetafieldPresenter) as the entry resource minus timestamps — a `draft`
+ * entry, or one whose definition is not storefront-visible, is already
+ * omitted on client surfaces, so the storefront renders whatever arrives.
+ */
+export interface MetaobjectEntry {
+  p_id: number;
+  type: string;
+  handle: string;
+  display_name: string;
+  /** Flat entry values (definitions never nest references). */
+  fields: Record<string, MetafieldScalar | MetafieldScalar[]>;
+}
+
+/** A presented product metafield value: scalar, scalar list, or linked entry/entries. */
+export type MetafieldValue =
+  | MetafieldScalar
+  | MetafieldScalar[]
+  | MetaobjectEntry
+  | MetaobjectEntry[];
+
 export interface Product {
   shop_id: string;
   id: string;
@@ -183,6 +209,9 @@ export interface Product {
   variants: ProductVariant[];
   addons: ProductAddon[];
   reviews: ProductReview[];
+  /** Presented product metafields keyed by definition key (incl. linked
+   *  metaobject entries). Absent when the backend sends none. */
+  metafields?: Record<string, MetafieldValue>;
   created_at: string | null;
   updated_at: string | null;
 }
@@ -271,6 +300,8 @@ export interface LegacyProductLike {
   >;
   addons?: ProductAddon[];
   reviews?: ProductReview[];
+  /** Raw presented metafields — passed through verbatim by the normalizer. */
+  metafields?: Record<string, unknown>;
   review_summary?: Partial<ProductReviewSummary>;
   created_at?: string | null;
   updated_at?: string | null;

package/types/theme.ts

@@ -63,6 +63,13 @@ export interface CollectionPageProps {
 
 export interface ProductPageProps {
   product: Product;
+  /**
+   * Product metafield definitions keyed by metafield key — the labels (and
+   * types) the core-owned `<ProductMetafields />` section renders values
+   * under. OPTIONAL so external themes that destructure `{ product }` keep
+   * compiling; unknown keys fall back to a humanised key label.
+   */
+  metafieldDefinitions?: Record<string, { name: string; type: string }>;
 }
 
 export interface GalleryPageProps {

package/utils/product-normalizer.ts

@@ -1,5 +1,6 @@
 import type {
   LegacyProductLike,
+  MetafieldValue,
   Product,
   ProductCategory,
   ProductOption,
@@ -196,6 +197,18 @@ function normalizeCategories(raw: LegacyProductLike): ProductCategory[] {
   }, []);
 }
 
+function normalizeMetafields(raw: LegacyProductLike): Record<string, MetafieldValue> {
+  // Explicit whitelist like every other field above: without this the
+  // presented metafields (incl. linked metaobject entries) are dropped at
+  // runtime and <ProductMetafields /> renders nothing at every call site.
+  const source = raw.metafields;
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    return {};
+  }
+
+  return source as Record<string, MetafieldValue>;
+}
+
 export function normalizeProduct(raw: LegacyProductLike): Product {
   const shopId = String(raw.shop_id ?? raw.vendor_id ?? raw.shop?.id ?? raw.vendor?.id ?? '');
 
@@ -292,6 +305,7 @@ export function normalizeProduct(raw: LegacyProductLike): Product {
       : [],
     addons: raw.addons ?? [],
     reviews: raw.reviews ?? [],
+    metafields: normalizeMetafields(raw),
     created_at: raw.created_at ?? null,
     updated_at: raw.updated_at ?? null,
   };