@usequeek/theme-kit 0.1.5 → 0.1.7

package/shared-blocks/core-blocks.css

@@ -1790,3 +1790,66 @@
   font-size: 0.85rem;
   color: var(--brand-text-muted, rgba(0, 0, 0, 0.6));
 }
+
+/* ── Metaobjects (content-entries section block) ────────────────── */
+.core-block-metaobjects__title {
+  margin: 0 0 1.5rem;
+  font-size: clamp(1.25rem, 2.5vw, 1.75rem);
+  font-weight: 600;
+  color: var(--brand-text, #1a1a1a);
+}
+
+.core-block-metaobjects__list {
+  display: grid;
+  gap: 1.25rem;
+}
+
+.core-block-metaobjects__list--grid {
+  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+}
+
+.core-block-metaobjects__list--list {
+  grid-template-columns: 1fr;
+}
+
+.core-block-metaobjects__card-link {
+  display: block;
+  color: inherit;
+  text-decoration: none;
+}
+
+.core-block-metaobjects__card-link:hover .core-metafields__entry-card {
+  border-color: var(--brand-accent, rgba(0, 0, 0, 0.2));
+}
+
+/* ── Metaobject entry page (DefaultMetaobjectPage) ───────────────── */
+.core-metaobject-page {
+  margin: 0 auto;
+  padding: clamp(1.5rem, 4vw, 3rem) 1.25rem;
+  max-width: var(--core-block-max-width, 1200px);
+}
+
+.core-metaobject-page__title {
+  margin: 0 0 2rem;
+  font-size: clamp(1.5rem, 3vw, 2.25rem);
+  font-weight: 700;
+  color: var(--brand-text, #1a1a1a);
+}
+
+.core-metaobject-page__fields {
+  display: grid;
+  gap: 1.5rem;
+}
+
+.core-metaobject-page__label {
+  margin: 0 0 0.5rem;
+  font-size: 0.85rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--brand-text-muted, rgba(0, 0, 0, 0.55));
+}
+
+.core-metaobject-page__value {
+  color: var(--brand-text, #1a1a1a);
+}

package/shared-blocks/index.ts

@@ -16,6 +16,7 @@ export { CoreContentDefaultBlock } from './content-default';
 export { CoreReviewsBlock } from './reviews';
 export { CoreFaqBlock } from './faq';
 export { CoreProductQaBlock } from './product-qa';
+export { CoreMetaobjectsBlock } from './metaobjects';
 
 export {
   FRAMEWORK_BLOCK_MANIFEST,

package/shared-blocks/manifest.ts

@@ -46,6 +46,10 @@ export const FRAMEWORK_BLOCK_MANIFEST: Record<string, ThemeManifestVariant[]> =
   product_qa: [
     { id: 'default', label: 'Product Q&A', default: true, purpose: 'Customer questions and vendor answers for this product' },
   ],
+  metaobjects: [
+    { id: 'grid', label: 'Grid', default: true, purpose: 'Entries of a chosen content type (designers, ingredients, …) in a responsive grid' },
+    { id: 'list', label: 'List', purpose: 'Entries of a chosen content type as a vertical list' },
+  ],
 };
 
 /**
@@ -65,6 +69,7 @@ export const FRAMEWORK_OWNED_TYPES = new Set<string>([
   'reviews',
   'faq',
   'product_qa',
+  'metaobjects',
 ]);
 
 /**

package/shared-blocks/metaobjects.tsx

@@ -0,0 +1,50 @@
+'use client';
+
+import type { JSX } from 'react';
+import type { MetaobjectsResolved } from '../types/block';
+import { EntryCard } from '../components/product-metafields';
+
+export interface CoreMetaobjectsBlockProps extends MetaobjectsResolved {
+  title?: string | null;
+  layout?: 'grid' | 'list';
+}
+
+/**
+ * Framework-owned "custom content" section — a merchant-picked metaobject
+ * type rendered as a grid or list of entry cards, reusing the same
+ * `EntryCard` a product's linked-entry metafields render. Renders nothing
+ * when the type is unknown, hidden, or has no active entries (the server
+ * seeds `entries: []` for all three cases — see `hydrateProductBlocks` in
+ * the storefront). Each card links to `/{type}/{handle}` only when the
+ * definition opted into entry pages (`has_pages`); otherwise it's inert.
+ */
+export function CoreMetaobjectsBlock({
+  title,
+  layout = 'grid',
+  entries,
+  definition,
+}: CoreMetaobjectsBlockProps): JSX.Element | null {
+  const safeEntries = Array.isArray(entries) ? entries : [];
+  if (safeEntries.length === 0) return null;
+
+  return (
+    <section className={`core-block core-block-metaobjects core-block-metaobjects--${layout}`}>
+      {title ? <h2 className="core-block-metaobjects__title">{title}</h2> : null}
+      <div className={`core-block-metaobjects__list core-block-metaobjects__list--${layout}`}>
+        {safeEntries.map((entry) =>
+          definition?.has_pages ? (
+            <a
+              key={`${entry.type}:${entry.p_id}`}
+              className="core-block-metaobjects__card-link"
+              href={`/${entry.type}/${entry.handle}`}
+            >
+              <EntryCard entry={entry} />
+            </a>
+          ) : (
+            <EntryCard key={`${entry.type}:${entry.p_id}`} entry={entry} />
+          ),
+        )}
+      </div>
+    </section>
+  );
+}

package/tests/default-metaobject-page.test.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { DefaultMetaobjectPage } from '../components/default-metaobject-page';
+import type { MetaobjectEntry } from '../types/product';
+import type { MetaobjectPageDefinition } from '../types/theme';
+
+function render(fields: MetaobjectEntry['fields'], fieldDefs: MetaobjectPageDefinition['fields']): string {
+  const entry: MetaobjectEntry = {
+    p_id: 1,
+    type: 'designer',
+    handle: 'adaeze',
+    display_name: 'Adaeze',
+    fields,
+  };
+  const definition: MetaobjectPageDefinition = { type: 'designer', name: 'Designer', fields: fieldDefs };
+
+  return renderToStaticMarkup(React.createElement(DefaultMetaobjectPage, { entry, definition }));
+}
+
+describe('DefaultMetaobjectPage', () => {
+  it('renders the entry display name as the title', () => {
+    const html = render({}, []);
+    expect(html).toContain('core-metaobject-page__title');
+    expect(html).toContain('Adaeze');
+  });
+
+  it('renders a text field with its definition label', () => {
+    const html = render({ bio: 'Lagos-based designer' }, [{ key: 'bio', name: 'Biography', type: 'single_line_text' }]);
+    expect(html).toContain('Biography');
+    expect(html).toContain('Lagos-based designer');
+  });
+
+  it('falls back to a humanised key label when no definition field matches', () => {
+    const html = render({ years_active: '10' }, []);
+    expect(html).toContain('Years active');
+  });
+
+  it('renders a boolean field as Yes/No', () => {
+    const html = render({ verified: true }, [{ key: 'verified', name: 'Verified', type: 'boolean' }]);
+    expect(html).toContain('>Yes<');
+  });
+
+  it('renders a url field as a link', () => {
+    const html = render({ portfolio: 'https://example.com/adaeze' }, [{ key: 'portfolio', name: 'Portfolio', type: 'url' }]);
+    expect(html).toContain('<a');
+    expect(html).toContain('href="https://example.com/adaeze"');
+  });
+
+  it('renders a list field as bullets', () => {
+    const html = render({ tags: ['couture', 'bridal'] }, [{ key: 'tags', name: 'Tags', type: 'list.single_line_text' }]);
+    expect(html).toContain('<ul');
+    expect(html).toContain('couture');
+    expect(html).toContain('bridal');
+  });
+});

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/manifest-parity.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { FRAMEWORK_BLOCK_MANIFEST, FRAMEWORK_OWNED_TYPES } from '../shared-blocks/manifest';
+import type { BlockType } from '../types/block';
+import type { FrameworkBlockType } from '../types/theme';
+
+/**
+ * Three places declare "this block type is framework-owned" and must never
+ * drift: `types/theme.ts` `FrameworkBlockType`, `shared-blocks/manifest.ts`
+ * `FRAMEWORK_OWNED_TYPES`, and `page-renderer.tsx`'s switch (checked here by
+ * proxy — every framework-owned type must at least have a manifest entry, or
+ * a theme's Section Library drawer would offer a block the renderer has no
+ * variant list for).
+ */
+describe('framework-owned block manifest parity', () => {
+  // Mirrors `FrameworkBlockType` in types/theme.ts — TypeScript enforces the
+  // literal union is exhaustive against `BlockType` here (compile error if
+  // one is added without the other), so this list doubles as the type check.
+  const frameworkBlockTypes: FrameworkBlockType[] = [
+    'divider',
+    'embed',
+    'video',
+    'table',
+    'button',
+    'image',
+    'reviews',
+    'faq',
+    'callout',
+    'quote',
+    'product_qa',
+    'metaobjects',
+  ];
+
+  it('FrameworkBlockType and FRAMEWORK_OWNED_TYPES name the same set', () => {
+    expect(new Set(frameworkBlockTypes)).toEqual(FRAMEWORK_OWNED_TYPES);
+  });
+
+  it('every framework-owned type (except content, handled specially) has a manifest entry', () => {
+    for (const type of FRAMEWORK_OWNED_TYPES) {
+      expect(FRAMEWORK_BLOCK_MANIFEST[type], `${type} missing from FRAMEWORK_BLOCK_MANIFEST`).toBeDefined();
+      expect(FRAMEWORK_BLOCK_MANIFEST[type].length).toBeGreaterThan(0);
+    }
+  });
+
+  it('metaobjects is a real BlockType', () => {
+    const type: BlockType = 'metaobjects';
+    expect(FRAMEWORK_OWNED_TYPES.has(type)).toBe(true);
+  });
+
+  it('metaobjects manifest declares grid (default) and list variants', () => {
+    const variants = FRAMEWORK_BLOCK_MANIFEST.metaobjects;
+    expect(variants.map((v) => v.id)).toEqual(expect.arrayContaining(['grid', 'list']));
+    expect(variants.find((v) => v.default)?.id).toBe('grid');
+  });
+});

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/metaobjects-block.test.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { CoreMetaobjectsBlock } from '../shared-blocks/metaobjects';
+import type { CoreMetaobjectsBlockProps } from '../shared-blocks/metaobjects';
+import type { MetaobjectEntry } from '../types/product';
+
+function makeEntry(overrides: Partial<MetaobjectEntry> = {}): MetaobjectEntry {
+  return {
+    p_id: 1,
+    type: 'designer',
+    handle: 'adaeze',
+    display_name: 'Adaeze',
+    fields: { bio: 'Lagos-based designer' },
+    ...overrides,
+  };
+}
+
+function render(props: Partial<CoreMetaobjectsBlockProps> = {}): string {
+  return renderToStaticMarkup(
+    React.createElement(CoreMetaobjectsBlock, {
+      entries: [makeEntry()],
+      definition: { type: 'designer', name: 'Designer', has_pages: false },
+      ...props,
+    }),
+  );
+}
+
+describe('CoreMetaobjectsBlock', () => {
+  it('renders nothing when there are no entries', () => {
+    expect(render({ entries: [] })).toBe('');
+  });
+
+  it('renders a grid by default with entry cards', () => {
+    const html = render();
+    expect(html).toContain('core-block-metaobjects--grid');
+    expect(html).toContain('core-block-metaobjects__list--grid');
+    expect(html).toContain('core-metafields__entry-card');
+    expect(html).toContain('Adaeze');
+  });
+
+  it('renders a list layout when requested', () => {
+    const html = render({ layout: 'list' });
+    expect(html).toContain('core-block-metaobjects--list');
+    expect(html).toContain('core-block-metaobjects__list--list');
+  });
+
+  it('renders the title when provided', () => {
+    expect(render({ title: 'Our designers' })).toContain('Our designers');
+  });
+
+  it('does not link entries when the definition has no pages', () => {
+    const html = render({ definition: { type: 'designer', name: 'Designer', has_pages: false } });
+    expect(html).not.toContain('<a ');
+  });
+
+  it('links each entry to /{type}/{handle} when the definition has pages', () => {
+    const html = render({ definition: { type: 'designer', name: 'Designer', has_pages: true } });
+    expect(html).toContain('<a ');
+    expect(html).toContain('href="/designer/adaeze"');
+  });
+
+  it('renders multiple entries', () => {
+    const html = render({
+      entries: [makeEntry(), makeEntry({ p_id: 2, handle: 'chidi', display_name: 'Chidi' })],
+    });
+    expect(html).toContain('Adaeze');
+    expect(html).toContain('Chidi');
+  });
+});

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([]);
+  });
+});