@gradial/aci 0.1.19 → 0.1.20-preview.2

package/dist/next/page.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentType } from 'react';
+import type { Metadata } from 'next';
+import { type KernelPage, type KernelSiteConfig } from '../content/index.js';
+export interface AciPageProps {
+    page: KernelPage;
+    siteConfig: KernelSiteConfig;
+}
+export interface CreateAciPageOptions {
+    /** The site's CmsPage component that renders chrome + content blocks. */
+    CmsPage: ComponentType<AciPageProps>;
+}
+type NextPageProps = {
+    params: Promise<{
+        slug?: string[];
+    }>;
+};
+/**
+ * Creates the catch-all route handler for a Next.js ACI site.
+ *
+ * Usage in `src/app/[[...slug]]/page.tsx`:
+ *
+ * ```tsx
+ * import { createAciPage } from '@gradial/aci/next/page';
+ * import { CmsPage } from '@/components/CmsPage';
+ *
+ * const page = createAciPage({ CmsPage });
+ * export const dynamic = page.dynamic;
+ * export const generateMetadata = page.generateMetadata;
+ * export default page.default;
+ * ```
+ *
+ * The SDK owns param normalization, content loading, metadata generation,
+ * and notFound handling. The site only provides its CmsPage component.
+ */
+export declare function createAciPage({ CmsPage }: CreateAciPageOptions): {
+    dynamic: "force-dynamic";
+    generateMetadata: ({ params }: NextPageProps) => Promise<Metadata>;
+    default: ({ params }: NextPageProps) => Promise<import("react").JSX.Element>;
+};
+export {};

package/dist/next/page.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { notFound } from 'next/navigation.js';
+import { PageNotFoundError, routeFromNextParams, getRenderInput, } from './server.js';
+import { routeMetadataForContent, } from '../content/index.js';
+/**
+ * Creates the catch-all route handler for a Next.js ACI site.
+ *
+ * Usage in `src/app/[[...slug]]/page.tsx`:
+ *
+ * ```tsx
+ * import { createAciPage } from '@gradial/aci/next/page';
+ * import { CmsPage } from '@/components/CmsPage';
+ *
+ * const page = createAciPage({ CmsPage });
+ * export const dynamic = page.dynamic;
+ * export const generateMetadata = page.generateMetadata;
+ * export default page.default;
+ * ```
+ *
+ * The SDK owns param normalization, content loading, metadata generation,
+ * and notFound handling. The site only provides its CmsPage component.
+ */
+export function createAciPage({ CmsPage }) {
+    const dynamic = 'force-dynamic';
+    async function generateMetadata({ params }) {
+        const route = await routeFromNextParams(params);
+        const input = await getRenderInput(route);
+        const meta = routeMetadataForContent(input.siteConfig, input.page);
+        return {
+            title: meta.title,
+            description: meta.description,
+            alternates: meta.canonical ? { canonical: meta.canonical } : undefined,
+            openGraph: {
+                title: meta.title,
+                description: meta.description,
+                siteName: meta.siteName,
+            },
+        };
+    }
+    async function CatchAllPage({ params }) {
+        const route = await routeFromNextParams(params);
+        try {
+            const input = await getRenderInput(route);
+            if (!input.page || input.page.status !== 'published')
+                notFound();
+            return _jsx(CmsPage, { page: input.page, siteConfig: input.siteConfig });
+        }
+        catch (error) {
+            if (error instanceof PageNotFoundError)
+                notFound();
+            throw error;
+        }
+    }
+    return {
+        dynamic,
+        generateMetadata,
+        default: CatchAllPage,
+    };
+}

package/dist/next/preview-mode.js

@@ -1,13 +1,9 @@
 import { headers } from 'next/headers.js';
-const RELEASE_HEADER = 'x-gradial-release-id';
-const PREVIEW_HEADER = 'x-gradial-preview';
+import { PREVIEW_HEADER, RELEASE_HEADER } from '../preview/core.js';
 export async function isPreviewMode() {
-    try {
-        const current = await headers();
-        if (current.get(PREVIEW_HEADER) === '1') {
-            return current.get(RELEASE_HEADER) || '';
-        }
+    const current = await headers();
+    if (current.get(PREVIEW_HEADER) === '1') {
+        return current.get(RELEASE_HEADER) || '';
     }
-    catch { }
     return '';
 }

package/dist/next/server.js

@@ -37,23 +37,17 @@ export async function getRoutes(config = {}) {
     return routes.map((route) => route.path).sort();
 }
 export async function getRenderInput(route = '/', config = {}) {
-    const startTime = Date.now();
     const runtimeInput = await getPageRuntimeRenderInput();
     if (runtimeInput) {
         return runtimeInput;
     }
-    const providerStart = Date.now();
     const provider = await resolveProviderWithFallback(config);
-    console.log(`[ACI SSR] Provider resolved in ${Date.now() - providerStart}ms`);
     // Cache shared resources (manifest, siteConfig) but not per-page content
     // Page-level caching is handled by CDN
-    const fetchStart = Date.now();
     const [page, siteConfig] = await Promise.all([
         provider.getPage(route),
         getCachedSiteConfig(provider),
     ]);
-    console.log(`[ACI SSR] Content fetched in ${Date.now() - fetchStart}ms`);
-    console.log(`[ACI SSR] Total getRenderInput for ${route}: ${Date.now() - startTime}ms`);
     return {
         route,
         domain: siteConfig.domain || 'www.aci.local',

package/dist/preview/core.d.ts

@@ -0,0 +1,41 @@
+export interface PreviewClaims {
+    scope?: string;
+    releaseId?: string;
+    siteId?: string;
+    expiresAt?: string;
+}
+export interface PreviewTokenSource {
+    query?: URLSearchParams;
+    cookies?: Map<string, string> | Record<string, string>;
+    authorization?: string;
+}
+export interface PreviewResolveOptions {
+    siteId: string;
+    signKey?: string;
+    token?: string;
+}
+export interface PreviewContext {
+    isPreview: boolean;
+    releaseId?: string;
+    token?: string;
+}
+export interface PreviewCookie {
+    name: string;
+    value: string;
+    options: {
+        httpOnly: boolean;
+        sameSite: 'lax' | 'strict' | 'none';
+        maxAge: number;
+        path: string;
+    };
+}
+export declare const PREVIEW_HEADER = "x-gradial-preview";
+export declare const RELEASE_HEADER = "x-gradial-release-id";
+export declare const PREVIEW_TOKEN_COOKIE = "aci_preview";
+export declare const PREVIEW_RELEASE_COOKIE = "aci_preview_release";
+export declare function validatePreviewToken(token: string, signKey: string): Promise<PreviewClaims | null>;
+export declare function extractPreviewToken(source: PreviewTokenSource): string | undefined;
+export declare function previewSignKey(): string | undefined;
+export declare function resolvePreviewContext(options: PreviewResolveOptions): Promise<PreviewContext>;
+export declare function createPreviewCookies(token: string, releaseId: string): PreviewCookie[];
+export declare function createPreviewBannerHTML(releaseId: string): string;

package/dist/preview/core.js

@@ -0,0 +1,116 @@
+export const PREVIEW_HEADER = 'x-gradial-preview';
+export const RELEASE_HEADER = 'x-gradial-release-id';
+export const PREVIEW_TOKEN_COOKIE = 'aci_preview';
+export const PREVIEW_RELEASE_COOKIE = 'aci_preview_release';
+export async function validatePreviewToken(token, signKey) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const signingInput = `${parts[0]}.${parts[1]}`;
+        const signature = base64URLToBytes(parts[2]);
+        const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(signKey), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        const expected = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(signingInput)));
+        if (!constantTimeEqual(signature, expected))
+            return null;
+        const payload = new TextDecoder().decode(base64URLToBytes(parts[1]));
+        return JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+}
+export function extractPreviewToken(source) {
+    const query = source.query?.get('preview_token');
+    if (query)
+        return query;
+    const cookies = source.cookies;
+    if (cookies) {
+        if (cookies instanceof Map) {
+            const cookie = cookies.get(PREVIEW_TOKEN_COOKIE);
+            if (cookie)
+                return cookie;
+        }
+        else {
+            const cookie = cookies[PREVIEW_TOKEN_COOKIE];
+            if (cookie)
+                return cookie;
+        }
+    }
+    const auth = source.authorization || '';
+    if (auth.startsWith('Bearer '))
+        return auth.slice('Bearer '.length);
+    return undefined;
+}
+export function previewSignKey() {
+    return process.env.GRADIAL_PREVIEW_SIGN_KEY || undefined;
+}
+export async function resolvePreviewContext(options) {
+    const token = options.token;
+    if (!token)
+        return { isPreview: false };
+    const signKey = options.signKey || previewSignKey();
+    if (!signKey) {
+        throw new Error('GRADIAL_PREVIEW_SIGN_KEY is not set; preview tokens cannot be validated.');
+    }
+    const claims = await validatePreviewToken(token, signKey);
+    if (!claims || claims.scope !== 'preview' || !claims.releaseId) {
+        return { isPreview: false };
+    }
+    if (claims.siteId && options.siteId && claims.siteId !== options.siteId) {
+        return { isPreview: false };
+    }
+    if (!claims.expiresAt || Date.parse(claims.expiresAt) <= Date.now()) {
+        return { isPreview: false };
+    }
+    return { isPreview: true, releaseId: claims.releaseId, token };
+}
+export function createPreviewCookies(token, releaseId) {
+    const common = {
+        sameSite: 'lax',
+        maxAge: 60 * 60,
+        path: '/',
+    };
+    return [
+        {
+            name: PREVIEW_TOKEN_COOKIE,
+            value: token,
+            options: { ...common, httpOnly: true },
+        },
+        {
+            name: PREVIEW_RELEASE_COOKIE,
+            value: releaseId,
+            options: { ...common, httpOnly: false },
+        },
+    ];
+}
+export function createPreviewBannerHTML(releaseId) {
+    const shortId = releaseId.length > 20
+        ? `${releaseId.slice(0, 8)}\u2026${releaseId.slice(-6)}`
+        : releaseId;
+    return `<div role="alert" style="position:fixed;top:0;left:0;right:0;z-index:9999;display:flex;align-items:center;justify-content:center;gap:12px;padding:8px 16px;background-color:#1a1a2e;color:#fff;font-size:13px;font-family:system-ui,-apple-system,sans-serif;box-shadow:0 2px 8px rgba(0,0,0,0.3);">
+  <span aria-hidden="true" style="display:inline-flex;align-items:center;justify-content:center;width:18px;height:18px;border-radius:50%;background-color:#f59e0b;color:#1a1a2e;font-weight:700;font-size:11px;flex-shrink:0;">P</span>
+  <span style="font-weight:500;">Release Preview</span>
+  <span style="font-family:monospace;opacity:0.7;font-size:12px;" title="${releaseId}">${shortId}</span>
+  <a href="?leave_preview=1" style="margin-left:auto;padding:4px 12px;border-radius:6px;background-color:#dc2626;color:#fff;text-decoration:none;font-size:12px;font-weight:600;white-space:nowrap;">Exit Preview</a>
+</div>`;
+}
+function base64URLToBytes(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function constantTimeEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < left.length; i++) {
+        diff |= left[i] ^ right[i];
+    }
+    return diff === 0;
+}

package/dist/sveltekit/index.d.ts

@@ -19,4 +19,5 @@ export declare function gradialEntries(): Promise<string[]>;
 export declare function getPageRuntimeRenderInput(event: {
     request: Request;
 }): RenderInput | null;
-export declare function gradialSvelteKit(options?: GradialContentWatchOptions): VitePluginLike;
+export { getPreviewMode, createPreviewBannerHTML, createPreviewCookies, type PreviewContext, type PreviewCookie, } from './preview.js';
+export declare function withGradialAci(options?: GradialContentWatchOptions): VitePluginLike;

package/dist/sveltekit/index.js

@@ -32,9 +32,13 @@ export function getPageRuntimeRenderInput(event) {
     return getPendingRenderInputFromHeaders(event.request.headers);
 }
 // ---------------------------------------------------------------------------
+// Preview support
+// ---------------------------------------------------------------------------
+export { getPreviewMode, createPreviewBannerHTML, createPreviewCookies, } from './preview.js';
+// ---------------------------------------------------------------------------
 // SvelteKit Vite plugin
 // ---------------------------------------------------------------------------
-export function gradialSvelteKit(options = {}) {
+export function withGradialAci(options = {}) {
     const watchPlugin = gradialContentWatchPlugin(options);
     const damAssetPlugin = gradialDamAssetPlugin(options);
     return {

package/dist/sveltekit/preview.d.ts

@@ -0,0 +1,5 @@
+import { type PreviewContext, type PreviewCookie } from '../preview/core.js';
+export declare function getPreviewMode(request: Request, siteId: string): Promise<PreviewContext>;
+export declare function createPreviewBannerHTML(releaseId: string): string;
+export declare function createPreviewCookies(token: string, releaseId: string): PreviewCookie[];
+export type { PreviewContext, PreviewCookie };

package/dist/sveltekit/preview.js

@@ -0,0 +1,33 @@
+import { extractPreviewToken, resolvePreviewContext, createPreviewBannerHTML as coreCreatePreviewBannerHTML, createPreviewCookies as coreCreatePreviewCookies, previewSignKey, } from '../preview/core.js';
+export async function getPreviewMode(request, siteId) {
+    const url = new URL(request.url);
+    const token = extractPreviewToken({
+        query: url.searchParams,
+        cookies: parseCookieHeader(request.headers.get('cookie') || ''),
+        authorization: request.headers.get('authorization') || undefined,
+    });
+    if (!token)
+        return { isPreview: false };
+    return resolvePreviewContext({ token, siteId, signKey: previewSignKey() });
+}
+export function createPreviewBannerHTML(releaseId) {
+    return coreCreatePreviewBannerHTML(releaseId);
+}
+export function createPreviewCookies(token, releaseId) {
+    return coreCreatePreviewCookies(token, releaseId);
+}
+function parseCookieHeader(header) {
+    const cookies = new Map();
+    for (const part of header.split(';')) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const idx = trimmed.indexOf('=');
+        if (idx < 0)
+            continue;
+        const name = trimmed.slice(0, idx).trim();
+        const value = trimmed.slice(idx + 1).trim();
+        cookies.set(name, decodeURIComponent(value));
+    }
+    return cookies;
+}

package/dist/types/config.d.ts

@@ -9,6 +9,7 @@ export interface BareMetalConfig {
         publicDir?: string;
     };
     componentRegistry: string;
+    dataRegistry?: string;
     layoutRegistry: string;
     rendererEntry: string;
     capabilities: RenderCapabilities;

package/dist/types/data.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+type InferDataProps<TSchema> = TSchema extends z.ZodType<infer T> ? T : Record<string, unknown>;
+export interface DataModelDefinition<TSchema = unknown, TType extends string = string> {
+    type: TType;
+    schema: TSchema;
+}
+export interface DataModelContract<TSchema = unknown, TType extends string = string> {
+    type: TType;
+    schema: TSchema;
+}
+export interface DataEntry<TProps = Record<string, unknown>, TType extends string = string> {
+    $type: TType;
+    props: TProps;
+}
+export type InferDataModelProps<TContract> = TContract extends DataModelContract<infer TSchema, string> ? InferDataProps<TSchema> : Record<string, unknown>;
+export type InferDataModelType<TContract> = TContract extends DataModelContract<unknown, infer TType> ? TType : string;
+export type DataModelRef<TContract extends DataModelContract> = DataEntry<InferDataModelProps<TContract>, InferDataModelType<TContract>>;
+export declare function dataModelRef<TContract extends DataModelContract<z.ZodTypeAny>>(contract: TContract): z.ZodType<DataModelRef<TContract>>;
+export {};

package/dist/types/data.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+const dataRefPattern = /^\$ref:data\/[A-Za-z0-9][A-Za-z0-9_./-]*$/;
+export function dataModelRef(contract) {
+    return z.union([
+        z.string().regex(dataRefPattern, `expected a $ref:data/... pointer for ${contract.type}`),
+        z.object({
+            $type: z.literal(contract.type),
+            props: contract.schema,
+        }),
+    ]).describe(`data model reference: ${contract.type}`);
+}

package/dist/types/image.d.ts

@@ -17,7 +17,7 @@ export interface GradialImage {
     versionId: string;
     alt: string;
     fallback: ImageSource;
-    sources: PictureSource[];
+    sources: PictureSource[] | null;
 }
 export interface ImageSlotContract {
     outputs: SlotOutput[];

package/dist/types/image.js

@@ -26,7 +26,7 @@ export function renderImageHTML(image, attrs = {}) {
         height: image.fallback.height > 0 ? image.fallback.height : undefined,
     });
     const img = `<img${imgAttrs}>`;
-    if (!image.sources.length) {
+    if (!image.sources?.length) {
         return img;
     }
     const sources = image.sources.map((source) => `<source${renderAttrs({

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from './config.js';
 export * from './component.js';
+export * from './data.js';
 export * from './layout.js';
 export * from './page.js';
 export * from './renderer.js';

package/dist/types/index.js

@@ -1,5 +1,6 @@
 export * from './config.js';
 export * from './component.js';
+export * from './data.js';
 export * from './layout.js';
 export * from './page.js';
 export * from './renderer.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.19",
+  "version": "0.1.20-preview.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,10 +35,18 @@
       "types": "./dist/content/contract.d.ts",
       "import": "./dist/content/contract.js"
     },
+    "./content/cache": {
+      "types": "./dist/content/cache.d.ts",
+      "import": "./dist/content/cache.js"
+    },
     "./content/validation": {
       "types": "./dist/content/validation.d.ts",
       "import": "./dist/content/validation.js"
     },
+    "./content/cache": {
+      "types": "./dist/content/cache.d.ts",
+      "import": "./dist/content/cache.js"
+    },
     "./content/tailwind-validator": {
       "types": "./dist/content/tailwind-validator.d.ts",
       "import": "./dist/content/tailwind-validator.js"
@@ -71,11 +79,21 @@
       "types": "./dist/astro/index.d.ts",
       "import": "./dist/astro/index.js"
     },
+    "./preview": {
+      "types": "./dist/preview/core.d.ts",
+      "import": "./dist/preview/core.js",
+      "default": "./dist/preview/core.js"
+    },
     "./next": {
       "types": "./dist/next/index.d.ts",
       "import": "./dist/next/index.js",
       "default": "./dist/next/index.js"
     },
+    "./next/page": {
+      "types": "./dist/next/page.d.ts",
+      "import": "./dist/next/page.js",
+      "default": "./dist/next/page.js"
+    },
     "./next/server": {
       "types": "./dist/next/server.d.ts",
       "import": "./dist/next/server.js",
@@ -115,6 +133,9 @@
   "overrides": {
     "postcss": "^8.5.10"
   },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
   "peerDependencies": {
     "@vercel/edge-config": "^1.4.3",
     "next": "^15.5.0",
@@ -135,11 +156,13 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@types/react": "^19.0.0",
+    "@types/ws": "^8.18.0",
     "@vercel/edge-config": "^1.4.3",
     "next": "^15.5.6",
     "react": "^19.0.0",
     "tsx": "^4.20.0",
     "typescript": "^5.9.3",
+    "ws": "^8.18.0",
     "zod": "^4.0.0"
   }
 }

package/src/cli/compile-registry.mjs

@@ -5,6 +5,8 @@ import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { GradialImageSchema } from '../types/image.ts';
 
+const DATA_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
 // Shim React global so JSX-containing component files can be loaded.
 // The compile-registry only extracts contract metadata (schemas, imageSlots)
 // and never renders components, but importing .tsx files requires the JSX
@@ -33,6 +35,9 @@ async function compileRegistry(options) {
 
   const components = await loadDefaultArray(options.components, 'component registry');
   const layouts = await loadDefaultArray(options.layouts, 'layout registry');
+  const dataModels = options.data
+    ? await loadDefaultArray(options.data, 'data model registry')
+    : [];
   const outDir = path.resolve(options.output);
   const schemaDir = path.join(outDir, 'schemas');
   await mkdir(schemaDir, { recursive: true });
@@ -72,6 +77,24 @@ async function compileRegistry(options) {
   const seenLayouts = new Set();
   const layoutEntries = layouts.map((layout, index) => validateLayout(layout, index, seenLayouts));
 
+  const seenDataModels = new Set();
+  const dataModelEntries = [];
+  if (dataModels.length > 0) {
+    await mkdir(path.join(schemaDir, 'data'), { recursive: true });
+  }
+  for (const [index, dataModel] of dataModels.entries()) {
+    validateDataModel(dataModel, index, seenDataModels);
+    const schema = compileSchema(dataModel.schema, dataModel.type);
+    const schemaFile = `schemas/data/${dataModel.type}.schema.json`;
+    const schemaPath = path.join(outDir, schemaFile);
+    await writeFile(schemaPath, JSON.stringify(schema, null, 2) + '\n');
+    schemaFiles.push(schemaPath);
+    dataModelEntries.push({
+      type: dataModel.type,
+      schemaFile,
+    });
+  }
+
   // Post-compilation: detect nested block patterns in JSON schemas and
   // validate that referenced component names exist in the registry.
   const knownNames = new Set(componentEntries.map((c) => c.name));
@@ -90,6 +113,7 @@ async function compileRegistry(options) {
     generatedAt: new Date().toISOString(),
     components: componentEntries,
     layouts: layoutEntries,
+    dataModels: dataModelEntries,
   };
   const registryPath = path.join(outDir, 'registry.json');
   await writeFile(registryPath, JSON.stringify(registry, null, 2) + '\n');
@@ -98,11 +122,26 @@ async function compileRegistry(options) {
 
 async function loadDefaultArray(modulePath, label) {
   const mod = await import(pathToFileURL(path.resolve(modulePath)).href);
-  const value = mod.default ?? mod.registry ?? mod.components ?? mod.layouts;
+  const value = mod.default ?? mod.registry ?? mod.components ?? mod.layouts ?? mod.dataModels;
   if (!Array.isArray(value)) throw new Error(`${label} must export an array`);
   return value;
 }
 
+function validateDataModel(dataModel, index, seen) {
+  if (!dataModel || typeof dataModel !== 'object') {
+    throw new Error(`dataModels[${index}] must be an object`);
+  }
+  if (typeof dataModel.type !== 'string' || !DATA_TYPE_PATTERN.test(dataModel.type)) {
+    throw new Error(`dataModels[${index}].type must match ${DATA_TYPE_PATTERN}`);
+  }
+  if (seen.has(dataModel.type)) {
+    throw new Error(`duplicate data model type ${dataModel.type}`);
+  }
+  seen.add(dataModel.type);
+  if (!dataModel.schema) throw new Error(`dataModels[${index}].schema is required`);
+  validateZodSubset(dataModel.schema, `dataModels[${index}].schema`);
+}
+
 function validateComponent(component, index, seen) {
   if (!component || typeof component !== 'object') throw new Error(`components[${index}] must be an object`);
   if (!component.name) throw new Error(`components[${index}].name is required`);

package/src/types/config.ts

@@ -10,6 +10,7 @@ export interface BareMetalConfig {
     publicDir?: string;
   };
   componentRegistry: string;
+  dataRegistry?: string;
   layoutRegistry: string;
   rendererEntry: string;
   capabilities: RenderCapabilities;

package/src/types/data.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+
+type InferDataProps<TSchema> = TSchema extends z.ZodType<infer T>
+  ? T
+  : Record<string, unknown>;
+
+const dataRefPattern = /^\$ref:data\/[A-Za-z0-9][A-Za-z0-9_./-]*$/;
+
+export interface DataModelDefinition<TSchema = unknown, TType extends string = string> {
+  type: TType;
+  schema: TSchema;
+}
+
+export interface DataModelContract<TSchema = unknown, TType extends string = string> {
+  type: TType;
+  schema: TSchema;
+}
+
+export interface DataEntry<TProps = Record<string, unknown>, TType extends string = string> {
+  $type: TType;
+  props: TProps;
+}
+
+export type InferDataModelProps<TContract> = TContract extends DataModelContract<infer TSchema, string>
+  ? InferDataProps<TSchema>
+  : Record<string, unknown>;
+
+export type InferDataModelType<TContract> = TContract extends DataModelContract<unknown, infer TType>
+  ? TType
+  : string;
+
+export type DataModelRef<TContract extends DataModelContract> = DataEntry<
+  InferDataModelProps<TContract>,
+  InferDataModelType<TContract>
+>;
+
+export function dataModelRef<TContract extends DataModelContract<z.ZodTypeAny>>(
+  contract: TContract,
+): z.ZodType<DataModelRef<TContract>> {
+  return z.union([
+    z.string().regex(dataRefPattern, `expected a $ref:data/... pointer for ${contract.type}`),
+    z.object({
+      $type: z.literal(contract.type),
+      props: contract.schema,
+    }),
+  ]).describe(`data model reference: ${contract.type}`) as unknown as z.ZodType<DataModelRef<TContract>>;
+}