@usequeek/theme-kit 0.1.5 → 0.1.7

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,8 @@ 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/default-metaobject-page';
 export * from './components/product-media-frame';
 export * from './components/variant-picker';
 export * from './components/auth/auth-flow';

package/components/default-metaobject-page.tsx

@@ -0,0 +1,40 @@
+import type { JSX } from 'react';
+import type { MetaobjectPageProps } from '../types/theme';
+import { humaniseMetafieldKey, renderValue } from './product-metafields';
+
+/**
+ * Core-owned fallback for a metaobject entry's own page — used when the
+ * active theme doesn't provide `theme.pages.Metaobject`. Same field-label
+ * and per-type value rendering as `ProductMetafields`/`CoreMetaobjectsBlock`
+ * (via the shared `renderValue`), so an entry looks the same whether it's
+ * embedded in a product's metafields or viewed on its own page. Markup
+ * carries `core-metaobject-page*` classes for theme.css styling.
+ */
+export function DefaultMetaobjectPage({ entry, definition }: MetaobjectPageProps): JSX.Element {
+  const fields = entry.fields && typeof entry.fields === 'object' ? entry.fields : {};
+  const fieldMeta = new Map(definition.fields.map((field) => [field.key, field]));
+
+  return (
+    <article className="core-metaobject-page">
+      <header className="core-metaobject-page__header">
+        <h1 className="core-metaobject-page__title">{entry.display_name}</h1>
+      </header>
+      <div className="core-metaobject-page__fields">
+        {Object.entries(fields).map(([key, value]) => {
+          const meta = fieldMeta.get(key);
+          const label = meta?.name?.trim() || humaniseMetafieldKey(key);
+          const type = meta?.type ?? '';
+
+          return (
+            <div className="core-metaobject-page__field" key={key}>
+              <h3 className="core-metaobject-page__label">{label}</h3>
+              <div className="core-metaobject-page__value">
+                {renderValue(value, key, label, type)}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </article>
+  );
+}

package/components/product-metafields.tsx

@@ -0,0 +1,226 @@
+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), '');
+}
+
+/**
+ * Renders one linked metaobject entry as a card — shared by
+ * `ProductMetafields` (a product's linked entries), `CoreMetaobjectsBlock`
+ * (a section listing a type's entries) and `DefaultMetaobjectPage` (via
+ * `renderValue` below, for entry detail pages). Exported so those two
+ * consumers never re-implement entry-card markup.
+ */
+export 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>
+  );
+}
+
+/**
+ * Per-type value renderer — scalar, scalar list, linked entry, or list of
+ * entries — shared by `ProductMetafields` and `DefaultMetaobjectPage` (a
+ * metaobject entry's own fields are always flat scalars, never nested
+ * entries, so this same function covers both without a second renderer).
+ */
+export 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.7",
   "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/page-renderer.tsx

@@ -2,7 +2,7 @@
 
 import type { JSX } from 'react';
 import { Component, Suspense, use, useEffect, useMemo, type ComponentType, type ReactNode } from 'react';
-import type { Block, BlockDataMap } from './types/block';
+import type { Block, BlockDataMap, MetaobjectsResolved } from './types/block';
 import type { Product } from './types/product';
 import { useTheme } from './theme-context';
 import { useStorefront } from './provider';
@@ -16,6 +16,7 @@ import {
   CoreQuoteBlock,
   CoreFaqBlock,
   CoreImageBlock,
+  CoreMetaobjectsBlock,
   CoreProductQaBlock,
   CoreReviewsBlock,
   CoreTableBlock,
@@ -323,6 +324,21 @@ export function PageRenderer({ blocks }: { blocks: Block[] }): JSX.Element {
             const data = block.data as BlockDataMap['product_qa'];
             return <CoreProductQaBlock key={key} {...data} />;
           }
+          case 'metaobjects': {
+            // Framework-owned. Themes never fetch metaobjects client-side —
+            // without a server-seeded promise (a route that hasn't called
+            // `hydrateProductBlocks`), the block renders nothing rather than
+            // falling back to a client fetch (mirrors `products`' fallback
+            // being a THEME concern only because that block is theme-owned).
+            const data = block.data as BlockDataMap['metaobjects'];
+            if (!block.metaobjectsPromise) return null;
+
+            return (
+              <Suspense key={key} fallback={<MetaobjectsBlockFallback title={data.title} limit={data.limit} />}>
+                <MetaobjectsBlockResolved data={data} promise={block.metaobjectsPromise} />
+              </Suspense>
+            );
+          }
           default:
             return null;
     }
@@ -364,3 +380,41 @@ function ProductsBlockFallback({ title, limit }: { title?: string | null; limit?
     </section>
   );
 }
+
+/** Unwraps a server-seeded metaobjects promise and hands the resolved entries
+ *  + definition straight to `CoreMetaobjectsBlock`. */
+function MetaobjectsBlockResolved({
+  data,
+  promise,
+}: {
+  data: BlockDataMap['metaobjects'];
+  promise: Promise<MetaobjectsResolved>;
+}): JSX.Element | null {
+  const resolved = use(promise);
+  return (
+    <CoreMetaobjectsBlock
+      title={data.title}
+      layout={data.layout ?? 'grid'}
+      entries={resolved.entries}
+      definition={resolved.definition}
+    />
+  );
+}
+
+/**
+ * Shown only while a `metaobjects` block's server-side fetch is still
+ * pending (cache-cold request). Deliberately theme-neutral, same rationale
+ * as `ProductsBlockFallback`.
+ */
+function MetaobjectsBlockFallback({ title, limit }: { title?: string | null; limit?: number }): JSX.Element {
+  return (
+    <section aria-hidden="true">
+      {title ? <h2>{title}</h2> : null}
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(220px, 1fr))', gap: '1rem' }}>
+        {Array.from({ length: limit ?? 12 }).map((_, i) => (
+          <div key={i} style={{ minHeight: 160, borderRadius: 8, background: 'rgba(127,127,127,0.15)' }} />
+        ))}
+      </div>
+    </section>
+  );
+}

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,19 @@ 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');
+
+  // Metaobject definitions (storefront-visible types + their field labels)
+  // and entry lists/detail reads for the `metaobjects` block and its entry
+  // pages. Merchant-edited, shared across visitors — same tag for both so
+  // a definition edit (e.g. has_pages) and an entry write both bust the
+  // same cache entries.
+  if (path === '/metaobject-definitions') return policy(300, 'metaobjects');
+  if (/^\/metaobjects(\/.+)?$/.test(path)) return policy(300, 'metaobjects');
+
   return null;
 }