@gradial/aci 0.1.2 → 0.1.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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": {

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,36 @@
+import type { RenderCapabilities } from './renderer.js';
+
+export interface BareMetalConfig {
+  version: '1';
+  siteId: string;
+  framework: 'astro' | 'next' | 'sveltekit' | 'custom';
+  source: {
+    root: string;
+    outDir?: 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(),
+});