@gradial/aci 0.1.27 → 0.1.29

package/templates/common/.agents/skills/authoring/references/block-slots.md

@@ -0,0 +1,140 @@
+# Block Slots Reference
+
+## What Block Slots Are
+
+Container components (like `container` and `grid_column`) can render
+child blocks. The SDK detects block slots from contracts and injects a
+`renderChildren` callback into the component props at render time.
+
+This lets editors nest blocks inside other blocks in content JSON, and
+the SDK resolves the child components through the registry — no
+hardcoded component name matching needed.
+
+## Defining Block Slots in Contracts
+
+Use `blockRefArray()` from `@gradial/aci` in the contract's Zod schema
+to declare a block slot field. The compiler scans the schema for
+`blockRefArray` and `blockRef` fields and auto-discovers block slots —
+no separate `slots` or `blockSlots` declaration needed.
+
+```ts
+import { blockRefArray, defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+import { calloutContract } from './callout.contract';
+import { headingContract } from './heading.contract';
+
+export const schema = z.object({
+  theme: z.enum(['auto', 'light', 'dark']).optional(),
+  className: z.string().optional(),
+  blocks: blockRefArray([calloutContract, headingContract]).optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const containerContract = defineComponentContract({
+  id: 'container',
+  props: schema,
+});
+```
+
+`blockRefArray()` takes an array of allowed contracts — only those block
+types can be placed in the slot. This flows into the generated JSON
+schema, so the content validator enforces the allowlist at build time.
+
+For a single (non-array) block slot, use `blockRef(contracts)` instead:
+
+```ts
+import { blockRef, defineComponentContract } from '@gradial/aci';
+import { headingContract } from './heading.contract';
+
+export const schema = z.object({
+  heading: blockRef([headingContract]).optional(),
+});
+```
+
+## Using renderChildren in Components
+
+The SDK's render system checks `entry.contract.blockSlots` and, if
+present, injects a `renderChildren` callback into the component props.
+This callback resolves child blocks through the registry.
+
+```tsx
+import type { BlockRef, ReactElement } from '@gradial/aci';
+import type { RenderChildren } from '@gradial/aci/react';
+import type { ContentProps } from '@/cms/contracts/components/container.contract';
+
+export async function ContainerSection({
+  theme = 'auto',
+  className = '',
+  blocks = [],
+  renderChildren,
+}: ContentProps & { renderChildren?: RenderChildren<readonly BlockRef[]> }) {
+  const rendered = blocks.length && renderChildren
+    ? await renderChildren(blocks)
+    : null;
+
+  return (
+    <section className={`theme-${theme} py-[var(--spacing-section-y)] ${className}`}>
+      <div className="flex flex-col gap-6">
+        {rendered}
+      </div>
+    </section>
+  );
+}
+```
+
+The `RenderChildren` type is exported from `@gradial/aci/react`:
+
+```ts
+type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<ReactElement[]>;
+```
+
+## Rules
+
+- **Never hardcode component name matching.** No switch statements on
+  `block.component`. Always use `renderChildren` from the SDK — it uses
+  the registry to resolve components.
+- **Always use `blockRefArray()` in contracts** to declare block slot
+  fields. The compiler auto-discovers them from the Zod schema.
+- **Atomic block contracts must be registered** in the registry with
+  their components. `renderChildren` resolves child blocks through the
+  same registry used for top-level blocks.
+- **`blockRefArray()` takes an array of allowed contracts** — only
+  those block types can be placed in the slot. This is enforced at
+  content validation time.
+- **`renderChildren` is optional** — always guard with a conditional
+  (`blocks.length && renderChildren ? await renderChildren(blocks) : null`)
+  so the component works in isolation (e.g., Storybook).
+- **Nested blocks live inside `props`**, not in a sibling `slots` field.
+  The content JSON places child blocks directly in the prop value
+  matching the `blockRefArray` field name.
+
+## Content JSON Example
+
+```json
+{
+  "id": "cta-section",
+  "component": "container",
+  "props": {
+    "theme": "dark",
+    "blocks": [
+      {
+        "id": "primary-cta",
+        "component": "callout",
+        "props": {
+          "headline": "Get started today",
+          "body": "Ship content updates in minutes."
+        }
+      },
+      {
+        "id": "heading",
+        "component": "heading",
+        "props": {
+          "text": "Why teams choose us",
+          "level": 2
+        }
+      }
+    ]
+  }
+}
+```

package/templates/common/.agents/skills/authoring/references/rich-text.md

@@ -0,0 +1,75 @@
+# Rich Text Reference
+
+## Rules
+
+- **NEVER** use `marked`, `markdown-it`, or `dangerouslySetInnerHTML`
+  directly in component code.
+- **ALWAYS** use the SDK's `RichText` component from `@gradial/aci/react`.
+
+The SDK `RichText` component uses `sanitize-html` with an explicit
+allowlist. It renders markdown via `markdown-it` (with `html: false` to
+prevent raw HTML in markdown) and then sanitizes the output. Links get
+`rel="noopener noreferrer"` automatically.
+
+## Usage
+
+```tsx
+import { RichText } from '@gradial/aci/react';
+
+export function ArticleBody({ body }: { body: string }) {
+  return <RichText value={body} />;
+}
+```
+
+The `value` prop accepts:
+
+- **`string`** — treated as markdown and rendered to HTML
+- **`RichTextValue`** object — `{ format: 'markdown', markdown: '...' }`
+  or `{ format: 'html', html: '...' }`
+
+When a string is passed, the component wraps it as
+`{ format: 'markdown', markdown: value }` internally.
+
+## In Contracts
+
+Use `RichTextValueSchema` for typed rich text fields:
+
+```ts
+import { RichTextValueSchema } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  body: RichTextValueSchema.optional(),
+});
+```
+
+Or accept a plain string:
+
+```ts
+export const schema = z.object({
+  body: z.string().optional(),
+});
+```
+
+Both forms work with the `RichText` component — it accepts
+`RichTextValue | string`.
+
+## Sanitization Policy
+
+The SDK allowlist includes:
+
+- Standard formatting tags: `p`, `br`, `strong`, `em`, `ul`, `ol`, `li`,
+  `code`, `pre`, `blockquote`, `h1`–`h6`, `img`
+- Links (`a`) with `href`, `name`, `target`, `rel` attributes
+- Images (`img`) with `src`, `alt`, `width`, `height`, `loading`
+  attributes
+
+Raw HTML in markdown input is rejected by `markdown-it`'s `html: false`
+setting. HTML format values are sanitized by `sanitize-html`.
+
+## Anti-Patterns
+
+- Importing `marked` or `markdown-it` directly — the SDK already
+  handles this with proper sanitization
+- Using `dangerouslySetInnerHTML` with unsanitized content
+- Writing a custom markdown-to-HTML pipeline in component code

package/templates/common/.agents/skills/authoring/references/sdk-server-functions.md

@@ -0,0 +1,192 @@
+# SDK Server Functions Reference
+
+## `@gradial/aci/next` Exports
+
+The SDK provides server-side functions that handle content resolution
+across preview, local file, and deployed S3 modes. **Always use these
+functions instead of directly importing `FileContentProvider` or
+`S3ContentProvider`.** The SDK handles the resolution chain automatically.
+
+### `createPage(registry)`
+
+The catch-all route handler for Next.js App Router. Owns param
+normalization, content loading via render input, metadata generation,
+`notFound` handling, layout resolution, and block rendering via the
+registry.
+
+```tsx
+// src/app/[[...slug]]/page.tsx
+import { createPage } from '@gradial/aci/next';
+import { registry } from '@/cms/registry';
+
+const page = createPage(registry);
+export const dynamic = 'force-dynamic';
+export const generateMetadata = page.generateMetadata;
+export default page.default;
+```
+
+`createPage` loads the page's layout, resolves all slots (filling from
+page regions or layout fragment defaults), and renders blocks via the
+registry. The `main` slot is wrapped in `<main>`; other slots render as
+fragments.
+
+### `withAci(nextConfig, options?)`
+
+Next.js config wrapper. Sets up asset rewrites (`.gradial-dam` prefix)
+and dev-mode content watch via webpack plugin.
+
+```ts
+// next.config.ts
+import { withAci } from '@gradial/aci/next';
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = { reactStrictMode: true };
+export default withAci(nextConfig);
+```
+
+### `getSiteConfig<T>()`
+
+Loads the site configuration. Checks the render input header first
+(preview mode), then falls back to file or S3 provider. **MUST be used
+in `layout.tsx` instead of `new FileContentProvider()`.**
+
+```tsx
+import { getSiteConfig } from '@gradial/aci/next';
+
+const siteConfig = await getSiteConfig<MySiteConfig>();
+```
+
+Generic: pass your site config interface for typed access:
+`getSiteConfig<SiteConfig>()`.
+
+### `getFragment(name)`
+
+Loads a fragment by name. Checks render input first (preview mode), then
+provider fallback.
+
+### `getLayout(name)`
+
+Loads a layout by name. Checks render input first (preview mode), then
+provider fallback.
+
+### `getPage(route)`
+
+Loads page content for a specific route. Checks render input first
+(preview mode), then provider fallback.
+
+### `getRenderInput(route)`
+
+Loads the full render input (page + siteConfig + domain + locale). Used
+internally by `createPage`. Available for custom server composition when
+you need the full render context.
+
+### `routeFromNextParams(params)`
+
+Normalizes Next.js catch-all params (`{ slug?: string[] }`) into a route
+string. Handles `Promise`-wrapped params from Next.js 15+.
+
+### `isPreviewMode()`
+
+Async function returning the preview release ID string when in preview
+mode, or an empty string when not. Use as a truthy check:
+
+```tsx
+const previewRelease = await isPreviewMode();
+if (previewRelease) { /* preview-specific logic */ }
+```
+
+### `DevRefresh`
+
+React component for dev-mode content refresh. Connects to the SDK's
+content watch WebSocket and triggers a page reload when compiled content
+changes. Add to the root layout:
+
+```tsx
+import { DevRefresh } from '@gradial/aci/next';
+
+// In layout body:
+<DevRefresh />
+```
+
+Only active in development (`NODE_ENV !== 'production'`). Renders `null`
+in production.
+
+### Error Classes
+
+| Class | Thrown When |
+|-------|-------------|
+| `PageNotFoundError` | Page not found for a route |
+| `FragmentNotFoundError` | Fragment not found by name |
+| `LayoutNotFoundError` | Layout not found by name |
+
+`createPage` catches `PageNotFoundError` and calls `notFound()`
+automatically.
+
+## Three-Tier Content Resolution
+
+Every SDK server function follows the same resolution chain:
+
+### Tier 1: Render Input (Preview Mode)
+
+When the Go harness sends a render request, it sets the
+`x-gradial-render-input-id` header. The SDK checks the
+`pendingRenderInputs` in-process map for a matching render input and
+returns page data directly from the Go harness's render payload. This
+is how preview works — the harness pushes content into the Next.js
+process without touching S3 or disk.
+
+### Tier 2: File Provider (`ACI_CONTENT_PROVIDER=file`)
+
+When the `ACI_CONTENT_PROVIDER` environment variable is set to `file`,
+the SDK reads compiled content from `.aci/compiled/` on disk. This is
+the local development path. Also used as a fallback in preview mode when
+no render input header is present.
+
+### Tier 3: S3 Provider (Deployed SSR)
+
+When neither render input nor file provider is active, the SDK reads
+from S3. The release ID is resolved from (in order):
+
+1. `x-gradial-release-id` header (set by middleware)
+2. `ACI_RELEASE_ID` environment variable
+3. Vercel Edge Config active release pointer
+
+## Critical Rule
+
+**NEVER import `FileContentProvider` or `S3ContentProvider` directly in
+app code.** Always use `getPage()`, `getSiteConfig()`, `getFragment()`,
+`getLayout()`, or `getRenderInput()` from `@gradial/aci/next`. The SDK
+handles the resolution chain automatically.
+
+The only exception is the asset route handler
+(`src/app/gradial/assets/[releaseId]/[...path]/route.ts`), which directly
+uses `FileContentProvider` for local asset serving and
+`getReleaseAssetResponse` for S3 assets.
+
+## Layout.tsx Pattern
+
+```tsx
+import { DevRefresh, getSiteConfig } from '@gradial/aci/next';
+
+export default async function Layout({ children }: { children: ReactNode }) {
+  const siteConfig = await getSiteConfig<SiteConfig>().catch(() => null);
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <DevRefresh />
+      </body>
+    </html>
+  );
+}
+```
+
+Chrome (Header/Footer) is CMS-managed via layout fragment defaults and
+rendered by `createPage` through the registry. The `layout.tsx` file
+should be minimal — import CSS, optionally load site config for
+metadata/fonts, and render `<DevRefresh />`.
+
+For sites that need site config in the layout (e.g., for fonts or
+metadata), use `getSiteConfig<SiteConfig>()` with a `.catch(() => null)`
+fallback so the layout doesn't crash if content isn't available during
+build.

package/templates/common/.agents/skills/authoring/references/type-safety.md

@@ -0,0 +1,141 @@
+# Type Safety Reference
+
+## ContentProps from Contracts
+
+Contracts export `ContentProps = z.infer<typeof schema>`. Use this type
+in runtime components for prop typing:
+
+```ts
+// src/cms/contracts/components/hero.contract.ts
+import { defineComponentContract, ImageSchema } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  headline: z.string().min(1),
+  image: ImageSchema,
+  ctaLabel: z.string().optional(),
+  ctaHref: z.string().optional(),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const heroContract = defineComponentContract({
+  id: 'hero',
+  props: schema,
+});
+```
+
+```tsx
+// src/components/sections/Hero.tsx
+import type { ContentProps } from '@/cms/contracts/components/hero.contract';
+
+type HeroProps = ContentProps & { className?: string };
+
+export function Hero({ headline, image, ctaLabel, ctaHref, className }: HeroProps) {
+  // ...
+}
+```
+
+## Rules
+
+### No `as any` casts
+
+**NEVER** use `as any` or `as any[]` casts in component code. If the
+type doesn't fit, fix the contract schema.
+
+```tsx
+// BAD
+const items = props.items as any[];
+
+// GOOD — fix the schema to match the actual shape
+export const schema = z.object({
+  items: z.array(z.object({
+    title: z.string(),
+    description: z.string(),
+  })),
+});
+```
+
+### No passthrough schemas
+
+Contracts must define proper schemas. Do not use
+`z.object({}).passthrough()` or `z.record(z.any())`:
+
+```ts
+// BAD — hides type errors and allows any content
+export const schema = z.object({}).passthrough();
+export const schema = z.record(z.any());
+
+// GOOD — explicit fields
+export const schema = z.object({
+  headline: z.string(),
+  items: z.array(z.object({ title: z.string() })),
+});
+```
+
+### CSS custom properties
+
+For React `style` props with CSS custom properties, use
+`as React.CSSProperties` (not `as any`):
+
+```tsx
+// BAD
+<div style={{ '--accent': 'red' } as any} />
+
+// GOOD
+<div style={{ '--accent': 'red' } as React.CSSProperties} />
+```
+
+### Image type
+
+Use the `Image` type from `@gradial/aci` for image props. Never
+duplicate the type locally:
+
+```tsx
+// BAD — local duplicate
+interface Image { src: string; alt: string; }
+
+// GOOD — import from SDK
+import type { Image } from '@gradial/aci';
+```
+
+### Site config
+
+Define a `SiteConfig` interface and pass it to `getSiteConfig()`:
+
+```tsx
+import { getSiteConfig } from '@gradial/aci/next';
+
+interface SiteConfig {
+  title: string;
+  domain: string;
+  defaultLocale: string;
+  navigation: NavItem[];
+  footer: FooterConfig;
+}
+
+const config = await getSiteConfig<SiteConfig>();
+// config is typed as SiteConfig
+```
+
+### Block slot types
+
+Use `RenderChildren` from `@gradial/aci/react` and `BlockRef` from
+`@gradial/aci` for block slot component props:
+
+```tsx
+import type { BlockRef } from '@gradial/aci';
+import type { RenderChildren } from '@gradial/aci/react';
+import type { ContentProps } from '@/cms/contracts/components/container.contract';
+
+export async function ContainerSection({
+  blocks = [],
+  renderChildren,
+}: ContentProps & {
+  renderChildren?: RenderChildren<readonly BlockRef[]>;
+}) {
+  // ...
+}
+```
+
+See `references/block-slots.md` for the full block slot pattern.

package/templates/common/.content/config/site.json

@@ -17,6 +17,11 @@
     "description": "Global satellite internet from anywhere on Earth.",
     "siteName": "Meridian"
   },
+  "personalization": {
+    "collect": true,
+    "consentPreset": "c15t",
+    "consentCategories": "measurement,marketing"
+  },
   "navigation": [
     {
       "id": "home",

package/templates/common/.content/schemas/site.schema.json

@@ -76,6 +76,21 @@
         "description": { "type": "string" },
         "siteName": { "type": "string" }
       }
+    },
+    "personalization": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "collect": { "type": "boolean" },
+        "consentPreset": {
+          "enum": ["c15t", "onetrust", "cookiebot", "trustarc", "manual"]
+        },
+        "consentCategories": {
+          "type": "string",
+          "pattern": "^\\s*[A-Za-z0-9._-]+(\\s*,\\s*[A-Za-z0-9._-]+)*\\s*$"
+        },
+        "debug": { "type": "boolean" }
+      }
     }
   },
   "$defs": {

package/templates/common/README.md.tmpl

@@ -43,3 +43,18 @@ src/design-system/ Design tokens and global styles
 .agents/skills/    Skills for humans and agents
 .aci/              Generated artifacts (compiled, schemas)
 ```
+
+## Personalization
+
+The `personalization` block in `.content/config/site.json` controls the
+Gradial collect tag (`<script defer src="/_aci/aci.js" …>`); pages emit it
+automatically when `collect` is `true`, and not at all when the block is
+absent. Consent is bridged from c15t (`consentPreset: "c15t"`): the Next kit
+ships a full c15t setup (`src/app/_components/ConsentManager.tsx`, offline
+mode by default, hosted via `NEXT_PUBLIC_C15T_BACKEND_URL`); the Astro kit
+ships the store bridge in `SiteLayout.astro` — add a banner via a React
+island (`@astrojs/react` + `@c15t/react`) and it is picked up automatically.
+
+Personalization requires the deployed site to be served through a Gradial
+edge binding, which provides `/collect`, identity, and the SDK itself. See
+the `@gradial/aci` README ("Personalization: The One-Tag Install").

package/templates/nextjs/template/package.json.tmpl

@@ -17,7 +17,9 @@
     "build:storybook": "storybook build"
   },
   "dependencies": {
-    "@gradial/aci": "0.1.23",
+    "@c15t/nextjs": "^2.1.0",
+    "@gradial/aci": "{{aciVersion}}",
+    "js-yaml": "^4.1.1",
     "next": "^15.1.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"