@gradial/aci 0.1.41 → 0.1.43

package/dist/providers/s3.js

@@ -1,4 +1,6 @@
 import crypto from 'node:crypto';
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { awsCredentialsProvider } from '@vercel/oidc-aws-credentials-provider';
 import { FragmentNotFoundError, LayoutNotFoundError, PageNotFoundError } from '../content/provider.js';
 import { normalizeRoute } from '../content/routes.js';
 // ---------------------------------------------------------------------------
@@ -7,8 +9,10 @@ import { normalizeRoute } from '../content/routes.js';
 export class S3ContentProvider {
     config;
     #manifest;
-    constructor(config = {}) {
+    #client;
+    constructor(config = {}, client) {
         this.config = resolveS3Config(config);
+        this.#client = client || oidcS3Client(this.config);
     }
     async listRoutes() {
         const manifest = await this.manifest();
@@ -34,7 +38,7 @@ export class S3ContentProvider {
     }
     /**
      * getPageByRef serves the exact payload the edge selected (the
-     * X-Baremetal-Function-Ref contract): base page or variant. Only refs the
+     * X-Aci-Content-Ref contract): base page or variant. Only refs the
      * release manifest declares are served — the header names published
      * content, it cannot address arbitrary keys.
      */
@@ -83,24 +87,18 @@ export class S3ContentProvider {
         return await this.#manifest;
     }
     async fetchRaw(key) {
-        return await getS3Raw(key, this.config);
+        return await getS3Raw(key, this.config, this.#client);
     }
     async getJSON(key) {
-        return await getS3JSON(joinKey(this.config.keyPrefix, key), this.config);
+        return await getS3JSON(joinKey(this.config.keyPrefix, key), this.config, this.#client);
     }
 }
 // ---------------------------------------------------------------------------
 // S3 fetch with AWS SigV4 signing
 // ---------------------------------------------------------------------------
-export async function getS3JSON(key, config) {
+export async function getS3JSON(key, config, client) {
     const startTime = Date.now();
-    const url = s3ObjectURL(config, key);
-    const signedHeaders = signedS3Headers('GET', url, config);
-    const res = await fetch(url, {
-        method: 'GET',
-        headers: signedHeaders,
-        cache: 'no-store'
-    });
+    const res = await getS3Raw(key, config, client);
     const duration = Date.now() - startTime;
     console.log(`[ACI S3] GET ${key} - ${res.status} in ${duration}ms`);
     if (!res.ok) {
@@ -108,7 +106,9 @@ export async function getS3JSON(key, config) {
     }
     return (await res.json());
 }
-export async function getS3Raw(key, config) {
+export async function getS3Raw(key, config, client) {
+    if (client)
+        return await getS3RawWithClient(key, config, client);
     const url = s3ObjectURL(config, key);
     const signedHeaders = signedS3Headers('GET', url, config);
     return await fetch(url, {
@@ -122,20 +122,90 @@ export async function getS3Raw(key, config) {
 // ---------------------------------------------------------------------------
 function resolveS3Config(config) {
     const resolved = {
-        bucket: config.bucket || process.env.ACI_S3_BUCKET || '',
-        keyPrefix: config.keyPrefix || process.env.ACI_S3_KEY_PREFIX || '',
-        region: config.region || process.env.AWS_REGION || 'us-east-1',
-        accessKeyId: config.accessKeyId || process.env.AWS_ACCESS_KEY_ID || '',
-        secretAccessKey: config.secretAccessKey || process.env.AWS_SECRET_ACCESS_KEY || '',
-        sessionToken: config.sessionToken || process.env.AWS_SESSION_TOKEN || '',
-        endpoint: trimSlash(config.endpoint || process.env.ACI_S3_ENDPOINT || '')
+        bucket: configuredValue(config.bucket, process.env.ACI_S3_BUCKET),
+        keyPrefix: configuredValue(config.keyPrefix, process.env.ACI_S3_KEY_PREFIX),
+        region: configuredValue(config.region, process.env.AWS_REGION) || 'us-east-1',
+        accessKeyId: configuredValue(config.accessKeyId, process.env.AWS_ACCESS_KEY_ID),
+        secretAccessKey: configuredValue(config.secretAccessKey, process.env.AWS_SECRET_ACCESS_KEY),
+        sessionToken: configuredValue(config.sessionToken, process.env.AWS_SESSION_TOKEN),
+        roleArn: configuredValue(config.roleArn, process.env.AWS_ROLE_ARN),
+        endpoint: trimSlash(configuredValue(config.endpoint, process.env.ACI_S3_ENDPOINT))
     };
-    for (const key of ['bucket', 'accessKeyId', 'secretAccessKey']) {
-        if (!resolved[key])
-            throw new Error(`S3 config missing ${key}`);
+    if (!resolved.bucket)
+        throw new Error('S3 config missing bucket');
+    if (!resolved.roleArn) {
+        if (resolved.accessKeyId && !resolved.secretAccessKey) {
+            throw new Error('S3 config missing secretAccessKey');
+        }
+        if (!resolved.accessKeyId && resolved.secretAccessKey) {
+            throw new Error('S3 config missing accessKeyId');
+        }
+        if (!resolved.accessKeyId) {
+            throw new Error('S3 config missing credential mode: set AWS_ROLE_ARN or both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY');
+        }
     }
     return resolved;
 }
+function oidcS3Client(config) {
+    if (!config.roleArn)
+        return undefined;
+    return new S3Client({
+        region: config.region,
+        ...(config.endpoint ? {
+            endpoint: config.endpoint,
+            forcePathStyle: true,
+        } : {}),
+        credentials: awsCredentialsProvider({
+            roleArn: config.roleArn,
+            clientConfig: { region: config.region },
+        }),
+    });
+}
+async function getS3RawWithClient(key, config, client) {
+    try {
+        const output = await client.send(new GetObjectCommand({
+            Bucket: config.bucket,
+            Key: key,
+        }));
+        if (!output.Body?.transformToWebStream) {
+            throw new Error(`S3 GET ${key} returned an unsupported object body`);
+        }
+        const headers = new Headers();
+        if (output.ContentType)
+            headers.set('content-type', output.ContentType);
+        if (output.ContentLength !== undefined) {
+            headers.set('content-length', String(output.ContentLength));
+        }
+        if (output.ETag)
+            headers.set('etag', output.ETag);
+        if (output.LastModified) {
+            headers.set('last-modified', output.LastModified.toUTCString());
+        }
+        return new Response(output.Body.transformToWebStream(), {
+            status: 200,
+            headers,
+        });
+    }
+    catch (error) {
+        const status = s3ErrorStatus(error);
+        if (status) {
+            return new Response(error instanceof Error ? error.message : String(error), { status });
+        }
+        throw new Error(`S3 GET ${key} failed`, { cause: error });
+    }
+}
+function s3ErrorStatus(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const status = error
+        .$metadata?.httpStatusCode;
+    return typeof status === 'number' && status >= 400 && status <= 599
+        ? status
+        : undefined;
+}
+function configuredValue(configured, environment) {
+    return (configured === undefined ? environment : configured)?.trim() || '';
+}
 function s3ObjectURL(config, key) {
     const encodedKey = encodeKey(key);
     if (config.endpoint) {

package/dist/react/VideoPlayer.d.ts

@@ -16,12 +16,16 @@ export declare function VideoPlayer({ video, ...attrs }: VideoPlayerProps): impo
     title: string;
     rel?: string | undefined | undefined;
     content?: string | undefined | undefined;
-    dir?: string | undefined | undefined;
-    hidden?: boolean | undefined | undefined;
     slot?: string | undefined | undefined;
     style?: import("react").CSSProperties | undefined;
+    dir?: string | undefined | undefined;
+    hidden?: boolean | undefined | undefined;
+    dangerouslySetInnerHTML?: {
+        __html: string | TrustedHTML;
+    } | undefined | undefined;
     children?: import("react").ReactNode;
     className?: string | undefined | undefined;
+    lang?: string | undefined | undefined;
     crossOrigin?: "" | "anonymous" | "use-credentials" | undefined;
     defaultChecked?: boolean | undefined | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
@@ -34,7 +38,6 @@ export declare function VideoPlayer({ video, ...attrs }: VideoPlayerProps): impo
     contextMenu?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
-    lang?: string | undefined | undefined;
     nonce?: string | undefined | undefined;
     spellCheck?: (boolean | "true" | "false") | undefined;
     tabIndex?: number | undefined | undefined;
@@ -121,9 +124,6 @@ export declare function VideoPlayer({ video, ...attrs }: VideoPlayerProps): impo
     "aria-valuemin"?: number | undefined | undefined;
     "aria-valuenow"?: number | undefined | undefined;
     "aria-valuetext"?: string | undefined | undefined;
-    dangerouslySetInnerHTML?: {
-        __html: string | TrustedHTML;
-    } | undefined | undefined;
     onCopy?: import("react").ClipboardEventHandler<HTMLVideoElement> | undefined;
     onCopyCapture?: import("react").ClipboardEventHandler<HTMLVideoElement> | undefined;
     onCut?: import("react").ClipboardEventHandler<HTMLVideoElement> | undefined;

package/dist/react/index.d.ts

@@ -25,12 +25,16 @@ export declare function Image({ image, value, ...attrs }: ImageProps): import("r
     rel?: string | undefined | undefined;
     content?: string | undefined | undefined;
     referrerPolicy?: import("react").HTMLAttributeReferrerPolicy | undefined;
-    dir?: string | undefined | undefined;
-    hidden?: boolean | undefined | undefined;
     slot?: string | undefined | undefined;
     style?: import("react").CSSProperties | undefined;
+    dir?: string | undefined | undefined;
+    hidden?: boolean | undefined | undefined;
+    dangerouslySetInnerHTML?: {
+        __html: string | TrustedHTML;
+    } | undefined | undefined;
     children?: ReactNode;
     className?: string | undefined | undefined;
+    lang?: string | undefined | undefined;
     crossOrigin?: "" | "anonymous" | "use-credentials" | undefined;
     fetchPriority?: "high" | "low" | "auto" | undefined | undefined;
     useMap?: string | undefined | undefined;
@@ -45,7 +49,6 @@ export declare function Image({ image, value, ...attrs }: ImageProps): import("r
     contextMenu?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
-    lang?: string | undefined | undefined;
     nonce?: string | undefined | undefined;
     spellCheck?: (boolean | "true" | "false") | undefined;
     tabIndex?: number | undefined | undefined;
@@ -132,9 +135,6 @@ export declare function Image({ image, value, ...attrs }: ImageProps): import("r
     "aria-valuemin"?: number | undefined | undefined;
     "aria-valuenow"?: number | undefined | undefined;
     "aria-valuetext"?: string | undefined | undefined;
-    dangerouslySetInnerHTML?: {
-        __html: string | TrustedHTML;
-    } | undefined | undefined;
     onCopy?: import("react").ClipboardEventHandler<HTMLImageElement> | undefined;
     onCopyCapture?: import("react").ClipboardEventHandler<HTMLImageElement> | undefined;
     onCut?: import("react").ClipboardEventHandler<HTMLImageElement> | undefined;

package/dist/testing/conformance/checks.js

@@ -278,7 +278,37 @@ export function checkMiddleware(ctx) {
     // the SDK's canonical value. Next.js requires config.matcher to be
     // statically analyzable, so importing the matcher from the SDK breaks the
     // build. Instead the template inlines the value and this check detects drift.
-    const canonicalMatcher = "['/((?!_next(?:/|$)|api(?:/|$)|favicon\\\\.ico$|\\\\.gradial-dam(?:/|$)).*)']";
+    const canonicalMatcher = String.raw `[
+    '/((?!_next(?:/|$)|api(?:/|$)|collect(?:/|$)|gradial/assets(?:/|$)|favicon\\.ico$).*)',
+    {
+      source: '/:path*',
+      has: [{ type: 'header', key: 'x-gradial-framework-origin-auth' }],
+    },
+    {
+      source: '/:path*',
+      has: [{ type: 'header', key: 'x-baremetal-site-id' }],
+    },
+    {
+      source: '/:path*',
+      has: [{ type: 'header', key: 'x-baremetal-release-id' }],
+    },
+    {
+      source: '/:path*',
+      has: [{ type: 'header', key: 'x-aci-content-ref' }],
+    },
+    {
+      source: '/:path*',
+      has: [{ type: 'header', key: 'x-baremetal-content-base-url' }],
+    },
+    {
+      source: '/:path*',
+      has: [{ type: 'header', key: 'x-aci-content-path' }],
+    },
+    {
+      source: '/:path*',
+      has: [{ type: 'query', key: '__aci_content_path' }],
+    },
+  ]`;
     // Check for actual import/usage of aciMiddlewareMatcher (not just a mention
     // in a comment). Look for `matcher: aciMiddlewareMatcher` or
     // `import { ... aciMiddlewareMatcher ... }`.
@@ -289,9 +319,9 @@ export function checkMiddleware(ctx) {
     }
     else {
         // Verify the inlined value matches the SDK canonical
-        const matcherMatch = middlewareFile.content.match(/matcher\s*:\s*(\[.*?\])/s);
-        if (matcherMatch) {
-            const normalizedInlined = matcherMatch[1].replace(/\s+/g, '');
+        const matcherLiteral = extractArrayPropertyLiteral(middlewareFile.content, 'matcher');
+        if (matcherLiteral) {
+            const normalizedInlined = matcherLiteral.replace(/\s+/g, '');
             const normalizedCanonical = canonicalMatcher.replace(/\s+/g, '');
             results.push(normalizedInlined === normalizedCanonical
                 ? ok('middleware', 'middleware matcher matches SDK canonical', rel)
@@ -303,6 +333,47 @@ export function checkMiddleware(ctx) {
     }
     return results;
 }
+function extractArrayPropertyLiteral(content, propertyName) {
+    const property = new RegExp(`\\b${propertyName}\\s*:`).exec(content);
+    if (!property)
+        return null;
+    const start = content.indexOf('[', property.index + property[0].length);
+    if (start < 0)
+        return null;
+    let depth = 0;
+    let quote = '';
+    let escaped = false;
+    for (let index = start; index < content.length; index += 1) {
+        const character = content[index];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (character === '\\') {
+                escaped = true;
+            }
+            else if (character === quote) {
+                quote = '';
+            }
+            continue;
+        }
+        if (character === "'" || character === '"' || character === '`') {
+            quote = character;
+            continue;
+        }
+        if (character === '[') {
+            depth += 1;
+            continue;
+        }
+        if (character === ']') {
+            depth -= 1;
+            if (depth === 0) {
+                return content.slice(start, index + 1);
+            }
+        }
+    }
+    return null;
+}
 // ---------------------------------------------------------------------------
 // Check: noFileContentProvider — no direct FileContentProvider imports in app code
 // ---------------------------------------------------------------------------

package/dist/types/block-ref.d.ts

@@ -5,6 +5,7 @@ export interface BlockRefMeta {
     multiple: boolean;
 }
 declare const blockRefBase: z.ZodObject<{
+    $type: z.ZodLiteral<"component">;
     id: z.ZodString;
     component: z.ZodString;
     props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -12,6 +13,7 @@ declare const blockRefBase: z.ZodObject<{
 type InferContractProps<T> = T extends ComponentContract<string, infer Schema> ? Schema extends z.ZodType<infer P> ? P : Record<string, unknown> : Record<string, unknown>;
 type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
 export type BlockRefEntry<T extends ComponentContract> = {
+    $type: 'component';
     id: string;
     component: InferContractId<T>;
     props: InferContractProps<T>;

package/dist/types/block-ref.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 const BLOCK_REF_KEY = '_gradialBlockRef';
 const blockRefBase = z.object({
+    $type: z.literal('component'),
     id: z.string().min(1),
     component: z.string().min(1),
     props: z.record(z.string(), z.unknown()),

package/dist/types/page.d.ts

@@ -30,7 +30,7 @@ export interface BlockNode {
     component: string;
     props: Record<string, unknown>;
     renderHints: BlockRenderHints;
-    contentRef?: string;
+    contentPath?: string;
 }
 export interface BlockRenderHints {
     canStatic: boolean;

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.41",
+  "version": "0.1.43",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gradial/bare-metal-go.git",
+    "directory": "packages/sdk"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -9,6 +14,8 @@
     "bin/aci.js",
     "src/cli/*.mjs",
     "src/types/*.ts",
+    "src/astro/*.astro",
+    "src/consent-banner/*.css",
     "templates/common",
     "templates/nextjs",
     "templates/astro",
@@ -65,6 +72,16 @@
       "import": "./dist/next/middleware.js",
       "default": "./dist/next/middleware.js"
     },
+    "./next/vercel-personalization": {
+      "types": "./dist/next/vercel-personalization.d.ts",
+      "import": "./dist/next/vercel-personalization.js",
+      "default": "./dist/next/vercel-personalization.js"
+    },
+    "./next/vercel-collect-sdk-route": {
+      "types": "./dist/next/vercel-collect-sdk-route.d.ts",
+      "import": "./dist/next/vercel-collect-sdk-route.js",
+      "default": "./dist/next/vercel-collect-sdk-route.js"
+    },
     "./next/asset-route": {
       "types": "./dist/next/asset-route.d.ts",
       "import": "./dist/next/asset-route.js",
@@ -84,12 +101,30 @@
       "import": "./dist/astro/index.js",
       "default": "./dist/astro/index.js"
     },
+    "./astro/ConsentBanner": {
+      "import": "./src/astro/ConsentBanner.astro"
+    },
+    "./consent-banner": {
+      "types": "./dist/consent-banner/index.d.ts",
+      "import": "./dist/consent-banner/index.js"
+    },
     "./testing": {
       "types": "./dist/testing/conformance/index.d.ts",
       "import": "./dist/testing/conformance/index.js"
     }
   },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/build-collect.mjs",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "build:collect": "node scripts/build-collect.mjs",
+    "build:cli": "cd ../.. && ./scripts/build-cli.sh",
+    "generate-starters": "cd ../.. && tsx scripts/generate-starters.ts",
+    "compile-registry": "tsx src/cli/compile-registry.mjs",
+    "prepack": "npm run generate-starters && npm run build && node scripts/ensure-bin-modes.mjs"
+  },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.883.0",
+    "@vercel/oidc-aws-credentials-provider": "^3.3.0",
     "markdown-it": "^14.1.0",
     "sanitize-html": "^2.13.1",
     "ws": "^8.18.0"
@@ -121,6 +156,7 @@
     "@types/react": "^19.0.0",
     "@types/sanitize-html": "^2.16.0",
     "@types/ws": "^8.18.0",
+    "esbuild": "0.28.1",
     "jsdom": "^29.1.1",
     "next": "^15.5.19",
     "tsx": "^4.20.0",
@@ -128,18 +164,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.41",
-    "@gradial/aci-cli-darwin-x64": "0.1.41",
-    "@gradial/aci-cli-linux-arm64": "0.1.41",
-    "@gradial/aci-cli-linux-x64": "0.1.41",
-    "@gradial/aci-cli-win32-arm64": "0.1.41",
-    "@gradial/aci-cli-win32-x64": "0.1.41"
-  },
-  "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
-    "test": "node --import tsx --test \"src/**/*.test.ts\"",
-    "build:cli": "cd ../.. && ./scripts/build-cli.sh",
-    "generate-starters": "cd ../.. && tsx scripts/generate-starters.ts",
-    "compile-registry": "tsx src/cli/compile-registry.mjs"
+    "@gradial/aci-cli-darwin-arm64": "0.1.43",
+    "@gradial/aci-cli-darwin-x64": "0.1.43",
+    "@gradial/aci-cli-linux-arm64": "0.1.43",
+    "@gradial/aci-cli-linux-x64": "0.1.43",
+    "@gradial/aci-cli-win32-arm64": "0.1.43",
+    "@gradial/aci-cli-win32-x64": "0.1.43"
   }
-}
+}

package/src/astro/ConsentBanner.astro

@@ -0,0 +1,62 @@
+---
+// ConsentBanner.astro — Astro wrapper around the SDK's first-party consent
+// banner. Import this into your layout and pass site-specific text/styles.
+//
+// Usage:
+//   import ConsentBanner from '@gradial/aci/astro/ConsentBanner.astro';
+//   <ConsentBanner
+//     heading="Cookie Preferences"
+//     message="We use cookies to personalize your experience."
+//     acceptLabel="Accept all"
+//     rejectLabel="Reject"
+//     privacyPolicyHref="/privacy"
+//     privacyPolicyLabel="Privacy Policy"
+//   />
+
+export interface Props {
+  heading?: string;
+  message?: string;
+  acceptLabel?: string;
+  rejectLabel?: string;
+  privacyPolicyLabel?: string;
+  privacyPolicyHref?: string;
+  source?: string;
+}
+
+const {
+  heading,
+  message,
+  acceptLabel,
+  rejectLabel,
+  privacyPolicyLabel,
+  privacyPolicyHref,
+  source,
+} = Astro.props as Props;
+
+const opts = JSON.stringify({
+  heading,
+  message,
+  acceptLabel,
+  rejectLabel,
+  privacyPolicyLabel,
+  privacyPolicyHref,
+  source,
+});
+---
+
+<div
+  id="aci-consent-banner-mount"
+  data-aci-consent-banner-mount
+  data-opts={opts}
+>
+</div>
+
+<script>
+  import { mountConsentBanner } from '../consent-banner/index.js';
+
+  const mount = document.getElementById('aci-consent-banner-mount');
+  if (mount) {
+    const opts = JSON.parse(mount.getAttribute('data-opts') || '{}');
+    mountConsentBanner(document, opts);
+  }
+</script>

package/src/cli/compile-registry.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { ImageSchema } from '../types/image.ts';
 import { VideoSchema } from '../types/video.ts';
@@ -19,14 +20,15 @@ try {
   if (!globalThis.React) globalThis.React = React;
 } catch { /* react not available — component files without JSX will still work */ }
 
-const args = parseArgs(process.argv.slice(2));
-
-try {
-  const result = await compileRegistry(args);
-  console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
-} catch (error) {
-  console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
-  process.exitCode = 1;
+if (isMainModule()) {
+  const args = parseArgs(process.argv.slice(2));
+  try {
+    const result = await compileRegistry(args);
+    console.log(JSON.stringify({ success: true, ...result, errors: [] }, null, 2));
+  } catch (error) {
+    console.error(JSON.stringify({ success: false, errors: [String(error?.message ?? error)] }, null, 2));
+    process.exitCode = 1;
+  }
 }
 
 async function compileRegistry(options) {
@@ -430,9 +432,10 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
   const defs = {
     baseBlock: {
       type: 'object',
-      required: ['id', 'component', 'props'],
+      required: ['$type', 'id', 'component', 'props'],
       additionalProperties: true,
       properties: {
+        $type: { const: 'component' },
         id: { type: 'string', minLength: 1 },
         component: { type: 'string' },
         props: { type: 'object' },
@@ -741,3 +744,14 @@ function parseArgs(argv) {
   }
   return out;
 }
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+export { compileRegistry, generatePageSchema };