@usequeek/theme-kit 0.1.6 → 0.1.7

package/client.ts

@@ -13,6 +13,7 @@ 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

@@ -142,7 +142,14 @@ function renderEntryField(value: MetafieldScalar | MetafieldScalar[], fieldKey:
   return renderScalar(value, fieldKey, humaniseMetafieldKey(fieldKey), '');
 }
 
-function EntryCard({ entry }: { entry: MetaobjectEntry }): JSX.Element {
+/**
+ * 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 (
@@ -160,7 +167,13 @@ function EntryCard({ entry }: { entry: MetaobjectEntry }): JSX.Element {
   );
 }
 
-function renderValue(value: MetafieldValue, fieldKey: string, label: string, type: string): JSX.Element {
+/**
+ * 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} />;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

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/sdk/server-store-client.ts

@@ -110,6 +110,14 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
   // 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;
 }
 

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/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/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/types/block.ts

@@ -1,5 +1,5 @@
 import type { DesignTokens } from './vendor';
-import type { Product } from './product';
+import type { MetaobjectEntry, Product } from './product';
 
 export type BlockType =
   | 'content'
@@ -18,7 +18,8 @@ export type BlockType =
   | 'reviews'
   | 'faq'
   | 'product_qa'
-  | 'blog';
+  | 'blog'
+  | 'metaobjects';
 
 export interface ContentBlockData {
   markdown: string;
@@ -245,6 +246,25 @@ export interface BlogBlockData {
   limit?: number;
 }
 
+export interface MetaobjectsBlockData {
+  title?: string | null;
+  /** Metaobject definition handle (`designer`, `ingredient`, …). */
+  type: string;
+  limit?: number;
+  layout?: 'grid' | 'list';
+}
+
+/**
+ * Server-seeded resolution for a `metaobjects` block — the entries of
+ * `data.type` plus the definition meta needed to decide whether each card
+ * links out (`definition.has_pages`). Mirrors `MetaobjectsResolved` shape
+ * used by `hydrateProductBlocks` in the storefront.
+ */
+export interface MetaobjectsResolved {
+  entries: MetaobjectEntry[];
+  definition: { type: string; name: string; has_pages: boolean };
+}
+
 export type BlockDataMap = {
   content: ContentBlockData;
   image: ImageBlockData;
@@ -263,6 +283,7 @@ export type BlockDataMap = {
   faq: FaqBlockData;
   product_qa: ProductQaBlockData;
   blog: BlogBlockData;
+  metaobjects: MetaobjectsBlockData;
 };
 
 export type Block<T extends BlockType = BlockType> = {
@@ -289,4 +310,12 @@ export type Block<T extends BlockType = BlockType> = {
    * block type and for any route that hasn't been wired to hydrate.
    */
   productsPromise?: Promise<Product[]>;
+  /**
+   * Server-seeded entries + definition meta for `metaobjects` blocks — set
+   * by `hydrateProductBlocks` alongside `productsPromise`. Same contract:
+   * absent for every other block type and for any route that hasn't been
+   * wired to hydrate; the renderer falls back to rendering nothing (themes
+   * never fetch metaobjects client-side).
+   */
+  metaobjectsPromise?: Promise<MetaobjectsResolved>;
 };

package/types/theme.ts

@@ -4,7 +4,7 @@ import type { CartItem as CartLineItem } from './cart';
 import type { ImageVariants } from './media';
 import type { MenuItem } from './menu';
 import type { BlogCategory, Collection, Page, Pagination, Post } from './page';
-import type { Product } from './product';
+import type { MetaobjectEntry, Product } from './product';
 import type { DesignTokenAxisPath, DesignTokens, StorefrontConfig, VendorProfile } from './vendor';
 
 export interface HomePageProps {
@@ -39,6 +39,19 @@ export interface PoliciesPageProps {
   policies: Page[];
 }
 
+/** Field label/type metadata for a metaobject entry page — the same shape
+ *  `GET store/metaobject-definitions` sends, scoped to one definition. */
+export interface MetaobjectPageDefinition {
+  type: string;
+  name: string;
+  fields: Array<{ key: string; name: string; type: string }>;
+}
+
+export interface MetaobjectPageProps {
+  entry: MetaobjectEntry;
+  definition: MetaobjectPageDefinition;
+}
+
 export interface ShopCategory {
   id: string;
   slug: string;
@@ -343,7 +356,7 @@ export interface ThemeManifest {
  * Block types that are framework-owned (React logic ships in core, themes
  * only style via `.core-block-*` CSS). Themes do NOT implement these.
  */
-export type FrameworkBlockType = 'divider' | 'embed' | 'video' | 'table' | 'button' | 'image' | 'reviews' | 'faq' | 'callout' | 'quote' | 'product_qa';
+export type FrameworkBlockType = 'divider' | 'embed' | 'video' | 'table' | 'button' | 'image' | 'reviews' | 'faq' | 'callout' | 'quote' | 'product_qa' | 'metaobjects';
 
 /**
  * Block types the theme is responsible for implementing. Framework-owned
@@ -383,6 +396,11 @@ export interface ThemeModule {
     Collection: FC<CollectionPageProps>;
     Product: FC<ProductPageProps>;
     Gallery: FC<GalleryPageProps>;
+    /** Optional override for a metaobject entry's own page (`/{type}/{handle}`,
+     *  only routed when the definition has `has_pages`). When absent, core
+     *  renders `DefaultMetaobjectPage` (themeable via `.core-metaobject-page-*`
+     *  CSS), same fallback pattern as `Policies`. */
+    Metaobject?: FC<MetaobjectPageProps>;
   };
   shells?: {
     CartShell?: FC<CartShellProps>;