@gradial/aci 0.1.2 → 0.1.4

package/README.md

@@ -106,3 +106,22 @@ npm publish --access public
 
 The package includes a `prepack` script that builds `dist` before packing or
 publishing.
+
+## Verify the Published Shape Locally
+
+Before publishing, inspect the exact tarball npm will upload. This catches
+package `files` mistakes where local source imports work from the repo but fail
+after npm filters the packed files.
+
+From `packages/sdk`:
+
+```bash
+tmpdir="$(mktemp -d /tmp/gradial-aci-pack.XXXXXX)"
+filename="$(npm pack --pack-destination "$tmpdir" | tail -n 1)"
+tar -tzf "$tmpdir/$filename" | sort | rg '^(package/src/cli/|package/src/types/|package/dist/types/)'
+echo "tarball=$tmpdir/$filename"
+```
+
+If a shipped source CLI imports another source file, make sure both paths appear
+in the tarball. For example, `src/cli/compile-registry.mjs` imports
+`src/types/image.ts`, so both files must be included by `package.json#files`.

package/bin/aci.js

@@ -46,7 +46,7 @@ function resolvePackagedBinary() {
 }
 
 function resolveWorkspaceBinary() {
-  const binaryPath = resolve(shimDir, '..', '..', 'packages', `cli-${platformKey}`, 'bin', binName);
+  const binaryPath = resolve(repoRoot, 'packages', `cli-${platformKey}`, 'bin', binName);
 
   return existsSync(binaryPath) ? binaryPath : null;
 }

package/dist/astro/index.d.ts

@@ -1,3 +1,4 @@
+import type { RenderInput } from '../content/types.js';
 import { type GradialContentWatchOptions } from '../dev/index.js';
 interface AstroConfigSetupParams {
     injectScript(stage: 'head-inline' | 'page' | 'page-ssr', content: string): void;
@@ -31,6 +32,7 @@ export declare function getGradialStaticPaths(): Promise<Array<{
         slug?: string;
     };
 }>>;
+export declare function getPageRuntimeRenderInput(request: Request): RenderInput | null;
 export interface GradialAstroOptions extends GradialContentWatchOptions {
     /** Path to compiled content root. Defaults to ACI_CONTENT_ROOT env or '.aci/compiled' */
     compiledRoot?: string;

package/dist/astro/index.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
 import { gradialContentWatchPlugin, gradialDamAssetPlugin, devRefreshPort, devRefreshScript, } from '../dev/index.js';
 // ---------------------------------------------------------------------------
 // Static paths helper — for Astro SSG
@@ -27,6 +28,9 @@ export async function getGradialStaticPaths() {
         };
     });
 }
+export function getPageRuntimeRenderInput(request) {
+    return getPendingRenderInputFromHeaders(request.headers);
+}
 export function gradialAstro(options = {}) {
     return {
         name: 'gradial-astro',

package/dist/next/server.d.ts

@@ -1,4 +1,5 @@
 import { FragmentNotFoundError, PageNotFoundError } from '../content/provider.js';
+import type { RenderInput } from '../content/types.js';
 export { FragmentNotFoundError, PageNotFoundError };
 export interface GradialFetchConfig {
     siteId?: string;
@@ -25,9 +26,11 @@ export interface GradialSiteConfig {
     defaultLocale?: string;
 }
 export declare function getPage<T = unknown>(route?: string, config?: GradialFetchConfig): Promise<T>;
+export declare function getSiteConfig<T extends GradialSiteConfig = GradialSiteConfig>(config?: GradialFetchConfig): Promise<T>;
 export declare function getFragment<T = unknown>(name: string, config?: GradialFetchConfig): Promise<T>;
 export declare function getRoutes(config?: GradialFetchConfig): Promise<string[]>;
 export declare function getRenderInput<TPage, TSite extends GradialSiteConfig = GradialSiteConfig>(route?: string, config?: GradialFetchConfig): Promise<GradialRenderInput<TPage, TSite>>;
+export declare function getPageRuntimeRenderInput(): Promise<RenderInput | null>;
 export declare function routeFromNextParams(params?: Promise<{
     slug?: string[];
 }> | {

package/dist/next/server.js

@@ -1,24 +1,39 @@
 import { headers } from 'next/headers';
 import { FragmentNotFoundError, PageNotFoundError, } from '../content/provider.js';
 import { S3ContentProvider } from '../providers/s3.js';
+import { GRADIAL_RENDER_INPUT_HEADER, getPendingRenderInput } from '../runtime/page.js';
 import { getUncachedEdgeConfigValue } from './edge-config.js';
 const RELEASE_HEADER = 'x-gradial-release-id';
 export { FragmentNotFoundError, PageNotFoundError };
 export async function getPage(route = '', config = {}) {
-    const provider = await resolveProvider(config);
+    const runtimeInput = await getPageRuntimeRenderInput();
+    if (runtimeInput)
+        return runtimeInput.page;
+    const provider = await resolveProviderWithFallback(config);
     return await provider.getPage(route);
 }
+export async function getSiteConfig(config = {}) {
+    const runtimeInput = await getPageRuntimeRenderInput();
+    if (runtimeInput)
+        return runtimeInput.siteConfig;
+    const provider = await resolveProviderWithFallback(config);
+    return await provider.getSiteConfig();
+}
 export async function getFragment(name, config = {}) {
-    const provider = await resolveProvider(config);
+    const provider = await resolveProviderWithFallback(config);
     return await provider.getFragment(name);
 }
 export async function getRoutes(config = {}) {
-    const provider = await resolveProvider(config);
+    const provider = await resolveProviderWithFallback(config);
     const routes = await provider.listRoutes();
     return routes.map((route) => route.path).sort();
 }
 export async function getRenderInput(route = '/', config = {}) {
-    const provider = await resolveProvider(config);
+    const runtimeInput = await getPageRuntimeRenderInput();
+    if (runtimeInput) {
+        return runtimeInput;
+    }
+    const provider = await resolveProviderWithFallback(config);
     const [page, siteConfig] = await Promise.all([
         provider.getPage(route),
         provider.getSiteConfig(),
@@ -31,6 +46,15 @@ export async function getRenderInput(route = '/', config = {}) {
         page,
     };
 }
+export async function getPageRuntimeRenderInput() {
+    try {
+        const current = await headers();
+        return getPendingRenderInput(current.get(GRADIAL_RENDER_INPUT_HEADER));
+    }
+    catch {
+        return null;
+    }
+}
 export async function routeFromNextParams(params) {
     if (!params)
         return '/';
@@ -125,6 +149,13 @@ async function resolveProvider(config) {
         endpoint: config.endpoint,
     });
 }
+async function resolveProviderWithFallback(config) {
+    if (process.env.ACI_CONTENT_PROVIDER === 'file') {
+        const { FileContentProvider } = await import('../providers/file.js');
+        return new FileContentProvider();
+    }
+    return await resolveProvider(config);
+}
 async function releaseIdFromHeaders() {
     try {
         const current = await headers();

package/dist/runtime/page.d.ts

@@ -0,0 +1,8 @@
+import type { RenderInput } from '../content/types.js';
+export declare const GRADIAL_RENDER_INPUT_HEADER = "x-gradial-render-input-id";
+export declare const GRADIAL_PENDING_RENDER_INPUTS_KEY = "__GRADIAL_PENDING_RENDER_INPUTS__";
+export declare function pendingRenderInputs(): Map<string, RenderInput>;
+export declare function setPendingRenderInput(id: string, input: RenderInput): void;
+export declare function deletePendingRenderInput(id: string): void;
+export declare function getPendingRenderInput(id: string | null | undefined): RenderInput | null;
+export declare function getPendingRenderInputFromHeaders(headers: Headers): RenderInput | null;

package/dist/runtime/page.js

@@ -0,0 +1,21 @@
+export const GRADIAL_RENDER_INPUT_HEADER = 'x-gradial-render-input-id';
+export const GRADIAL_PENDING_RENDER_INPUTS_KEY = '__GRADIAL_PENDING_RENDER_INPUTS__';
+export function pendingRenderInputs() {
+    const global = globalThis;
+    global[GRADIAL_PENDING_RENDER_INPUTS_KEY] ??= new Map();
+    return global[GRADIAL_PENDING_RENDER_INPUTS_KEY];
+}
+export function setPendingRenderInput(id, input) {
+    pendingRenderInputs().set(id, input);
+}
+export function deletePendingRenderInput(id) {
+    pendingRenderInputs().delete(id);
+}
+export function getPendingRenderInput(id) {
+    if (!id)
+        return null;
+    return pendingRenderInputs().get(id) ?? null;
+}
+export function getPendingRenderInputFromHeaders(headers) {
+    return getPendingRenderInput(headers.get(GRADIAL_RENDER_INPUT_HEADER));
+}

package/dist/sveltekit/index.d.ts

@@ -1,4 +1,5 @@
 import { type GradialContentWatchOptions, type VitePluginLike } from '../dev/index.js';
+import type { RenderInput } from '../content/types.js';
 /**
  * Generates prerender entries from the compiled content manifest for SvelteKit.
  *
@@ -15,4 +16,7 @@ import { type GradialContentWatchOptions, type VitePluginLike } from '../dev/ind
  * ```
  */
 export declare function gradialEntries(): Promise<string[]>;
+export declare function getPageRuntimeRenderInput(event: {
+    request: Request;
+}): RenderInput | null;
 export declare function gradialSvelteKit(options?: GradialContentWatchOptions): VitePluginLike;

package/dist/sveltekit/index.js

@@ -1,4 +1,5 @@
 import { gradialContentWatchPlugin, gradialDamAssetPlugin, devRefreshPort, devRefreshScriptTag, } from '../dev/index.js';
+import { getPendingRenderInputFromHeaders } from '../runtime/page.js';
 // ---------------------------------------------------------------------------
 // Entries helper — for SvelteKit SSG prerendering
 // ---------------------------------------------------------------------------
@@ -27,6 +28,9 @@ export async function gradialEntries() {
         return normalized === '/' ? '/' : `/${normalized.replace(/^\/|\/$/g, '')}/`;
     });
 }
+export function getPageRuntimeRenderInput(event) {
+    return getPendingRenderInputFromHeaders(event.request.headers);
+}
 // ---------------------------------------------------------------------------
 // SvelteKit Vite plugin
 // ---------------------------------------------------------------------------

package/dist/types/config.d.ts

@@ -6,6 +6,7 @@ export interface BareMetalConfig {
     source: {
         root: string;
         outDir?: string;
+        publicDir?: string;
     };
     componentRegistry: string;
     layoutRegistry: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -9,6 +9,7 @@
     "bin/aci.js",
     "bin/aci",
     "src/cli/*.mjs",
+    "src/types/*.ts",
     "README.md"
   ],
   "bin": {
@@ -58,6 +59,10 @@
       "types": "./dist/assets/index.d.ts",
       "import": "./dist/assets/index.js"
     },
+    "./runtime": {
+      "types": "./dist/runtime/page.d.ts",
+      "import": "./dist/runtime/page.js"
+    },
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js"
@@ -128,13 +133,13 @@
     }
   },
   "devDependencies": {
-    "@vercel/edge-config": "^1.4.3",
     "@types/node": "^24.10.1",
     "@types/react": "^19.0.0",
+    "@vercel/edge-config": "^1.4.3",
     "next": "^15.5.6",
     "react": "^19.0.0",
     "tsx": "^4.20.0",
-    "typescript": "^5.9.0",
+    "typescript": "^5.9.3",
     "zod": "^4.0.0"
   }
 }

package/src/types/component.ts

@@ -0,0 +1,59 @@
+import type { IslandMode, VaryDimension } from './render-mode.js';
+import type { ImageSlotContract } from './image.js';
+import type { z } from 'zod';
+
+export interface ComponentRenderModes {
+  canStatic: boolean;
+  canSSR: boolean;
+  canClientIsland: boolean;
+}
+
+/**
+ * A CMS-registered component — sync or async (server components).
+ * Accepts content props derived from the Zod schema.
+ */
+type CmsComponentFn<TProps = any> =
+  | ((props: TProps) => import('react').ReactElement | null)
+  | ((props: TProps) => Promise<import('react').ReactElement | null>);
+
+/**
+ * Infers the props type from a schema.
+ * If TSchema is a Zod type, returns z.infer<TSchema>.
+ * Otherwise returns Record<string, unknown>.
+ */
+type InferContentProps<TSchema> = TSchema extends z.ZodType<infer T> ? T : Record<string, unknown>;
+
+export interface ComponentDefinition<TSchema = unknown> {
+  name: string;
+  /**
+   * The React component that renders this CMS block.
+   * Accepts at least the schema-derived props, but may accept additional
+   * composition params (className, etc.) passed by parent sections.
+   */
+  component?: CmsComponentFn<any>;
+  schema: TSchema;
+  renderModes?: ComponentRenderModes;
+  render?: ComponentRenderModes;
+  defaultIslandMode?: IslandMode;
+  varyDimensions?: VaryDimension[];
+  vary?: VaryDimension[];
+  imageSlots?: Record<string, ImageSlotContract>;
+}
+
+export interface ComponentContract<TSchema = unknown> {
+  name: string;
+  component?: CmsComponentFn<any>;
+  schema: TSchema;
+  renderModes: ComponentRenderModes;
+  render: ComponentRenderModes;
+  defaultIslandMode?: IslandMode;
+  varyDimensions?: VaryDimension[];
+  vary?: VaryDimension[];
+  imageSlots?: Record<string, ImageSlotContract>;
+}
+
+export type InferComponentProps<TContract> = TContract extends ComponentContract<infer TSchema>
+  ? InferContentProps<TSchema>
+  : Record<string, unknown>;
+
+export type { CmsComponentFn, InferContentProps };

package/src/types/config.ts

@@ -0,0 +1,37 @@
+import type { RenderCapabilities } from './renderer.js';
+
+export interface BareMetalConfig {
+  version: '1';
+  siteId: string;
+  framework: 'astro' | 'next' | 'sveltekit' | 'custom';
+  source: {
+    root: string;
+    outDir?: string;
+    publicDir?: string;
+  };
+  componentRegistry: string;
+  layoutRegistry: string;
+  rendererEntry: 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/image.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+
+export interface ImageSource {
+  src: string;
+  width: number;
+  height: number;
+  type: string;
+}
+
+export interface PictureSource {
+  media?: string;
+  type: string;
+  srcset: string;
+  sizes?: string;
+}
+
+export interface GradialImage {
+  $type: 'gradial.image';
+  assetId: string;
+  versionId: string;
+  alt: string;
+  fallback: ImageSource;
+  sources: PictureSource[];
+}
+
+export interface ImageSlotContract {
+  outputs: SlotOutput[];
+  formats: string[];
+  sizes: string;
+}
+
+export interface SlotOutput {
+  aspectRatio: string;
+  widths: number[];
+  media?: string;
+}
+
+export const GradialImageSchema = z.object({
+  $type: z.literal('gradial.image'),
+  assetId: z.string().min(1),
+  versionId: z.string().min(1),
+  alt: z.string(),
+  fallback: z.object({
+    src: z.string().min(1),
+    width: z.number().int().nonnegative(),
+    height: z.number().int().nonnegative(),
+    type: z.string().min(1),
+  }),
+  sources: z.array(z.object({
+    media: z.string().optional(),
+    type: z.string().min(1),
+    srcset: z.string().min(1),
+    sizes: z.string().optional(),
+  })).nullable().default([]),
+});
+
+export type ImageHTMLAttributes = Record<string, string | number | boolean | undefined | null>;
+
+export function renderImageHTML(image: GradialImage, attrs: ImageHTMLAttributes = {}): string {
+  const imgAttrs = renderAttrs({
+    ...attrs,
+    src: image.fallback.src,
+    alt: image.alt,
+    width: image.fallback.width > 0 ? image.fallback.width : undefined,
+    height: image.fallback.height > 0 ? image.fallback.height : undefined,
+  });
+  const img = `<img${imgAttrs}>`;
+  if (!image.sources.length) {
+    return img;
+  }
+  const sources = image.sources.map((source) => `<source${renderAttrs({
+    media: source.media,
+    type: source.type,
+    srcset: source.srcset,
+    sizes: source.sizes,
+  })}>`).join('');
+  return `<picture>${sources}${img}</picture>`;
+}
+
+function renderAttrs(attrs: ImageHTMLAttributes): string {
+  const rendered = Object.entries(attrs)
+    .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: string): string {
+  return name.replace(/[^A-Za-z0-9_:-]/g, '');
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/src/types/index.ts

@@ -0,0 +1,9 @@
+export * from './config.js';
+export * from './component.js';
+export * from './layout.js';
+export * from './page.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/media.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { GradialImageSchema, renderImageHTML, type GradialImage } from './image.js';
+import { GradialVideoSchema, type GradialVideo } from './video.js';
+
+// ---------------------------------------------------------------------------
+// GradialAsset — union of all DAM-backed asset types
+//
+// Content authors write: { "$type": "dam.assetRef", "assetId": "..." }
+// The compiler resolves this to a GradialImage or GradialVideo based on
+// the asset's media type in the DAM.
+// ---------------------------------------------------------------------------
+
+/** Discriminated union of all compiler-resolved asset types. */
+export type GradialAsset = GradialImage | GradialVideo;
+
+// ---------------------------------------------------------------------------
+// Zod schema — discriminated on $type
+// ---------------------------------------------------------------------------
+
+export const GradialAssetSchema = z.discriminatedUnion('$type', [
+  GradialImageSchema,
+  GradialVideoSchema,
+]);
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+export function isGradialImage(value: unknown): value is GradialImage {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as Record<string, unknown>).$type === 'gradial.image'
+  );
+}
+
+export function isGradialVideo(value: unknown): value is GradialVideo {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as Record<string, unknown>).$type === 'gradial.video'
+  );
+}
+
+export function isGradialAsset(value: unknown): value is GradialAsset {
+  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: GradialVideo,
+  attrs: Record<string, string | number | boolean | undefined | null> = {},
+): string {
+  const posterSrc = video.poster?.fallback.src;
+  const attrPairs: Array<[string, string | number | boolean | undefined | null]> = [
+    ...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: GradialAsset,
+  attrs: Record<string, string | number | boolean | undefined | null> = {},
+): string {
+  if (asset.$type === 'gradial.image') {
+    return renderImageHTML(asset, attrs);
+  }
+  return renderVideoHTML(asset, attrs);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function renderAttrs(
+  pairs: Array<[string, string | number | boolean | undefined | null]>,
+): string {
+  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: string): string {
+  return name.replace(/[^A-Za-z0-9_:-]/g, '');
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/src/types/page.ts

@@ -0,0 +1,48 @@
+import type { RenderMode, VaryDimension } from './render-mode.js';
+
+export interface PageDocument {
+  path: string;
+  layout: string;
+  locale: string;
+  metadata: PageMetadata;
+  regions: Record<string, RegionNode>;
+  renderMode: RenderMode;
+}
+
+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,18 @@
+export type RenderMode =
+  | 'static'
+  | 'static-with-fragments'
+  | 'prerender-on-demand'
+  | 'ssr-page'
+  | 'ssr-island'
+  | 'client-island';
+
+export type IslandMode = 'ssr' | 'client';
+
+export type VaryDimension =
+  | 'geo:country'
+  | 'geo:region'
+  | 'geo:city'
+  | `cookie:${string}`
+  | `header:${string}`
+  | 'locale'
+  | `query:${string}`;

package/src/types/renderer.ts

@@ -0,0 +1,83 @@
+import type { PageDocument } from './page.js';
+import type { VaryDimension } from './render-mode.js';
+
+export interface RenderCapabilities {
+  staticRender: boolean;
+  ssr: boolean;
+  ssrIslands: boolean;
+  clientIslands: boolean;
+  fragmentRender: boolean;
+}
+
+export interface GradialRenderer {
+  renderPage(request: RenderPageRequest): Promise<RenderPageResult>;
+  renderFragment?(request: RenderFragmentRequest): Promise<RenderResult>;
+  renderIsland?(request: RenderIslandRequest): Promise<RenderResult>;
+}
+
+export interface RenderPageRequest {
+  page: PageDocument;
+  requestContext?: RequestContext;
+  release: ReleaseContext;
+}
+
+export interface RequestContext {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+  geo?: GeoContext;
+}
+
+export interface GeoContext {
+  country?: string;
+  region?: string;
+  city?: string;
+}
+
+export interface ReleaseContext {
+  releaseId: string;
+  codeDigest: string;
+  contentSnapshotId: string;
+  assetUrl(logicalPath: string): string;
+}
+
+export interface RenderFragmentRequest {
+  fragmentId: string;
+  content: unknown;
+  release: ReleaseContext;
+}
+
+export interface RenderIslandRequest {
+  islandId: string;
+  component: string;
+  props: Record<string, unknown>;
+  requestContext: RequestContext;
+  release: ReleaseContext;
+}
+
+export interface RenderResult {
+  html: string;
+  status?: number;
+  headers?: Record<string, string>;
+  cachePolicy?: CachePolicy;
+}
+
+export interface RenderPageResult extends RenderResult {
+  islands?: IslandDescriptor[];
+}
+
+export interface IslandDescriptor {
+  islandId: string;
+  component: string;
+  props: Record<string, unknown>;
+  mode: 'ssr' | 'client';
+  varyDimensions?: VaryDimension[];
+}
+
+export interface CachePolicy {
+  scope: 'public' | 'private' | 'no-store';
+  ttl?: number;
+  staleWhileRevalidate?: number;
+  tags?: string[];
+}

package/src/types/video.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { GradialImageSchema, type GradialImage } from './image.js';
+
+// ---------------------------------------------------------------------------
+// Video source variant (format alternatives)
+// ---------------------------------------------------------------------------
+
+export interface VideoSource {
+  src: string;
+  type: string; // MIME type: video/mp4, video/webm
+}
+
+// ---------------------------------------------------------------------------
+// GradialVideo — DAM-backed video asset with compiler-resolved derivatives
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// 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(),
+});