@gradial/aci 0.1.0 → 0.1.2

package/dist/types/media.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { GradialImageSchema, renderImageHTML } from './image.js';
+import { GradialVideoSchema } from './video.js';
+// ---------------------------------------------------------------------------
+// Zod schema — discriminated on $type
+// ---------------------------------------------------------------------------
+export const GradialAssetSchema = z.discriminatedUnion('$type', [
+    GradialImageSchema,
+    GradialVideoSchema,
+]);
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+export function isGradialImage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.$type === 'gradial.image');
+}
+export function isGradialVideo(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.$type === 'gradial.video');
+}
+export function isGradialAsset(value) {
+    return isGradialImage(value) || isGradialVideo(value);
+}
+// ---------------------------------------------------------------------------
+// HTML string renderers (framework-agnostic)
+// ---------------------------------------------------------------------------
+/**
+ * Renders a GradialVideo to an HTML string.
+ * Uses poster.fallback.src for the poster attribute.
+ * Includes <source> elements for format variants.
+ */
+export function renderVideoHTML(video, attrs = {}) {
+    const posterSrc = video.poster?.fallback.src;
+    const attrPairs = [
+        ...Object.entries(attrs),
+        ['src', video.sources?.length ? undefined : video.src],
+        ['poster', posterSrc],
+        ['width', video.width > 0 ? video.width : undefined],
+        ['height', video.height > 0 ? video.height : undefined],
+    ];
+    const attrString = renderAttrs(attrPairs);
+    const sources = (video.sources ?? [])
+        .map((s) => `<source${renderAttrs([['src', s.src], ['type', s.type]])}>`)
+        .join('');
+    // If no format variants, src is on the <video> element itself
+    if (!sources) {
+        return `<video${attrString}></video>`;
+    }
+    return `<video${attrString}>${sources}</video>`;
+}
+/**
+ * Renders any GradialAsset to an HTML string.
+ * Delegates to renderImageHTML or renderVideoHTML based on $type.
+ */
+export function renderAssetHTML(asset, attrs = {}) {
+    if (asset.$type === 'gradial.image') {
+        return renderImageHTML(asset, attrs);
+    }
+    return renderVideoHTML(asset, attrs);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function renderAttrs(pairs) {
+    const rendered = pairs
+        .filter(([, value]) => value !== undefined && value !== null && value !== false)
+        .map(([name, value]) => value === true
+        ? escapeName(name)
+        : `${escapeName(name)}="${escapeAttr(String(value))}"`);
+    if (!rendered.length)
+        return '';
+    return ' ' + rendered.join(' ');
+}
+function escapeName(name) {
+    return name.replace(/[^A-Za-z0-9_:-]/g, '');
+}
+function escapeAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}

package/dist/types/video.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { type GradialImage } from './image.js';
+export interface VideoSource {
+    src: string;
+    type: string;
+}
+export interface GradialVideo {
+    /** Discriminator — always 'gradial.video'. */
+    $type: 'gradial.video';
+    /** DAM asset identifier. */
+    assetId: string;
+    /** DAM version identifier. */
+    versionId: string;
+    /** Accessible description of the video content. */
+    alt: string;
+    /** Primary video URL (compiler-resolved). */
+    src: string;
+    /** Primary video MIME type (e.g. 'video/mp4'). */
+    type: string;
+    /** Intrinsic width in pixels. */
+    width: number;
+    /** Intrinsic height in pixels. */
+    height: number;
+    /**
+     * Poster frame — a full GradialImage with responsive srcset.
+     * The compiler extracts or generates this from the video asset.
+     */
+    poster?: GradialImage;
+    /** Format variants (e.g. mp4 + webm). Maps to <video><source> elements. */
+    sources?: VideoSource[];
+    /** Duration in seconds (if known). */
+    duration?: number;
+}
+export declare const VideoSourceSchema: z.ZodObject<{
+    src: z.ZodString;
+    type: z.ZodString;
+}, z.core.$strip>;
+export declare const GradialVideoSchema: z.ZodObject<{
+    $type: z.ZodLiteral<"gradial.video">;
+    assetId: z.ZodString;
+    versionId: z.ZodString;
+    alt: z.ZodString;
+    src: z.ZodString;
+    type: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    poster: z.ZodOptional<z.ZodObject<{
+        $type: z.ZodLiteral<"gradial.image">;
+        assetId: z.ZodString;
+        versionId: z.ZodString;
+        alt: z.ZodString;
+        fallback: z.ZodObject<{
+            src: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            type: z.ZodString;
+        }, z.core.$strip>;
+        sources: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            media: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+            srcset: z.ZodString;
+            sizes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        src: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>>;
+    duration: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;

package/dist/types/video.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { GradialImageSchema } from './image.js';
+// ---------------------------------------------------------------------------
+// Zod schema
+// ---------------------------------------------------------------------------
+export const VideoSourceSchema = z.object({
+    src: z.string().min(1),
+    type: z.string().min(1),
+});
+export const GradialVideoSchema = z.object({
+    $type: z.literal('gradial.video'),
+    assetId: z.string().min(1),
+    versionId: z.string().min(1),
+    alt: z.string(),
+    src: z.string().min(1),
+    type: z.string().min(1),
+    width: z.number().int().nonnegative(),
+    height: z.number().int().nonnegative(),
+    poster: GradialImageSchema.optional(),
+    sources: z.array(VideoSourceSchema).optional(),
+    duration: z.number().nonnegative().optional(),
+});

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "bin/aci.js",
+    "bin/aci",
     "src/cli/*.mjs",
     "README.md"
   ],
+  "bin": {
+    "aci": "./bin/aci.js"
+  },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "exports": {
     ".": {
@@ -41,14 +46,31 @@
       "types": "./dist/providers/file.d.ts",
       "import": "./dist/providers/file.js"
     },
+    "./providers/s3": {
+      "types": "./dist/providers/s3.d.ts",
+      "import": "./dist/providers/s3.js"
+    },
     "./dev": {
       "types": "./dist/dev/index.d.ts",
       "import": "./dist/dev/index.js"
     },
+    "./assets": {
+      "types": "./dist/assets/index.d.ts",
+      "import": "./dist/assets/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
     "./astro": {
       "types": "./dist/astro/index.d.ts",
       "import": "./dist/astro/index.js"
     },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js",
+      "default": "./dist/next/index.js"
+    },
     "./next/server": {
       "types": "./dist/next/server.d.ts",
       "import": "./dist/next/server.js",
@@ -63,6 +85,10 @@
       "types": "./dist/next/dev-refresh.d.ts",
       "import": "./dist/next/dev-refresh.js"
     },
+    "./next/asset-route": {
+      "types": "./dist/next/asset-route.d.ts",
+      "import": "./dist/next/asset-route.js"
+    },
     "./sveltekit": {
       "types": "./dist/sveltekit/index.d.ts",
       "import": "./dist/sveltekit/index.js"
@@ -72,10 +98,12 @@
       "import": "./dist/testing/index.js"
     },
     "./cli/compile-registry": "./src/cli/compile-registry.mjs",
+    "./cli/validate-content": "./src/cli/validate-content.mjs",
     "./cli/verify-renderer": "./src/cli/verify-renderer.mjs"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "build:cli": "cd ../.. && ./scripts/build-cli.sh",
     "compile-registry": "tsx src/cli/compile-registry.mjs",
     "prepack": "npm run build"
   },

package/src/cli/compile-registry.mjs

@@ -3,6 +3,17 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
+import { GradialImageSchema } from '../types/image.ts';
+
+// 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 */ }
 
 const args = parseArgs(process.argv.slice(2));
 
@@ -38,6 +49,7 @@ async function compileRegistry(options) {
     schemaFiles.push(schemaPath);
     const renderModes = component.renderModes ?? component.render;
     const varyDimensions = component.varyDimensions ?? component.vary;
+    const imageSlots = normalizeImageSlots(component.imageSlots);
     componentEntries.push({
       name: component.name,
       schemaFile,
@@ -53,12 +65,26 @@ async function compileRegistry(options) {
       },
       ...(component.defaultIslandMode ? { defaultIslandMode: component.defaultIslandMode } : {}),
       ...(varyDimensions?.length ? { vary: varyDimensions, varyDimensions } : {}),
+      ...(Object.keys(imageSlots).length ? { imageSlots } : {}),
     });
   }
 
   const seenLayouts = new Set();
   const layoutEntries = layouts.map((layout, index) => validateLayout(layout, index, seenLayouts));
 
+  // 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));
+  for (const entry of componentEntries) {
+    const schemaPath = path.join(outDir, entry.schemaFile);
+    const schemaRaw = await import('node:fs/promises').then((fs) => fs.readFile(schemaPath, 'utf-8'));
+    const schema = JSON.parse(schemaRaw);
+    const nestedBlocks = collectNestedBlockRefs(schema, knownNames, entry.name);
+    if (nestedBlocks.length > 0) {
+      entry.nestedBlocks = nestedBlocks;
+    }
+  }
+
   const registry = {
     manifestVersion: '1',
     generatedAt: new Date().toISOString(),
@@ -84,6 +110,7 @@ function validateComponent(component, index, seen) {
   seen.add(component.name);
   if (!component.schema) throw new Error(`components[${index}].schema is required`);
   validateZodSubset(component.schema, `components[${index}].schema`);
+  validateImageSlotSchemaMatch(component, index);
   const renderModes = component.renderModes ?? component.render;
   if (!renderModes) throw new Error(`components[${index}].renderModes is required`);
   const enabled = Boolean(renderModes.canStatic ?? renderModes.static)
@@ -92,6 +119,183 @@ function validateComponent(component, index, seen) {
   if (!enabled) throw new Error(`components[${index}].renderModes must enable at least one mode`);
 }
 
+function validateImageSlotSchemaMatch(component, index) {
+  const imageSlots = normalizeImageSlots(component.imageSlots);
+  const imageFields = collectGradialImageFields(component.schema);
+  for (const field of imageFields) {
+    if (!Object.prototype.hasOwnProperty.call(imageSlots, field)) {
+      throw new Error(`components[${index}].imageSlots.${field} is required because schema field ${field} uses GradialImageSchema`);
+    }
+  }
+  for (const field of Object.keys(imageSlots)) {
+    if (!imageFields.has(field)) {
+      throw new Error(`components[${index}].schema.${field} must use GradialImageSchema because imageSlots.${field} is declared`);
+    }
+  }
+}
+
+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 } : {}),
+  };
+}
+
+function collectGradialImageFields(schema) {
+  const out = new Set();
+
+  collectGradialImageFieldsFromSchema(schema, '', out);
+
+  return out;
+}
+
+function collectGradialImageFieldsFromSchema(schema, prefix, out) {
+  if (!schema) {
+    return;
+  }
+
+  if (prefix && isGradialImageSchema(schema)) {
+    out.add(prefix);
+    return;
+  }
+
+  const itemSchema = arrayItemSchema(schema);
+  if (itemSchema) {
+    collectGradialImageFieldsFromSchema(itemSchema, prefix, out);
+    return;
+  }
+
+  const unionOptions = unionOptionSchemas(schema);
+  if (unionOptions) {
+    for (const option of unionOptions) {
+      collectGradialImageFieldsFromSchema(option, prefix, out);
+    }
+    return;
+  }
+
+  const def = unwrapSchema(schema)?._def;
+  const shape = typeof def?.shape === 'function' ? def.shape() : def?.shape;
+  if (!shape || typeof shape !== 'object') {
+    return;
+  }
+
+  for (const [field, fieldSchema] of Object.entries(shape)) {
+    const nextPrefix = prefix ? `${prefix}.${field}` : field;
+    collectGradialImageFieldsFromSchema(fieldSchema, nextPrefix, out);
+  }
+}
+
+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 isGradialImageSchema(schema) {
+  const unwrapped = unwrapSchema(schema);
+  if (unwrapped === GradialImageSchema) return true;
+  try {
+    const compiled = z.toJSONSchema(unwrapped, {
+      target: 'draft-2020-12',
+      unrepresentable: 'throw',
+    });
+    const sources = compiled?.properties?.sources;
+    const sourcesIsArray = sources?.type === 'array'
+      || (Array.isArray(sources?.anyOf) && sources.anyOf.some((s) => s?.type === 'array'));
+    return compiled?.type === 'object'
+      && compiled?.properties?.$type?.const === 'gradial.image'
+      && compiled?.properties?.fallback?.type === 'object'
+      && sourcesIsArray;
+  } catch {
+    return false;
+  }
+}
+
+function unwrapSchema(schema) {
+  let current = schema;
+  const seen = new Set();
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    if (current === GradialImageSchema) 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`);
@@ -182,6 +386,105 @@ function childSchemas(def) {
   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++) {