@gradial/aci 0.1.23 → 0.1.25

package/src/cli/compile-registry.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { 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_-]*$/;
@@ -147,15 +148,17 @@ function validateComponent(component, index, seen) {
 
 function validateImageSlotSchemaMatch(component, index) {
   const imageSlots = normalizeImageSlots(component.imageSlots);
-  const imageFields = collectImageFields(component.props);
+  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 (!imageFields.has(field)) {
-      throw new Error(`components[${index}].props.${field} must use an image schema because imageSlots.${field} is declared`);
+    if (!allMediaFields.has(field)) {
+      throw new Error(`components[${index}].props.${field} must use an image or asset schema because imageSlots.${field} is declared`);
     }
   }
 }
@@ -272,48 +275,35 @@ function normalizeSlotOutput(slotKey, output, outputIndex) {
   };
 }
 
-function collectImageFields(schema) {
-  const out = new Set();
+/**
+ * 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 [];
 
-  collectImageFieldsFromSchema(schema, '', out);
-
-  return out;
-}
-
-function collectImageFieldsFromSchema(schema, prefix, out) {
-  if (!schema) {
-    return;
-  }
-
-  if (prefix && isImageSchema(schema)) {
-    out.add(prefix);
-    return;
-  }
+  if (prefix && isImageSchema(schema)) return [[prefix, 'image']];
+  if (prefix && isVideoSchema(schema)) return [];
 
   const itemSchema = arrayItemSchema(schema);
-  if (itemSchema) {
-    collectImageFieldsFromSchema(itemSchema, prefix, out);
-    return;
-  }
+  if (itemSchema) return collectMediaFields(itemSchema, prefix);
 
   const unionOptions = unionOptionSchemas(schema);
   if (unionOptions) {
-    for (const option of unionOptions) {
-      collectImageFieldsFromSchema(option, prefix, out);
-    }
-    return;
+    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 def = unwrapSchema(schema)?._def;
-  const shape = typeof def?.shape === 'function' ? def.shape() : def?.shape;
-  if (!shape || typeof shape !== 'object') {
-    return;
-  }
+  const shape = getSchemaShape(unwrapSchema(schema));
+  if (!shape) return [];
 
-  for (const [field, fieldSchema] of Object.entries(shape)) {
-    const nextPrefix = prefix ? `${prefix}.${field}` : field;
-    collectImageFieldsFromSchema(fieldSchema, nextPrefix, out);
-  }
+  return Object.entries(shape).flatMap(([field, fieldSchema]) =>
+    collectMediaFields(fieldSchema, prefix ? `${prefix}.${field}` : field),
+  );
 }
 
 function unionOptionSchemas(schema) {
@@ -369,6 +359,21 @@ function isImageSchema(schema) {
   }
 }
 
+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();
@@ -451,6 +456,25 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
         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) {
@@ -524,25 +548,26 @@ function replaceImagesWithDamAssetRef(schema, damAssetRef) {
   }
   if (schema.properties) {
     for (const [key, value] of Object.entries(schema.properties)) {
-      if (isJsonImage(value)) {
-        schema.properties[key] = { $ref: '#/$defs/damAssetRef' };
+      if (isJsonAssetRef(value)) {
+        schema.properties[key] = { $ref: '#/$defs/assetRef' };
       } else {
         replaceImagesWithDamAssetRef(value, damAssetRef);
       }
     }
   }
   if (schema.items) {
-    if (isJsonImage(schema.items)) {
-      schema.items = { $ref: '#/$defs/damAssetRef' };
+    if (isJsonAssetRef(schema.items)) {
+      schema.items = { $ref: '#/$defs/assetRef' };
     } else {
       replaceImagesWithDamAssetRef(schema.items, damAssetRef);
     }
   }
 }
 
-function isJsonImage(node) {
-  return node?.type === 'object'
-    && node?.properties?.$type?.const === 'gradial.image';
+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()) {

package/src/cli/verify-next-cdn-routes.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const projectRoot = process.argv[2] || '.';
+
+const checks = [];
+const missing = [];
+
+function checkFile(label, relativePath, validate, message) {
+  const fullPath = path.join(projectRoot, relativePath);
+  if (!fs.existsSync(fullPath)) {
+    missing.push(`✗ ${label}: ${relativePath} not found`);
+    return;
+  }
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  if (!validate(content)) {
+    checks.push(`✗ ${label}: ${message}`);
+    return;
+  }
+  checks.push(`✓ ${label}`);
+}
+
+function checkMissing(label, relativePath, message) {
+  const fullPath = path.join(projectRoot, relativePath);
+  if (fs.existsSync(fullPath)) {
+    checks.push(`✗ ${label}: ${relativePath} should be removed. ${message}`);
+    return;
+  }
+  checks.push(`✓ ${label}`);
+}
+
+function checkOptionalFile(label, relativePath, validate, message) {
+  const fullPath = path.join(projectRoot, relativePath);
+  if (!fs.existsSync(fullPath)) {
+    checks.push(`- ${label}: ${relativePath} not found (optional)`);
+    return;
+  }
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  if (!validate(content)) {
+    checks.push(`✗ ${label}: ${message}`);
+    return;
+  }
+  checks.push(`✓ ${label}`);
+}
+
+checkFile(
+  'middleware is configured',
+  'src/middleware.ts',
+  (content) => (content.includes('@gradial/aci/next/middleware') || content.includes('createGradialMiddleware'))
+    && !content.includes('|__r'),
+  'Expected src/middleware.ts to use @gradial/aci/next/middleware and not exclude __r; middleware blocks direct /__r requests.',
+);
+
+checkFile(
+  'catch-all page route exists',
+  'src/app/[[...slug]]/page.tsx',
+  (content) => content.includes('createPage') || content.includes('getRenderInput'),
+  'Expected catch-all page to use createPage() from the SDK.',
+);
+
+checkFile(
+  'public asset route exists',
+  'src/app/gradial/assets/[...path]/route.ts',
+  (content) => content.includes('@gradial/aci/next/asset-route'),
+  'Expected public asset route to re-export @gradial/aci/next/asset-route.',
+);
+
+checkMissing(
+  'legacy release-scoped asset route is removed',
+  'src/app/gradial/assets/[releaseId]/[...path]/route.ts',
+  'Use src/app/gradial/assets/[...path]/route.ts instead. Assets are now public, not release-scoped.',
+);
+
+checkMissing(
+  'no separate __r route folder',
+  'src/app/__r/[releaseId]/routes/[[...slug]]/page.tsx',
+  'The root catch-all handles release-scoped rewrites. Do not create a separate __r route folder.',
+);
+
+checkFile(
+  'next.config uses withAci',
+  'next.config.mjs',
+  (content) => content.includes('withAci'),
+  'Expected next.config.mjs to use withAci() from @gradial/aci/next.',
+);
+
+for (const line of checks) {
+  console.log(line);
+}
+for (const line of missing) {
+  console.log(line);
+}
+
+const failed = [...checks.filter((line) => line.startsWith('✗')), ...missing];
+if (failed.length > 0) {
+  console.error(`\n${failed.length} check(s) failed`);
+  process.exit(1);
+}
+console.log('\nAll route checks passed');

package/src/types/component.ts

@@ -0,0 +1,55 @@
+import type { ImageSlotContract } from './image.js';
+import type { BlockRefMeta } from './block-ref.js';
+import type { z } from 'zod';
+
+type InferContentProps<TSchema> = TSchema extends z.ZodType<infer T> ? T : Record<string, unknown>;
+
+export interface ComponentContractValidator<TProps = Record<string, unknown>> {
+  (context: ComponentValidationContext<TProps>): void | Promise<void>;
+}
+
+export interface ComponentValidationContext<TProps = Record<string, unknown>> {
+  component: string;
+  props: TProps;
+  blockId?: string;
+  path: readonly string[];
+  report(issue: ComponentValidationIssue): void;
+}
+
+export interface ComponentValidationIssue {
+  path?: readonly string[];
+  code?: string;
+  message: string;
+  severity?: 'error' | 'warning';
+}
+
+export interface ComponentDefinition<TId extends string = string, TSchema = unknown> {
+  id: TId;
+  displayName?: string;
+  props: TSchema;
+  imageSlots?: Record<string, ImageSlotContract>;
+  validate?: readonly ComponentContractValidator<InferContentProps<TSchema>>[];
+}
+
+export interface ComponentContract<TId extends string = string, TSchema = unknown> {
+  readonly id: TId;
+  readonly displayName?: string;
+  props: TSchema;
+  blockSlots?: Record<string, BlockRefMeta>;
+  imageSlots?: Record<string, ImageSlotContract>;
+  validate: readonly ComponentContractValidator<InferContentProps<TSchema>>[];
+}
+
+export type InferComponentProps<TContract> = TContract extends ComponentContract<string, infer TSchema>
+  ? InferContentProps<TSchema>
+  : Record<string, unknown>;
+
+export type ComponentContractID<TContract> = TContract extends ComponentContract<infer TId, unknown>
+  ? TId
+  : never;
+
+export type ComponentRegistry<TContracts extends Record<string, ComponentContract>> = {
+  readonly [K in keyof TContracts]: TContracts[K] & { readonly id: K & string };
+};
+
+export type { InferContentProps };

package/src/types/config.ts

@@ -0,0 +1,37 @@
+import type { RenderCapabilities } from './renderer.js';
+
+export interface Config {
+  version: '1';
+  siteId: string;
+  framework: 'astro' | 'next' | 'sveltekit' | 'custom';
+  source: {
+    root: string;
+    outDir?: string;
+    publicDir?: string;
+  };
+  componentRegistry: string;
+  dataRegistry?: string;
+  layoutRegistry: string;
+  capabilities: RenderCapabilities;
+  routes: RouteConfig;
+  dam?: DAMConfig;
+  externalDependencies?: ExternalDependency[];
+  rendererProtocol: 'http' | 'stdio-json';
+}
+
+export interface RouteConfig {
+  cmsManaged: string;
+  frameworkOwned?: string[];
+}
+
+export interface ExternalDependency {
+  name: string;
+  host: string;
+  kind?: 'api' | 'client-script';
+  description?: string;
+  cacheTTL?: number;
+}
+
+export interface DAMConfig {
+  autoApproveUploads?: boolean;
+}

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>>;
+}

package/src/types/image.ts

@@ -22,15 +22,16 @@ export interface ImageSource {
 // Image — DAM-backed image asset with compiler-resolved derivatives
 //
 // Content authors write an asset reference: { "$type": "dam.assetRef", ... }
-// The compiler resolves it to this Image value based on the asset's media type.
+// or for static files: { "$type": "static.assetRef", "src": "/path" }
+// The compiler resolves both to this Image value.
 // ---------------------------------------------------------------------------
 
 export interface Image {
   /** Discriminator — always 'gradial.image'. */
   $type: 'gradial.image';
-  /** DAM asset identifier. */
+  /** DAM asset identifier (or "static:<path>" for non-DAM assets). */
   assetId: string;
-  /** DAM version identifier. */
+  /** DAM version identifier (or "static" for non-DAM assets). */
   versionId: string;
   /** Accessible description of the image content. */
   alt: string;

package/src/types/index.ts

@@ -0,0 +1,11 @@
+export * from './config.js';
+export * from './component.js';
+export * from './data.js';
+export * from './layout.js';
+export * from './page.js';
+export * from './rich-text.js';
+export * from './renderer.js';
+export * from './render-mode.js';
+export * from './image.js';
+export * from './video.js';
+export * from './media.js';

package/src/types/layout.ts

@@ -0,0 +1,29 @@
+import type { FragmentRefNode } from './page.js';
+
+export interface LayoutSlot {
+  name: string;
+  required: boolean;
+}
+
+/** Default content for non-required layout slots, keyed by slot name. */
+export type LayoutDefaults = Record<string, FragmentRefNode[]>;
+
+export interface LayoutDefinition {
+  name: string;
+  slots: LayoutSlot[];
+  /** Default fragment references for slots not provided by the page. */
+  defaults?: LayoutDefaults;
+}
+
+export interface LayoutContract {
+  name: string;
+  slots: LayoutSlot[];
+  defaults?: LayoutDefaults;
+}
+
+/** A compiled layout file as stored on disk. */
+export interface CompiledLayout {
+  name: string;
+  slots: LayoutSlot[];
+  defaults: LayoutDefaults;
+}

package/src/types/link.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Link — internal or external hyperlink target
+// ---------------------------------------------------------------------------
+
+export type LinkTarget = '_self' | '_blank' | '_parent' | '_top';
+
+export interface Link {
+  href: string;
+  target?: LinkTarget;
+  title?: string;
+  rel?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Zod schema
+// ---------------------------------------------------------------------------
+
+export const LinkSchema = z.object({
+  href: z.string().min(1),
+  target: z.enum(['_self', '_blank', '_parent', '_top']).optional(),
+  title: z.string().optional(),
+  rel: z.string().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Link resolver — turns a reference string into a Link object
+//
+// Supported reference schemes:
+//   aci:page:{slug}    → resolved by the consumer (e.g. Next.js/Astro router)
+//   aci:external:{url} → external URL
+//   {url}              → literal URL
+// ---------------------------------------------------------------------------
+
+export interface LinkResolverContext {
+  /** Resolved path for an aci:page:{slug} reference, if found. */
+  resolvePageSlug?: (slug: string) => string | undefined;
+}
+
+export function resolveLink(
+  reference: string | Link,
+  ctx: LinkResolverContext = {},
+): Link {
+  if (typeof reference !== 'string') return reference;
+
+  if (reference.startsWith('aci:external:')) {
+    return { href: reference.slice('aci:external:'.length), target: '_blank' };
+  }
+
+  if (reference.startsWith('aci:page:')) {
+    const slug = reference.slice('aci:page:'.length);
+    const path = ctx.resolvePageSlug?.(slug);
+    return { href: path ?? `/${slug}` };
+  }
+
+  return { href: reference };
+}
+
+/**
+ * Resolve a Link object to its final href string.
+ * An optional resolver can perform async or domain-specific resolution.
+ */
+export function resolveHref(
+  link: Link,
+  resolver?: (link: Link) => string | Promise<string>,
+): string | Promise<string> {
+  if (resolver) {
+    return resolver(link);
+  }
+  return link.href;
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers — consumed by React, Astro, and Svelte components
+// ---------------------------------------------------------------------------
+
+/**
+ * Throw if the href uses an unsafe protocol (javascript:, data:, vbscript:).
+ */
+export function assertSafeHref(href: string): void {
+  const protocol = href.split(':')[0].toLowerCase();
+  if (protocol === 'javascript' || protocol === 'data' || protocol === 'vbscript') {
+    throw new Error(`unsafe Link protocol: ${protocol}`);
+  }
+}
+
+/**
+ * Normalize the rel attribute for a Link.
+ * Adds noopener noreferrer for target="_blank" automatically.
+ */
+export function normalizeLinkRel(link: Link): string | undefined {
+  if (link.target !== '_blank') {
+    return link.rel;
+  }
+  const rel = new Set((link.rel ?? '').split(/\s+/).filter(Boolean));
+  rel.add('noopener');
+  rel.add('noreferrer');
+  return [...rel].join(' ');
+}

package/src/types/media.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { ImageSchema, type Image } from './image.js';
+import { VideoSchema, type Video } from './video.js';
+
+// ---------------------------------------------------------------------------
+// Asset — union of all compiler-resolved asset types
+//
+// Content authors write either:
+//   { "$type": "dam.assetRef", "assetId": "..." }    — resolved via DAM
+//   { "$type": "static.assetRef", "src": "/path" }   — resolved as-is
+//
+// The compiler normalizes both into Image or Video values.
+// ---------------------------------------------------------------------------
+
+/** Discriminated union of all compiler-resolved asset types. */
+export type Asset = Image | Video;
+
+/** Zod schema for a resolved asset value. */
+export const AssetSchema = z.union([ImageSchema, VideoSchema]);
+
+/** Runtime guard: value is a resolved asset. */
+export function isAsset(value: unknown): value is Asset {
+  return ImageSchema.safeParse(value).success || VideoSchema.safeParse(value).success;
+}
+
+/** Runtime guard: value is a resolved image asset. */
+export function isImage(value: unknown): value is Image {
+  return ImageSchema.safeParse(value).success;
+}
+
+/** Runtime guard: value is a resolved video asset. */
+export function isVideo(value: unknown): value is Video {
+  return VideoSchema.safeParse(value).success;
+}

package/src/types/page.ts

@@ -0,0 +1,47 @@
+import type { VaryDimension } from './render-mode.js';
+
+export interface PageDocument {
+  path: string;
+  layout: string;
+  locale: string;
+  metadata: PageMetadata;
+  regions: Record<string, RegionNode>;
+}
+
+export interface PageMetadata {
+  title: string;
+  description?: string;
+  openGraph?: Record<string, string>;
+  canonicalUrl?: string;
+  alternateLocales?: { locale: string; path: string }[];
+  customHead?: string[];
+}
+
+export interface RegionNode {
+  kind: 'region';
+  name: string;
+  children: Array<BlockNode | FragmentRefNode>;
+}
+
+export interface BlockNode {
+  kind: 'block';
+  id: string;
+  component: string;
+  props: Record<string, unknown>;
+  renderHints: BlockRenderHints;
+  contentRef?: string;
+}
+
+export interface BlockRenderHints {
+  canStatic: boolean;
+  needsSSR: boolean;
+  isIsland: boolean;
+  islandMode?: 'ssr' | 'client';
+  varyDimensions?: VaryDimension[];
+}
+
+export interface FragmentRefNode {
+  kind: 'fragment-ref';
+  fragmentId: string;
+  inline: boolean;
+}

package/src/types/render-mode.ts

@@ -0,0 +1,10 @@
+export type IslandMode = 'ssr' | 'client';
+
+export type VaryDimension =
+  | 'geo:country'
+  | 'geo:region'
+  | 'geo:city'
+  | `cookie:${string}`
+  | `header:${string}`
+  | 'locale'
+  | `query:${string}`;