@gradial/aci 0.1.18 → 0.1.20-preview.1

package/README.md

@@ -5,9 +5,31 @@ installing `@gradial/aci`, Zod 4, and TypeScript tooling. The
 SDK exposes component and layout helpers, renderer types, compiler tooling,
 content provider helpers, and framework-specific subpaths from one package.
 
+## Getting Started
+
+The fastest way to create a new ACI site is via the scaffolding script:
+
+```bash
+pnpm exec tsx scripts/create-site.ts --framework astro --name my-site --dir ./my-site
+cd my-site
+pnpm run dev
+```
+
+Available frameworks: `astro`, `nextjs`, `sveltekit`.
+
+Generated starters include:
+- `.aci/docs/` — Understanding ACI, running, and testing guides
+- `.aci/guides/` — Component development, design system, content authoring
+- `.aci/migration/` — Migrating existing sites to ACI
+- Design system tokens, ESLint rules, and demo content
+
+See the [templates directory](templates/) for the canonical starter source.
+
+## Installation
+
 ```bash
-npm install @gradial/aci zod@^4
-npm install -D typescript tsx
+pnpm add @gradial/aci zod@^4
+pnpm add -D typescript tsx
 ```
 
 Common imports:
@@ -56,7 +78,6 @@ export const heroContract = defineComponentContract({
     headline: z.string(),
     image: GradialImageSchema,
   }),
-  renderModes: { canStatic: true, canSSR: true, canClientIsland: false },
 });
 
 export type HeroProps = z.infer<typeof heroContract.schema>;
@@ -85,7 +106,6 @@ const content = new FixtureContentProvider({
       $type: 'page',
       status: 'published',
       layout: 'marketing',
-      renderMode: 'static',
       metadata: { title: 'Test Home' },
       regions: { main: [] }
     }
@@ -101,7 +121,7 @@ Use this in unit tests when you want the same provider API as
 Publish from this package directory:
 
 ```bash
-npm publish --access public
+pnpm publish --access public
 ```
 
 The package includes a `prepack` script that builds `dist` before packing or
@@ -109,15 +129,15 @@ publishing.
 
 ## Verify the Published Shape Locally
 
-Before publishing, inspect the exact tarball npm will upload. This catches
+Before publishing, inspect the exact tarball pnpm will upload. This catches
 package `files` mistakes where local source imports work from the repo but fail
-after npm filters the packed files.
+after pnpm 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)"
+filename="$(pnpm 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"
 ```

package/dist/astro/index.d.ts

@@ -33,9 +33,11 @@ export declare function getGradialStaticPaths(): Promise<Array<{
     };
 }>>;
 export declare function getPageRuntimeRenderInput(request: Request): RenderInput | null;
+export { createRegistry, registryLookup } from '../registry.js';
+export type { Registry, RegistryEntry, AnyComponent } from '../registry.js';
+export { getPreviewMode, createPreviewBannerHTML, createPreviewCookies, type PreviewContext, type PreviewCookie, } from './preview.js';
 export interface GradialAstroOptions extends GradialContentWatchOptions {
     /** Path to compiled content root. Defaults to ACI_CONTENT_ROOT env or '.aci/compiled' */
     compiledRoot?: string;
 }
-export declare function gradialAstro(options?: GradialAstroOptions): AstroIntegrationLike;
-export {};
+export declare function withGradialAci(options?: GradialAstroOptions): AstroIntegrationLike;

package/dist/astro/index.js

@@ -31,7 +31,15 @@ export async function getGradialStaticPaths() {
 export function getPageRuntimeRenderInput(request) {
     return getPendingRenderInputFromHeaders(request.headers);
 }
-export function gradialAstro(options = {}) {
+// ---------------------------------------------------------------------------
+// Registry helpers
+// ---------------------------------------------------------------------------
+export { createRegistry, registryLookup } from '../registry.js';
+// ---------------------------------------------------------------------------
+// Preview support
+// ---------------------------------------------------------------------------
+export { getPreviewMode, createPreviewBannerHTML, createPreviewCookies, } from './preview.js';
+export function withGradialAci(options = {}) {
     return {
         name: 'gradial-astro',
         hooks: {

package/dist/astro/preview.d.ts

@@ -0,0 +1,5 @@
+import { type PreviewContext, type PreviewCookie } from '../preview/core.js';
+export declare function getPreviewMode(request: Request, siteId: string): Promise<PreviewContext>;
+export declare function createPreviewBannerHTML(releaseId: string): string;
+export declare function createPreviewCookies(token: string, releaseId: string): PreviewCookie[];
+export type { PreviewContext, PreviewCookie };

package/dist/astro/preview.js

@@ -0,0 +1,33 @@
+import { extractPreviewToken, resolvePreviewContext, createPreviewBannerHTML as coreCreatePreviewBannerHTML, createPreviewCookies as coreCreatePreviewCookies, previewSignKey, } from '../preview/core.js';
+export async function getPreviewMode(request, siteId) {
+    const url = new URL(request.url);
+    const token = extractPreviewToken({
+        query: url.searchParams,
+        cookies: parseCookieHeader(request.headers.get('cookie') || ''),
+        authorization: request.headers.get('authorization') || undefined,
+    });
+    if (!token)
+        return { isPreview: false };
+    return resolvePreviewContext({ token, siteId, signKey: previewSignKey() });
+}
+export function createPreviewBannerHTML(releaseId) {
+    return coreCreatePreviewBannerHTML(releaseId);
+}
+export function createPreviewCookies(token, releaseId) {
+    return coreCreatePreviewCookies(token, releaseId);
+}
+function parseCookieHeader(header) {
+    const cookies = new Map();
+    for (const part of header.split(';')) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const idx = trimmed.indexOf('=');
+        if (idx < 0)
+            continue;
+        const name = trimmed.slice(0, idx).trim();
+        const value = trimmed.slice(idx + 1).trim();
+        cookies.set(name, decodeURIComponent(value));
+    }
+    return cookies;
+}

package/dist/content/index.d.ts

@@ -2,3 +2,4 @@ export * from './provider.js';
 export * from './routes.js';
 export * from './types.js';
 export * from './cache.js';
+export * from './resolve-slots.js';

package/dist/content/index.js

@@ -2,3 +2,4 @@ export * from './provider.js';
 export * from './routes.js';
 export * from './types.js';
 export * from './cache.js';
+export * from './resolve-slots.js';

package/dist/content/provider.d.ts

@@ -12,17 +12,33 @@ export interface FragmentEntry {
     digest: string;
     fragmentRefs?: string[];
 }
+export interface LayoutEntry {
+    name: string;
+    slots: LayoutSlot[];
+    defaults?: Record<string, FragmentRef[]>;
+}
+export interface LayoutSlot {
+    name: string;
+    required: boolean;
+}
+export interface FragmentRef {
+    kind: string;
+    fragmentId: string;
+    inline: boolean;
+}
 export interface CompiledManifest {
     manifestVersion: string;
     buildDigest: string;
     siteConfigRef: string;
     routes: Record<string, RouteEntry>;
     fragments: Record<string, FragmentEntry>;
+    layouts?: Record<string, LayoutEntry>;
 }
 export interface ContentProvider {
     getSiteConfig<T = unknown>(): Promise<T>;
     getPage<T = unknown>(route: string): Promise<T>;
     getFragment<T = unknown>(id: string): Promise<T>;
+    getLayout<T = unknown>(name: string): Promise<T>;
     listRoutes(): Promise<RouteEntry[]>;
 }
 export declare class PageNotFoundError extends Error {
@@ -31,6 +47,9 @@ export declare class PageNotFoundError extends Error {
 export declare class FragmentNotFoundError extends Error {
     constructor(id: string, cause?: unknown);
 }
+export declare class LayoutNotFoundError extends Error {
+    constructor(name: string, cause?: unknown);
+}
 export interface RenderInputOptions {
     domain?: string;
     locale?: string;

package/dist/content/provider.js

@@ -16,6 +16,13 @@ export class FragmentNotFoundError extends Error {
         this.cause = cause;
     }
 }
+export class LayoutNotFoundError extends Error {
+    constructor(name, cause) {
+        super(`Layout not found: ${name}`);
+        this.name = 'LayoutNotFoundError';
+        this.cause = cause;
+    }
+}
 import { getCachedSiteConfig } from './cache.js';
 export async function loadRenderInput(provider, route = '/', options = {}) {
     const normalized = normalizeRoute(route);

package/dist/content/resolve-slots.d.ts

@@ -0,0 +1,9 @@
+import type { LayoutEntry } from './provider.js';
+import type { KernelPageBlock } from './types.js';
+export interface FragmentData {
+    id: string;
+    component: string;
+    props?: Record<string, unknown>;
+}
+export type FragmentLoader = (id: string) => Promise<FragmentData>;
+export declare function resolveSlots(layout: LayoutEntry, pageRegions: Record<string, KernelPageBlock[]>, getFragment: FragmentLoader): Promise<Record<string, KernelPageBlock[]>>;

package/dist/content/resolve-slots.js

@@ -0,0 +1,24 @@
+export async function resolveSlots(layout, pageRegions, getFragment) {
+    const resolved = {};
+    for (const slot of layout.slots) {
+        const pageBlocks = pageRegions[slot.name];
+        if (pageBlocks && pageBlocks.length > 0) {
+            resolved[slot.name] = pageBlocks;
+            continue;
+        }
+        const defaults = layout.defaults?.[slot.name];
+        if (defaults?.length) {
+            const blocks = [];
+            for (const ref of defaults) {
+                const fragment = await getFragment(ref.fragmentId);
+                blocks.push({
+                    id: fragment.id,
+                    component: fragment.component,
+                    props: fragment.props || {},
+                });
+            }
+            resolved[slot.name] = blocks;
+        }
+    }
+    return resolved;
+}

package/dist/content/types.d.ts

@@ -55,7 +55,6 @@ export interface KernelPage {
     $type: 'page';
     status: string;
     layout: string;
-    renderMode: string;
     metadata: KernelPageSeo;
     regions: Record<string, KernelPageBlock[]>;
 }
@@ -93,6 +92,7 @@ export interface RenderInput<TPage extends KernelPage = KernelPage, TSiteConfig
     siteConfig: TSiteConfig;
     page: TPage | null;
     fragments?: Record<string, unknown>;
+    layouts?: Record<string, unknown>;
 }
 export interface RenderOutput {
     route: string;

package/dist/content/validation.js

@@ -121,7 +121,6 @@ export function createContentSchemas(contracts = {}) {
         $type: z.literal('page'),
         status: z.string().min(1),
         layout: z.string().min(1),
-        renderMode: z.string().min(1),
         metadata: z.looseObject({
             title: z.string().optional(),
             description: z.string().optional(),

package/dist/define-component.js

@@ -1,12 +1,6 @@
 export function defineComponent(definition) {
-    const renderModes = definition.renderModes ?? definition.render;
-    if (!renderModes) {
-        throw new Error(`component ${definition.name} must define renderModes`);
-    }
     return {
         ...definition,
-        renderModes,
-        render: renderModes,
         varyDimensions: definition.varyDimensions ?? definition.vary,
         vary: definition.vary ?? definition.varyDimensions,
     };

package/dist/define-data-model.d.ts

@@ -0,0 +1,2 @@
+import type { DataModelContract, DataModelDefinition } from './types/data.js';
+export declare function defineDataModel<TSchema = unknown, TType extends string = string>(definition: DataModelDefinition<TSchema, TType>): DataModelContract<TSchema, TType>;

package/dist/define-data-model.js

@@ -0,0 +1,3 @@
+export function defineDataModel(definition) {
+    return { ...definition };
+}

package/dist/define-layout.d.ts

@@ -1,4 +1,6 @@
 import type { LayoutContract, LayoutDefinition, LayoutSlot } from './types/layout.js';
+import type { FragmentRefNode } from './types/page.js';
 export declare function defineLayout(definition: LayoutDefinition): LayoutContract;
 export declare const defineLayoutContract: typeof defineLayout;
 export declare function slot(name: string, required?: boolean): LayoutSlot;
+export declare function fragmentDefault(fragmentId: string): FragmentRefNode;

package/dist/define-layout.js

@@ -9,3 +9,6 @@ export const defineLayoutContract = defineLayout;
 export function slot(name, required = false) {
     return { name, required };
 }
+export function fragmentDefault(fragmentId) {
+    return { kind: 'fragment-ref', fragmentId, inline: true };
+}

package/dist/dev/index.d.ts

@@ -7,10 +7,21 @@ declare global {
     }
 }
 export interface GradialContentWatchOptions extends DevRefreshOptions {
+    /** Source content root to watch. Defaults to ACI_CONTENT_SOURCE env or '.content' */
     contentRoot?: string;
+    /** Compiled content output root. Defaults to ACI_CONTENT_ROOT env or '.aci/compiled' */
     compiledRoot?: string;
+    /** Path to the ACI CLI binary. Defaults to ACI_BIN env or 'aci' */
+    aciBin?: string;
+    /** Disable content watching entirely. Defaults to ACI_DISABLE_CONTENT_WATCH env */
     enabled?: boolean;
 }
+interface ViteModuleGraph {
+    idToModuleMap: Map<unknown, {
+        id: string | null;
+    }>;
+    invalidateModule(mod: unknown): void;
+}
 interface ViteDevServerLike {
     middlewares?: {
         use(path: string, handler: (req: IncomingMessage, res: ServerResponse, next: () => void) => void): void;
@@ -22,6 +33,7 @@ interface ViteDevServerLike {
     ws: {
         send(payload: unknown): void;
     };
+    moduleGraph?: ViteModuleGraph;
 }
 export interface VitePluginLike {
     name: string;

package/dist/dev/index.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { compiledContentRoot } from '../content/routes.js';
 import { DEFAULT_DEV_REFRESH_PATH, DEFAULT_DEV_REFRESH_PORT, } from './browser.js';
@@ -48,23 +49,97 @@ export function devRefreshScript(options = {}) {
 export function devRefreshScriptTag(options = {}) {
     return `<script>${devRefreshScript(options)}</script>`;
 }
+function sourceContentRoot(options) {
+    return path.resolve(options.contentRoot ||
+        process.env.ACI_CONTENT_SOURCE ||
+        './.content');
+}
+function resolveAciBin(options) {
+    return options.aciBin || process.env.ACI_BIN || 'aci';
+}
+function recompileContent(options, reason) {
+    const siteDir = process.cwd();
+    const src = sourceContentRoot(options);
+    const out = path.resolve(options.compiledRoot ||
+        process.env.ACI_CONTENT_ROOT ||
+        '.aci/compiled');
+    const bin = resolveAciBin(options);
+    console.log(`[aci] compiling content (${reason})`);
+    const result = spawnSync(bin, [
+        '-s', siteDir,
+        'build',
+        '--content', src,
+        '--out', out,
+        '--skip-code',
+    ], {
+        cwd: siteDir,
+        stdio: 'inherit',
+        env: process.env,
+    });
+    if (result.status !== 0) {
+        console.error(`[aci] content compile failed with exit code ${result.status ?? 'unknown'}`);
+        return false;
+    }
+    return true;
+}
 export function gradialContentWatchPlugin(options = {}) {
     const enabled = options.enabled ?? process.env.ACI_DISABLE_CONTENT_WATCH !== '1';
+    if (!enabled) {
+        return {
+            name: 'gradial-content-watch-disabled',
+            apply: 'serve',
+        };
+    }
+    let timer;
+    let running = false;
+    let queued = false;
+    function rebuild(server, reason) {
+        if (running) {
+            queued = true;
+            return;
+        }
+        running = true;
+        const success = recompileContent(options, reason);
+        running = false;
+        if (success) {
+            if (server.moduleGraph) {
+                for (const mod of server.moduleGraph.idToModuleMap.values()) {
+                    server.moduleGraph.invalidateModule(mod);
+                }
+            }
+            server.ws.send({ type: 'full-reload' });
+        }
+        if (queued) {
+            queued = false;
+            rebuild(server, 'queued change');
+        }
+    }
     return {
         name: 'gradial-content-watch',
         apply: 'serve',
         configureServer(server) {
-            if (!enabled) {
-                return;
-            }
-            const root = path.resolve(options.contentRoot || compiledContentRoot());
-            server.watcher.add(root);
-            server.watcher.on('all', (_eventName, filePath) => {
+            const src = sourceContentRoot(options);
+            const compiled = path.resolve(options.compiledRoot ||
+                process.env.ACI_CONTENT_ROOT ||
+                compiledContentRoot());
+            server.watcher.add(src);
+            server.watcher.add(compiled);
+            rebuild(server, 'startup');
+            server.watcher.on('all', (_event, filePath) => {
                 const changed = path.resolve(filePath);
-                const relative = path.relative(root, changed);
-                if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
-                    server.ws.send({ type: 'full-reload', path: '*' });
+                const isSource = changed.startsWith(src + path.sep);
+                const isCompiled = changed.startsWith(compiled + path.sep);
+                if (!isSource && !isCompiled)
+                    return;
+                if (isCompiled) {
+                    server.ws.send({ type: 'full-reload' });
+                    return;
                 }
+                clearTimeout(timer);
+                timer = setTimeout(() => {
+                    const relative = path.relative(src, changed);
+                    rebuild(server, relative);
+                }, 100);
             });
         },
     };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './block-ref.js';
 export * from './define-component.js';
+export * from './define-data-model.js';
 export * from './define-layout.js';
+export * from './registry.js';
 export * from './types/index.js';

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './block-ref.js';
 export * from './define-component.js';
+export * from './define-data-model.js';
 export * from './define-layout.js';
+export * from './registry.js';
 export * from './types/index.js';
 // Note: content/ is NOT re-exported here because it imports node:path,
 // making it incompatible with client-side bundlers. Import server-only

package/dist/next/asset-route.d.ts

@@ -5,5 +5,7 @@ type AssetRouteParams = {
     releaseId?: string;
     path?: string[];
 };
+export declare const runtime = "nodejs";
+export declare const dynamic = "force-dynamic";
 export declare function GET(_request: Request, { params }: AssetRouteContext): Promise<Response>;
 export {};

package/dist/next/asset-route.js

@@ -1,11 +1,19 @@
+import { FileContentProvider } from '../providers/file.js';
 import { getReleaseAssetResponse } from './server.js';
+const LOCAL_RELEASE_ID = 'local';
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
 export async function GET(_request, { params }) {
     const resolvedParams = await params;
     const releaseId = resolvedParams.releaseId || '';
-    const assetPath = (resolvedParams.path || []).join('/');
-    if (!releaseId || !assetPath) {
+    const assetPath = '/' + (resolvedParams.path || []).join('/');
+    if (!releaseId || assetPath === '/') {
         return new Response('asset not found', { status: 404 });
     }
+    if (releaseId === LOCAL_RELEASE_ID) {
+        const provider = new FileContentProvider();
+        return provider.fetchRaw(assetPath);
+    }
     try {
         return await getReleaseAssetResponse(releaseId, assetPath);
     }

package/dist/next/config.d.ts

@@ -3,4 +3,4 @@ export interface WithGradialOptions {
     /** Asset rewrite prefix. Defaults to '/.gradial-dam' */
     assetPrefix?: string;
 }
-export declare function withGradial(nextConfig?: NextConfig, options?: WithGradialOptions): NextConfig;
+export declare function withGradialAci(nextConfig?: NextConfig, options?: WithGradialOptions): NextConfig;

package/dist/next/config.js

@@ -1,13 +1,15 @@
-export function withGradial(nextConfig = {}, options = {}) {
+import { createContentWatchWebpackPlugin } from './content-watch.js';
+export function withGradialAci(nextConfig = {}, options = {}) {
     const assetPrefix = options.assetPrefix || '/.gradial-dam';
     const userRewrites = nextConfig.rewrites;
+    const userWebpack = nextConfig.webpack;
     return {
         ...nextConfig,
         rewrites: async () => {
             const gradialRewrites = [
                 {
                     source: `${assetPrefix}/:path*`,
-                    destination: `/api/aci-assets${assetPrefix}/:path*`,
+                    destination: `/gradial/assets/local${assetPrefix}/:path*`,
                 },
             ];
             if (!userRewrites)
@@ -21,5 +23,15 @@ export function withGradial(nextConfig = {}, options = {}) {
                 beforeFiles: [...gradialRewrites, ...(userResult.beforeFiles ?? [])],
             };
         },
+        webpack: (config, context) => {
+            if (context?.isServer && process.env.NODE_ENV !== 'production') {
+                if (!config.plugins)
+                    config.plugins = [];
+                config.plugins.push(createContentWatchWebpackPlugin());
+            }
+            return typeof userWebpack === 'function'
+                ? userWebpack(config, context)
+                : config;
+        },
     };
 }

package/dist/next/content-watch.d.ts

@@ -0,0 +1,11 @@
+interface ContentWatchWebpackPlugin {
+    apply(compiler: {
+        hooks: {
+            [key: string]: {
+                tap: (name: string, fn: () => void) => void;
+            };
+        };
+    }): void;
+}
+export declare function createContentWatchWebpackPlugin(): ContentWatchWebpackPlugin;
+export {};