@gradial/aci 0.1.41 → 0.1.43

package/dist/cli/compile-registry.mjs

@@ -0,0 +1,774 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { ImageSchema } from '../types/image.ts';
+import { VideoSchema } from '../types/video.ts';
+import { getBlockRefMeta } from '../types/block-ref.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
+// runtime to be resolvable. Next.js uses jsx: "preserve" which leaves React
+// references in the transpiled output.
+try {
+    const React = await import('react');
+    if (!globalThis.React)
+        globalThis.React = React;
+}
+catch { /* react not available — component files without JSX will still work */ }
+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) {
+    const required = ['components', 'layouts', 'output'];
+    for (const key of required) {
+        if (!options[key])
+            throw new Error(`missing --${key}`);
+    }
+    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 });
+    const seenComponents = new Set();
+    const componentEntries = [];
+    const schemaFiles = [];
+    for (const [index, component] of components.entries()) {
+        validateComponent(component, index, seenComponents);
+        const componentId = component.id;
+        const schema = compileSchema(component.props, componentId);
+        const schemaFile = `schemas/${componentId}.schema.json`;
+        const schemaPath = path.join(outDir, schemaFile);
+        await writeFile(schemaPath, JSON.stringify(schema, null, 2) + '\n');
+        schemaFiles.push(schemaPath);
+        const imageSlots = normalizeImageSlots(component.imageSlots);
+        const slots = extractBlockSlots(component.props, componentId);
+        componentEntries.push({
+            id: componentId,
+            name: componentId,
+            props: schemaFile,
+            ...(Object.keys(imageSlots).length ? { imageSlots } : {}),
+            ...(Object.keys(slots).length ? { slots } : {}),
+        });
+    }
+    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,
+        });
+    }
+    const knownNames = new Set(componentEntries.map((c) => c.id));
+    for (const entry of componentEntries) {
+        for (const [slotName, slot] of Object.entries(entry.slots ?? {})) {
+            for (const childName of slot.allowed) {
+                if (!knownNames.has(childName)) {
+                    throw new Error(`${entry.id}.slots.${slotName}.allowed references unknown component "${childName}"`);
+                }
+            }
+        }
+    }
+    const registry = {
+        manifestVersion: '1',
+        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');
+    const pageSchemaPath = await generatePageSchema(schemaDir, componentEntries, outDir);
+    schemaFiles.push(pageSchemaPath);
+    return { registry: registryPath, schemas: schemaFiles };
+}
+async function loadDefaultArray(modulePath, label) {
+    const mod = await import(pathToFileURL(path.resolve(modulePath)).href);
+    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.id)
+        throw new Error(`components[${index}].id is required`);
+    if (seen.has(component.id))
+        throw new Error(`duplicate component id ${component.id}`);
+    seen.add(component.id);
+    if (!component.props)
+        throw new Error(`components[${index}].props is required`);
+    validateZodSubset(component.props, `components[${index}].props`);
+    validateImageSlotSchemaMatch(component, index);
+}
+function validateImageSlotSchemaMatch(component, index) {
+    const imageSlots = normalizeImageSlots(component.imageSlots);
+    const mediaFields = collectMediaFields(component.props);
+    const imageFields = new Set(mediaFields.filter(([, k]) => k === 'image').map(([p]) => p));
+    const allMediaFields = new Set(mediaFields.map(([p]) => p));
+    for (const field of imageFields) {
+        if (!Object.prototype.hasOwnProperty.call(imageSlots, field)) {
+            throw new Error(`components[${index}].imageSlots.${field} is required because props field ${field} uses an image schema`);
+        }
+    }
+    for (const field of Object.keys(imageSlots)) {
+        if (!allMediaFields.has(field)) {
+            throw new Error(`components[${index}].props.${field} must use an image or asset schema because imageSlots.${field} is declared`);
+        }
+    }
+}
+function extractBlockSlots(schema, componentId) {
+    const shape = getSchemaShape(schema);
+    if (!shape)
+        return {};
+    const out = {};
+    for (const [name, fieldSchema] of Object.entries(shape)) {
+        const unwrapped = unwrapOptionalSchema(fieldSchema);
+        const meta = getBlockRefMeta(unwrapped) ?? getBlockRefMeta(unwrapArraySchema(unwrapped));
+        if (meta) {
+            out[name] = {
+                allowed: [...meta.allowed],
+                multiple: meta.multiple,
+                required: false,
+            };
+        }
+    }
+    return out;
+}
+function unwrapOptionalSchema(schema) {
+    let current = schema;
+    const seen = new Set();
+    while (current && typeof current === 'object' && !seen.has(current)) {
+        seen.add(current);
+        const def = current._def;
+        if (!def || typeof def !== 'object')
+            break;
+        const type = def.type;
+        const typeName = def.typeName;
+        if (type === 'optional' || type === 'nullable' || type === 'default' ||
+            typeName === 'ZodOptional' || typeName === 'ZodNullable' || typeName === 'ZodDefault') {
+            const inner = def.innerType ?? def.schema;
+            if (inner) {
+                current = inner;
+                continue;
+            }
+        }
+        break;
+    }
+    return current;
+}
+function getSchemaShape(schema) {
+    if (!schema || typeof schema !== 'object')
+        return null;
+    const def = schema._def;
+    if (!def)
+        return null;
+    const shape = typeof def.shape === 'function' ? def.shape() : def.shape;
+    if (shape && typeof shape === 'object')
+        return shape;
+    return null;
+}
+function unwrapArraySchema(schema) {
+    if (!schema || typeof schema !== 'object')
+        return null;
+    const def = schema._def;
+    if (!def)
+        return null;
+    if (def.type === 'array' && def.element)
+        return def.element;
+    if (def.typeName === 'ZodArray' && def.type)
+        return def.type;
+    return null;
+}
+function normalizeImageSlots(imageSlots) {
+    if (imageSlots == null)
+        return {};
+    if (typeof imageSlots !== 'object' || Array.isArray(imageSlots)) {
+        throw new Error('imageSlots must be an object');
+    }
+    const out = {};
+    for (const [key, slot] of Object.entries(imageSlots)) {
+        if (!key)
+            throw new Error('imageSlots keys must be non-empty');
+        if (!slot || typeof slot !== 'object' || Array.isArray(slot)) {
+            throw new Error(`imageSlots.${key} must be an object`);
+        }
+        if (!Array.isArray(slot.outputs) || !slot.outputs.length) {
+            throw new Error(`imageSlots.${key}.outputs must be a non-empty array`);
+        }
+        if (!Array.isArray(slot.formats) || !slot.formats.length) {
+            throw new Error(`imageSlots.${key}.formats must be a non-empty array`);
+        }
+        if (typeof slot.sizes !== 'string' || !slot.sizes.trim()) {
+            throw new Error(`imageSlots.${key}.sizes must be a non-empty string`);
+        }
+        out[key] = {
+            outputs: slot.outputs.map((output, outputIndex) => normalizeSlotOutput(key, output, outputIndex)),
+            formats: slot.formats.map((format, formatIndex) => {
+                if (typeof format !== 'string' || !format.trim()) {
+                    throw new Error(`imageSlots.${key}.formats[${formatIndex}] must be a non-empty string`);
+                }
+                return format;
+            }),
+            sizes: slot.sizes,
+        };
+    }
+    return out;
+}
+function normalizeSlotOutput(slotKey, output, outputIndex) {
+    if (!output || typeof output !== 'object' || Array.isArray(output)) {
+        throw new Error(`imageSlots.${slotKey}.outputs[${outputIndex}] must be an object`);
+    }
+    if (typeof output.aspectRatio !== 'string' || !output.aspectRatio.trim()) {
+        throw new Error(`imageSlots.${slotKey}.outputs[${outputIndex}].aspectRatio must be a non-empty string`);
+    }
+    if (!Array.isArray(output.widths) || !output.widths.length) {
+        throw new Error(`imageSlots.${slotKey}.outputs[${outputIndex}].widths must be a non-empty array`);
+    }
+    const widths = output.widths.map((width, widthIndex) => {
+        if (!Number.isInteger(width) || width <= 0) {
+            throw new Error(`imageSlots.${slotKey}.outputs[${outputIndex}].widths[${widthIndex}] must be a positive integer`);
+        }
+        return width;
+    });
+    return {
+        aspectRatio: output.aspectRatio,
+        widths,
+        ...(typeof output.media === 'string' && output.media.trim() ? { media: output.media } : {}),
+    };
+}
+/**
+ * Walks a Zod schema and returns [dotPath, kind] pairs for every field
+ * that contains an image or asset schema.
+ * kind = 'image' for ImageSchema-only fields, 'asset' for unions (image | video).
+ */
+function collectMediaFields(schema, prefix = '') {
+    if (!schema)
+        return [];
+    if (prefix && isImageSchema(schema))
+        return [[prefix, 'image']];
+    if (prefix && isVideoSchema(schema))
+        return [];
+    const itemSchema = arrayItemSchema(schema);
+    if (itemSchema)
+        return collectMediaFields(itemSchema, prefix);
+    const unionOptions = unionOptionSchemas(schema);
+    if (unionOptions) {
+        const hasImage = unionOptions.some((opt) => isImageSchema(opt));
+        const hasVideo = unionOptions.some((opt) => isVideoSchema(opt));
+        if (prefix && hasImage && hasVideo)
+            return [[prefix, 'asset']];
+        if (prefix && hasVideo)
+            return [];
+        return unionOptions.flatMap((opt) => collectMediaFields(opt, prefix));
+    }
+    const shape = getSchemaShape(unwrapSchema(schema));
+    if (!shape)
+        return [];
+    return Object.entries(shape).flatMap(([field, fieldSchema]) => collectMediaFields(fieldSchema, prefix ? `${prefix}.${field}` : field));
+}
+function unionOptionSchemas(schema) {
+    const def = unwrapSchema(schema)?._def;
+    if (!def)
+        return null;
+    if (Array.isArray(def.options))
+        return def.options;
+    if (def.options instanceof Map)
+        return Array.from(def.options.values());
+    return null;
+}
+function arrayItemSchema(schema) {
+    let current = schema;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        const def = current?._def;
+        if (!def) {
+            // Zod 4 mini: check for ~standard array type
+            if (current?.type === 'array' && current?.element)
+                return current.element;
+            return null;
+        }
+        if (def.typeName === 'ZodArray')
+            return def.type;
+        // Zod 4: array element might be in def.element
+        if (def.type === 'array' && def.element)
+            return def.element;
+        current = def.innerType ?? def.schema;
+    }
+    return null;
+}
+function isImageSchema(schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (unwrapped === ImageSchema)
+        return true;
+    try {
+        const compiled = z.toJSONSchema(unwrapped, {
+            target: 'draft-2020-12',
+            unrepresentable: 'throw',
+        });
+        const properties = compiled?.properties ?? {};
+        const required = new Set(compiled?.required ?? []);
+        return compiled?.type === 'object'
+            && properties.$type?.const === 'gradial.image'
+            && properties.assetId?.type === 'string'
+            && properties.versionId?.type === 'string'
+            && properties.alt?.type === 'string'
+            && properties.sources?.type === 'array'
+            && required.has('$type')
+            && required.has('assetId')
+            && required.has('versionId')
+            && required.has('alt')
+            && required.has('sources');
+    }
+    catch {
+        return false;
+    }
+}
+function isVideoSchema(schema) {
+    const unwrapped = unwrapSchema(schema);
+    if (unwrapped === VideoSchema)
+        return true;
+    try {
+        const compiled = z.toJSONSchema(unwrapped, {
+            target: 'draft-2020-12',
+            unrepresentable: 'throw',
+        });
+        return compiled?.type === 'object'
+            && compiled?.properties?.$type?.const === 'gradial.video';
+    }
+    catch {
+        return false;
+    }
+}
+function unwrapSchema(schema) {
+    let current = schema;
+    const seen = new Set();
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        if (current === ImageSchema)
+            return current;
+        const def = current._def;
+        const next = def?.innerType ?? def?.schema;
+        if (!next)
+            break;
+        current = next;
+    }
+    return current;
+}
+function validateLayout(layout, index, seen) {
+    if (!layout || typeof layout !== 'object')
+        throw new Error(`layouts[${index}] must be an object`);
+    if (!layout.name)
+        throw new Error(`layouts[${index}].name is required`);
+    if (seen.has(layout.name))
+        throw new Error(`duplicate layout name ${layout.name}`);
+    seen.add(layout.name);
+    if (!Array.isArray(layout.slots))
+        throw new Error(`layouts[${index}].slots must be an array`);
+    const slots = [];
+    const seenSlots = new Set();
+    for (const [slotIndex, slot] of layout.slots.entries()) {
+        if (!slot?.name)
+            throw new Error(`layouts[${index}].slots[${slotIndex}].name is required`);
+        if (seenSlots.has(slot.name))
+            throw new Error(`duplicate slot name ${slot.name} in layout ${layout.name}`);
+        seenSlots.add(slot.name);
+        slots.push({ name: slot.name, required: Boolean(slot.required) });
+    }
+    const entry = { name: layout.name, slots };
+    if (layout.defaults && typeof layout.defaults === 'object') {
+        entry.defaults = layout.defaults;
+    }
+    return entry;
+}
+function compileSchema(schema, name) {
+    const toJSONSchema = z.toJSONSchema;
+    if (typeof toJSONSchema !== 'function') {
+        throw new Error('Zod 4 is required: install zod@^4.0.0');
+    }
+    const compiled = toJSONSchema(schema, {
+        target: 'draft-2020-12',
+        unrepresentable: 'throw',
+    });
+    return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        title: name,
+        ...compiled,
+    };
+}
+async function generatePageSchema(schemaDir, componentEntries, outDir) {
+    const { readFile } = await import('node:fs/promises');
+    const defs = {
+        baseBlock: {
+            type: 'object',
+            required: ['$type', 'id', 'component', 'props'],
+            additionalProperties: true,
+            properties: {
+                $type: { const: 'component' },
+                id: { type: 'string', minLength: 1 },
+                component: { type: 'string' },
+                props: { type: 'object' },
+                slots: {
+                    type: 'object',
+                    additionalProperties: {
+                        type: 'array',
+                        items: { $ref: '#/$defs/baseBlock' },
+                    },
+                },
+            },
+        },
+        damAssetRef: {
+            type: 'object',
+            required: ['$type', 'assetId'],
+            additionalProperties: true,
+            properties: {
+                $type: { const: 'dam.assetRef' },
+                assetId: { type: 'string', minLength: 1 },
+                version: { type: 'string', minLength: 1 },
+                alt: { type: 'string' },
+            },
+        },
+        staticAssetRef: {
+            type: 'object',
+            required: ['$type', 'src'],
+            additionalProperties: true,
+            properties: {
+                $type: { const: 'static.assetRef' },
+                src: { type: 'string', minLength: 1 },
+                alt: { type: 'string' },
+                mediaType: { type: 'string' },
+                width: { type: 'number' },
+                height: { type: 'number' },
+            },
+        },
+        assetRef: {
+            oneOf: [
+                { $ref: '#/$defs/damAssetRef' },
+                { $ref: '#/$defs/staticAssetRef' },
+            ],
+        },
+    };
+    const oneOf = [];
+    for (const entry of componentEntries) {
+        const schemaPath = path.join(outDir, entry.props);
+        const raw = await readFile(schemaPath, 'utf-8');
+        const componentSchema = JSON.parse(raw);
+        const { $schema: _s, title: _t, ...propsSchema } = componentSchema;
+        replaceImagesWithDamAssetRef(propsSchema, defs.damAssetRef);
+        const defName = `${entry.name}Block`;
+        defs[defName] = {
+            allOf: [
+                { $ref: '#/$defs/baseBlock' },
+                {
+                    properties: {
+                        component: { const: entry.name },
+                        props: propsSchema,
+                    },
+                },
+            ],
+        };
+        oneOf.push({ $ref: `#/$defs/${defName}` });
+    }
+    const pageSchema = {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        $id: 'https://baremetal.local/schemas/page.schema.json',
+        title: 'bare-metal Page',
+        type: 'object',
+        required: ['$type', 'id', 'status', 'layout', 'metadata', 'regions'],
+        additionalProperties: true,
+        properties: {
+            $type: { const: 'page' },
+            id: { type: 'string', minLength: 1 },
+            status: { type: 'string', minLength: 1 },
+            layout: { type: 'string', minLength: 1 },
+            metadata: {
+                type: 'object',
+                required: ['title'],
+                additionalProperties: true,
+                properties: {
+                    title: { type: 'string', minLength: 1 },
+                    description: { type: 'string' },
+                    canonical: { type: 'string' },
+                },
+            },
+            regions: {
+                type: 'object',
+                additionalProperties: {
+                    type: 'array',
+                    items: { oneOf },
+                },
+            },
+        },
+        $defs: defs,
+    };
+    const pageSchemaPath = path.join(schemaDir, 'page.schema.json');
+    await writeFile(pageSchemaPath, JSON.stringify(pageSchema, null, 2) + '\n');
+    return pageSchemaPath;
+}
+function replaceImagesWithDamAssetRef(schema, damAssetRef) {
+    if (!schema || typeof schema !== 'object')
+        return schema;
+    if (schema.$ref)
+        return;
+    if (Array.isArray(schema.anyOf)) {
+        for (const s of schema.anyOf)
+            replaceImagesWithDamAssetRef(s, damAssetRef);
+    }
+    if (Array.isArray(schema.allOf)) {
+        for (const s of schema.allOf)
+            replaceImagesWithDamAssetRef(s, damAssetRef);
+    }
+    if (Array.isArray(schema.oneOf)) {
+        for (const s of schema.oneOf)
+            replaceImagesWithDamAssetRef(s, damAssetRef);
+    }
+    if (schema.properties) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+            if (isJsonAssetRef(value)) {
+                schema.properties[key] = { $ref: '#/$defs/assetRef' };
+            }
+            else {
+                replaceImagesWithDamAssetRef(value, damAssetRef);
+            }
+        }
+    }
+    if (schema.items) {
+        if (isJsonAssetRef(schema.items)) {
+            schema.items = { $ref: '#/$defs/assetRef' };
+        }
+        else {
+            replaceImagesWithDamAssetRef(schema.items, damAssetRef);
+        }
+    }
+}
+function isJsonAssetRef(node) {
+    if (node?.type !== 'object' || !node?.properties?.$type)
+        return false;
+    const constVal = node.properties.$type.const;
+    return constVal === 'gradial.image' || constVal === 'gradial.video';
+}
+function validateZodSubset(schema, pathLabel, seen = new Set()) {
+    if (seen.has(schema))
+        return;
+    seen.add(schema);
+    const def = schema?._def;
+    if (!def)
+        throw new Error(`${pathLabel}: expected a Zod schema`);
+    const typeName = def.typeName ?? def.type;
+    if (unsupportedZodType(typeName)) {
+        throw new Error(`${pathLabel}: unsupported Zod feature ${typeName}`);
+    }
+    rejectUnsupportedChecks(def, pathLabel);
+    for (const child of childSchemas(def)) {
+        validateZodSubset(child.schema, `${pathLabel}${child.path}`, seen);
+    }
+}
+function unsupportedZodType(typeName) {
+    return new Set([
+        'ZodEffects',
+        'ZodPipeline',
+        'ZodLazy',
+        'ZodPromise',
+        'ZodFunction',
+        'ZodTransform',
+        'pipe',
+        'lazy',
+        'promise',
+        'function',
+        'transform',
+        'custom',
+    ]).has(String(typeName));
+}
+function rejectUnsupportedChecks(def, pathLabel) {
+    if (!Array.isArray(def.checks))
+        return;
+    for (const [index, check] of def.checks.entries()) {
+        const checkType = check?.def?.type ?? check?._def?.type ?? check?._zod?.def?.check;
+        if (String(checkType) === 'custom') {
+            throw new Error(`${pathLabel}.checks[${index}]: unsupported Zod feature custom`);
+        }
+    }
+}
+function childSchemas(def) {
+    const children = [];
+    if (def.innerType)
+        children.push({ path: '.inner', schema: def.innerType });
+    if (def.schema)
+        children.push({ path: '.schema', schema: def.schema });
+    if (def.valueType)
+        children.push({ path: '.value', schema: def.valueType });
+    if (def.keyType)
+        children.push({ path: '.key', schema: def.keyType });
+    if (Array.isArray(def.options))
+        def.options.forEach((schema, index) => children.push({ path: `.options[${index}]`, schema }));
+    if (Array.isArray(def.items))
+        def.items.forEach((schema, index) => children.push({ path: `.items[${index}]`, schema }));
+    const shape = typeof def.shape === 'function' ? def.shape() : def.shape;
+    if (shape && typeof shape === 'object') {
+        for (const [name, schema] of Object.entries(shape))
+            children.push({ path: `.shape.${name}`, schema });
+    }
+    return children;
+}
+// ---------------------------------------------------------------------------
+// Nested block detection — walks generated JSON schemas to find blockRef
+// patterns (objects with `component` enum + `props`) and validates that
+// referenced component names exist in the registry.
+// ---------------------------------------------------------------------------
+function collectNestedBlockRefs(schema, knownNames, componentName) {
+    const results = [];
+    _walkSchemaForBlockRefs(schema, schema, '', results, knownNames, componentName);
+    return results;
+}
+function _walkSchemaForBlockRefs(node, rootSchema, currentPath, results, knownNames, componentName) {
+    if (!node || typeof node !== 'object')
+        return;
+    // Resolve $ref
+    if (node.$ref) {
+        const resolved = resolveJsonSchemaRef(node.$ref, rootSchema);
+        if (resolved)
+            _walkSchemaForBlockRefs(resolved, rootSchema, currentPath, results, knownNames, componentName);
+        return;
+    }
+    // Check if this object matches the blockRef signature:
+    // { type: "object", properties: { id, component, props } }
+    if (isBlockRefSchema(node)) {
+        const allow = extractBlockRefAllow(node, rootSchema);
+        // Validate allowed names exist
+        for (const name of allow) {
+            if (!knownNames.has(name)) {
+                throw new Error(`${componentName}: nested block allowlist references unknown component "${name}" at ${currentPath || '(root)'}`);
+            }
+        }
+        results.push({
+            path: currentPath || '(root)',
+            ...(allow.length > 0 ? { allow } : {}),
+        });
+        return; // Don't recurse into the block schema itself
+    }
+    // Recurse into object properties
+    if (node.properties) {
+        for (const [key, propSchema] of Object.entries(node.properties)) {
+            const nextPath = currentPath ? `${currentPath}.${key}` : key;
+            _walkSchemaForBlockRefs(propSchema, rootSchema, nextPath, results, knownNames, componentName);
+        }
+    }
+    // Recurse into array items
+    if (node.items) {
+        _walkSchemaForBlockRefs(node.items, rootSchema, `${currentPath}[]`, results, knownNames, componentName);
+    }
+    // Recurse into anyOf / allOf / oneOf
+    for (const keyword of ['anyOf', 'allOf', 'oneOf']) {
+        if (Array.isArray(node[keyword])) {
+            for (const sub of node[keyword]) {
+                _walkSchemaForBlockRefs(sub, rootSchema, currentPath, results, knownNames, componentName);
+            }
+        }
+    }
+}
+function isBlockRefSchema(node) {
+    if (node.type !== 'object' || !node.properties)
+        return false;
+    const props = node.properties;
+    // Must have component and props fields
+    if (!props.component || !props.props)
+        return false;
+    // component must be a string or enum
+    const comp = props.component;
+    if (comp.type !== 'string' && !Array.isArray(comp.enum))
+        return false;
+    // props must be an object (record)
+    if (props.props.type !== 'object')
+        return false;
+    return true;
+}
+function extractBlockRefAllow(node, rootSchema) {
+    let comp = node.properties.component;
+    // Resolve $ref on the component field
+    if (comp.$ref) {
+        comp = resolveJsonSchemaRef(comp.$ref, rootSchema) ?? comp;
+    }
+    if (Array.isArray(comp.enum)) {
+        return comp.enum.filter((v) => typeof v === 'string');
+    }
+    return [];
+}
+function resolveJsonSchemaRef(ref, rootSchema) {
+    if (!ref || !ref.startsWith('#/'))
+        return null;
+    const parts = ref.slice(2).split('/');
+    let current = rootSchema;
+    for (const part of parts) {
+        current = current?.[part];
+    }
+    return current ?? null;
+}
+function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const body = arg.slice(2);
+        const equals = body.indexOf('=');
+        if (equals >= 0) {
+            out[body.slice(0, equals)] = body.slice(equals + 1);
+            continue;
+        }
+        out[body] = argv[++i];
+    }
+    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 };