@gradial/aci 0.1.53-rc.2 → 0.1.53-rc.4

package/templates/astro/template/package.json.tmpl

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "astro dev --host 0.0.0.0",
-    "build": "node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs prepare && astro build",
+    "build": "aci error-pages prepare && astro build",
     "preview": "ACI_CONTENT_ROOT=./.aci/compiled astro preview --host 0.0.0.0",
     "typecheck": "ACI_CONTENT_ROOT=./.aci/compiled astro check --tsconfig ./tsconfig.json",
     "test": "node --import tsx --test tests/**/*.test.ts",

package/templates/common/.agents/skills/authoring/SKILL.md

@@ -918,3 +918,9 @@ Read `references/asset-rendering.md` for `imageAttrs()`, `Picture`,
 Read `references/type-safety.md` for `ContentProps` from contracts,
 `as any` prohibition, CSS custom property typing, site config
 generics, and block slot type imports.
+
+## Deep Dive: SDK Migrations
+
+Read `references/sdk-migrations.md` when an `@gradial/aci` upgrade's
+changelog says `Migration required`: what changed, which files to touch, the
+fix, and how to confirm it with `npm test`.

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

@@ -3,21 +3,55 @@
 The component registry maps contract names to runtime components. It is built
 using `createRegistry` from `@gradial/aci` with raw `[contract, component]` tuples.
 
-Every registered component must extend `RootIdentityProps` (exported from
-`@gradial/aci`) and spread the rest of its props onto its root element. The
+Every registered component must extend `AciRootProps` (exported from
+`@gradial/aci`) and put `{...aciRootAttrs(props)}` on its root element. The
 renderer passes `data-aci-block` and `data-aci-component` to every block so
 analytics can join events to content; a component that does not declare the
 type fails `createRegistry` typecheck with
-`<id>: props type must extend RootIdentityProps from @gradial/aci`, and one
-that does not spread fails the `rootIdentity` conformance check under
-`npm test`.
+`<id>: props type must extend AciRootProps from @gradial/aci`, and one that
+does not place them on its root fails the `rootIdentity` conformance check
+under `npm test`.
 
 ```tsx
-export function StatsBar({ stats = [], ...root }: ContentProps & RootIdentityProps) {
-  return <section {...root} className="…">…</section>;
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
+import type { ContentProps } from '@/cms/contracts/components/statsBar.contract';
+
+export function StatsBar(props: ContentProps & AciRootProps) {
+  const { stats = [] } = props;
+  return <section {...aciRootAttrs(props)} className="…">…</section>;
+}
+```
+
+In Astro, write `<section {...aciRootAttrs(Astro.props)}>`. See
+`sdk-migrations.md` for the upgrade from a component that predates the
+contract.
+
+**Empty state** — A block renders its root on every render, empty content included. Render
+the root with `aciRootAttrs` and no children instead of returning `null`.
+
+```tsx
+if (stats.length === 0) return <section {...aciRootAttrs(props)} />;
+```
+
+```astro
+<section {...aciRootAttrs(Astro.props)}>{stats.map((s) => <Stat {...s} />)}</section>
+```
+
+**Client-only widget** — Render a server placeholder root that carries the attributes and holds the
+client-only part.
+
+```tsx
+const Map = dynamic(() => import('./Map'), { ssr: false });
+
+export function StoreMap(props: ContentProps & AciRootProps) {
+  return <div {...aciRootAttrs(props)}><Map {...props.map} /></div>;
 }
 ```
 
+```astro
+<div {...aciRootAttrs(Astro.props)}><Map client:only="react" {...map} /></div>
+```
+
 The tuple form provides **type-level validation** — the component must accept
 at least the props derived from the contract's Zod schema. If you register a
 component with the wrong prop type, TypeScript will fail at the call site.

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

@@ -0,0 +1,87 @@
+# SDK Migrations
+
+Some `@gradial/aci` releases require a change in the site's code. Each such
+release has a `### Migration required` section in the SDK `CHANGELOG.md`
+(`node_modules/@gradial/aci/CHANGELOG.md`) that links here. There is no
+migrate command and no file to record: make the change, then confirm it with
+`npm test`. If the site is not ready, pin the previous `@gradial/aci` version
+and rebuild.
+
+## Root identity (0.1.52-rc.24)
+
+Every registered component must put the two root identity props the renderer
+passes, `data-aci-block` and `data-aci-component`, on its own root element.
+Analytics joins events to content by them, and block-level features build on
+them.
+
+- **Which files** — every component in `src/cms/registry.ts`. Not the
+  elements those components render inside themselves.
+- **The fix** — extend `AciRootProps` (formerly `RootIdentityProps`) and put
+  `{...aciRootAttrs(props)}` on the root element. A rest-spread (`...root`,
+  then `{...root}` on the root) also works.
+- **Who checks it** — `npm test` runs the `rootIdentity` conformance check,
+  which renders each component and names the file of each one that fails.
+  On Next, `next build` fails first through the registry type check;
+  `astro build` does not check it.
+
+Next.js:
+
+```tsx
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
+
+export function StatsBar(props: ContentProps & AciRootProps) {
+  const { stats = [] } = props;
+  return <section {...aciRootAttrs(props)} className="…">…</section>;
+}
+```
+
+Astro:
+
+```astro
+---
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
+
+interface Props extends AciRootProps {
+  stats?: Stat[];
+}
+
+const { stats = [] } = Astro.props;
+---
+<section {...aciRootAttrs(Astro.props)} class="…">…</section>
+```
+
+`aciRootAttrs` and the `AciRootProps` name ship after 0.1.52-rc.24. On an
+older release, write `RootIdentityProps` and a rest-spread instead.
+
+To confirm, run `npm test`. The `rootIdentity` check passes, or it lists each
+failing component with its source file, the defect, and the fix.
+
+### Empty state
+
+A block renders its root on every render, empty content included. Render
+the root with `aciRootAttrs` and no children instead of returning `null`.
+
+```tsx
+if (stats.length === 0) return <section {...aciRootAttrs(props)} />;
+```
+
+```astro
+<section {...aciRootAttrs(Astro.props)}>{stats.map((s) => <Stat {...s} />)}</section>
+```
+
+### Client-only widget
+
+Render a server placeholder root that carries the attributes and holds the
+client-only part.
+
+```tsx
+const Map = dynamic(() => import('./Map'), { ssr: false });
+
+export function StoreMap(props: ContentProps & AciRootProps) {
+  return <div {...aciRootAttrs(props)}><Map {...props.map} /></div>;
+}
+```
+
+```astro
+<div {...aciRootAttrs(Astro.props)}><Map client:only="react" {...map} /></div>
+```

package/templates/nextjs/starter-content/src/components/chrome/Footer.tsx

@@ -1,9 +1,9 @@
 import { Container } from '@/components/elements/Container';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import { Logo } from '@/components/elements/Logo';
 import type { FooterColumn, FooterGroup, FooterLink } from '@gradial/aci/content';
 
-interface FooterProps extends RootIdentityProps {
+interface FooterProps extends AciRootProps {
   brandHref: string;
   brandLabel: string;
   brandLogo?: { src: string; alt?: string } | null;
@@ -18,9 +18,10 @@ function columnGroups(column: FooterColumn): FooterGroup[] {
   return [{ id: column.id, title: column.title || '', links: column.links || [] }];
 }
 
-export function Footer({ brandHref, brandLabel, brandLogo = null, columns = [], social = [], legalLinks = [], copyright = '', ...root }: FooterProps) {
+export function Footer(props: FooterProps) {
+  const { brandHref, brandLabel, brandLogo = null, columns = [], social = [], legalLinks = [], copyright = '' } = props;
   return (
-    <footer {...root} className="bm-footer relative pt-[var(--spacing-footer-y)]" id="footer">
+    <footer {...aciRootAttrs(props)} className="bm-footer relative pt-[var(--spacing-footer-y)]" id="footer">
       <div className="absolute inset-x-0 top-0 h-px bg-gradient-to-r from-transparent via-[var(--color-brand-500)] to-transparent opacity-50" />
       <Container>
         <div className="footer-main-grid grid grid-cols-1 gap-12 lg:grid-cols-2">

package/templates/nextjs/starter-content/src/components/chrome/Header.tsx

@@ -2,10 +2,10 @@ import { Button } from '@/components/elements/Button';
 import { Container } from '@/components/elements/Container';
 import { Icon } from '@/components/elements/Icon';
 import { Logo } from '@/components/elements/Logo';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { NavItem, UtilityItem } from '@gradial/aci/content';
 
-interface HeaderProps extends RootIdentityProps {
+interface HeaderProps extends AciRootProps {
   brandHref: string;
   brandLabel: string;
   brandLogo?: { src: string; alt?: string } | null;
@@ -13,9 +13,10 @@ interface HeaderProps extends RootIdentityProps {
   utilities?: UtilityItem[];
 }
 
-export function Header({ brandHref, brandLabel, brandLogo = null, navigation = [], utilities = [], ...root }: HeaderProps) {
+export function Header(props: HeaderProps) {
+  const { brandHref, brandLabel, brandLogo = null, navigation = [], utilities = [] } = props;
   return (
-    <header {...root} className="bm-header fixed top-0 left-0 right-0 z-[var(--z-header)] border-b border-[var(--header-border)]">
+    <header {...aciRootAttrs(props)} className="bm-header fixed top-0 left-0 right-0 z-[var(--z-header)] border-b border-[var(--header-border)]">
       <a href="#content-main" className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-[var(--z-overlay)] focus:rounded-button focus:bg-[var(--color-space-900)] focus:px-4 focus:py-2 focus:text-[var(--color-white)]">
         Skip to main content
       </a>

package/templates/nextjs/starter-content/src/components/elements/ButtonBlock.tsx

@@ -1,16 +1,17 @@
 import { Button } from '@/components/elements/Button';
 import { Icon } from '@/components/elements/Icon';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { ContentProps } from '@/cms/contracts/components/button.contract';
 
-export type ButtonBlockProps = ContentProps & RootIdentityProps;
+export type ButtonBlockProps = ContentProps & AciRootProps;
 
-export function ButtonBlock({ label = '', href = '#', variant = 'primary', newWindow = false, icon = '', iconPosition = 'before', className = '', ...root }: ButtonBlockProps) {
+export function ButtonBlock(props: ButtonBlockProps) {
+  const { label = '', href = '#', variant = 'primary', newWindow = false, icon = '', iconPosition = 'before', className = '' } = props;
   const target = newWindow ? '_blank' : undefined;
   const rel = newWindow ? 'noreferrer' : undefined;
 
   return (
-    <Button href={href} variant={variant} target={target} rel={rel} className={className} {...root}>
+    <Button href={href} variant={variant} target={target} rel={rel} className={className} {...aciRootAttrs(props)}>
       {icon && iconPosition === 'before' ? <Icon name={icon} /> : null}
       <span>{label}</span>
       {icon && iconPosition === 'after' ? <Icon name={icon} /> : null}

package/templates/nextjs/starter-content/src/components/sections/ContainerSection.tsx

@@ -1,22 +1,22 @@
 import { Container } from '@/components/elements/Container';
 import { type ContentProps } from '@/cms/contracts/components/container.contract';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { RenderChildren } from '@gradial/aci/react';
 
-export async function ContainerSection({
-  theme = 'auto',
-  className = '',
-  content,
-  renderChildren,
-  ...root
-}: ContentProps & RootIdentityProps & { renderChildren: RenderChildren<NonNullable<ContentProps['content']>> }) {
+export async function ContainerSection(props: ContentProps & AciRootProps & { renderChildren: RenderChildren<NonNullable<ContentProps['content']>> }) {
+  const {
+    theme = 'auto',
+    className = '',
+    content,
+    renderChildren,
+  } = props;
   const buttonCount = content?.filter((b) => b.component === 'button').length ?? 0;
   const layout = buttonCount === 1
     ? 'flex-col items-center'
     : 'flex-col items-center sm:flex-row sm:justify-center sm:gap-4';
 
   return (
-    <section className={`theme-${theme} relative overflow-hidden py-[var(--spacing-section-y)] ${className}`} {...root}>
+    <section className={`theme-${theme} relative overflow-hidden py-[var(--spacing-section-y)] ${className}`} {...aciRootAttrs(props)}>
       {theme === 'dark' ? (
         <div className="pointer-events-none absolute inset-0 bg-[image:var(--gradient-hero-base)] opacity-30" />
       ) : null}

package/templates/nextjs/starter-content/src/components/sections/FeatureCard.tsx

@@ -1,12 +1,13 @@
 import { Icon } from '@/components/elements/Icon';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { ContentProps } from '@/cms/contracts/components/featureCard.contract';
 
-export type FeatureCardProps = ContentProps & RootIdentityProps;
+export type FeatureCardProps = ContentProps & AciRootProps;
 
-export function FeatureCard({ icon = '', title = '', description = '', ...root }: FeatureCardProps) {
+export function FeatureCard(props: FeatureCardProps) {
+  const { icon = '', title = '', description = '' } = props;
   return (
-    <div {...root} className="group relative overflow-hidden rounded-card border border-[var(--color-border-default)] bg-[var(--color-white)] p-[var(--spacing-card)] shadow-[var(--shadow-card-default)] transition-all duration-[var(--transition-duration-fast)] hover:-translate-y-1 hover:border-[var(--color-border-strong)] hover:shadow-[var(--shadow-elevated)]">
+    <div {...aciRootAttrs(props)} className="group relative overflow-hidden rounded-card border border-[var(--color-border-default)] bg-[var(--color-white)] p-[var(--spacing-card)] shadow-[var(--shadow-card-default)] transition-all duration-[var(--transition-duration-fast)] hover:-translate-y-1 hover:border-[var(--color-border-strong)] hover:shadow-[var(--shadow-elevated)]">
       <div className="absolute inset-x-0 top-0 h-px bg-gradient-to-r from-transparent via-[var(--color-brand-500)] to-transparent opacity-0 transition-opacity duration-[var(--transition-duration-fast)] group-hover:opacity-100" />
       {icon ? (
         <div className="mb-6 flex h-12 w-12 items-center justify-center rounded-button border border-[var(--color-border-default)] bg-[var(--color-surface-100)] text-[var(--color-brand-600)] shadow-[var(--shadow-glow-sm)] transition-colors group-hover:border-[var(--color-brand-500)] group-hover:text-[var(--color-brand-500)]">

package/templates/nextjs/starter-content/src/components/sections/FeatureGrid.tsx

@@ -1,20 +1,20 @@
 import { Container } from '@/components/elements/Container';
 import { type ContentProps } from '@/cms/contracts/components/featureGrid.contract';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { RenderChildren } from '@gradial/aci/react';
 
-export async function FeatureGrid({
-  title = '',
-  subtitle = '',
-  features,
-  renderChildren,
-  ...root
-}: ContentProps & RootIdentityProps & { renderChildren: RenderChildren<NonNullable<ContentProps['features']>> }) {
+export async function FeatureGrid(props: ContentProps & AciRootProps & { renderChildren: RenderChildren<NonNullable<ContentProps['features']>> }) {
+  const {
+    title = '',
+    subtitle = '',
+    features,
+    renderChildren,
+  } = props;
   const count = features?.length ?? 0;
   const cols = count <= 2 ? 'sm:grid-cols-2' : 'sm:grid-cols-2 lg:grid-cols-3';
 
   return (
-    <section className="theme-light relative overflow-hidden py-[var(--spacing-section-y)] bg-[var(--color-white)]" {...root}>
+    <section className="theme-light relative overflow-hidden py-[var(--spacing-section-y)] bg-[var(--color-white)]" {...aciRootAttrs(props)}>
       <div className="pointer-events-none absolute inset-0 bg-[image:var(--gradient-hero-base)] opacity-50" />
       <Container className="relative">
         <div className="mb-14 max-w-[var(--max-width-container-narrow)]">

package/templates/nextjs/starter-content/src/components/sections/HomeHero.tsx

@@ -1,19 +1,20 @@
 import { Button } from '@/components/elements/Button';
 import { Container } from '@/components/elements/Container';
-import { primaryImageSource, type RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, primaryImageSource, type AciRootProps } from '@gradial/aci';
 import type { ContentProps } from '@/cms/contracts/components/homeHero.contract';
 
 type HeroImage = NonNullable<ContentProps['image']>;
 
-export type HomeHeroProps = Omit<ContentProps, 'image'> & { image?: HeroImage } & RootIdentityProps;
+export type HomeHeroProps = Omit<ContentProps, 'image'> & { image?: HeroImage } & AciRootProps;
 
-export function HomeHero({ eyebrow = '', headline = '', description = '', ctaLabel = '', ctaHref = '#', image, ...root }: HomeHeroProps) {
+export function HomeHero(props: HomeHeroProps) {
+  const { eyebrow = '', headline = '', description = '', ctaLabel = '', ctaHref = '#', image } = props;
   const imageSrc = heroImageSrc(image);
   const imageAlt = image?.alt || headline;
 
   return (
     <section
-      {...root}
+      {...aciRootAttrs(props)}
       className="theme-light relative flex min-h-[var(--height-hero-min)] items-center bg-cover bg-center"
       aria-label={imageAlt}
       style={{

package/templates/nextjs/starter-content/src/components/sections/PersonalizationChoice.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { ContentProps } from '@/cms/contracts/components/personalizationChoice.contract';
 
 type AciWindow = Window & { aci?: (command: string, value: unknown) => void };
@@ -10,14 +10,14 @@ function hasCookie(name: string): boolean {
   return document.cookie.split('; ').some((value) => value.startsWith(`${name}=`));
 }
 
-export function PersonalizationChoice({
-  title,
-  description,
-  redLabel,
-  blueLabel,
-  refreshLabel,
-  ...root
-}: ContentProps & RootIdentityProps) {
+export function PersonalizationChoice(props: ContentProps & AciRootProps) {
+  const {
+    title,
+    description,
+    redLabel,
+    blueLabel,
+    refreshLabel,
+  } = props;
   const [consent, setConsent] = useState(false);
   const [marker, setMarker] = useState(false);
 
@@ -32,7 +32,7 @@ export function PersonalizationChoice({
   }, []);
 
   return (
-    <section className="border-y border-[var(--color-border)] bg-[var(--color-surface)] py-[var(--spacing-section-y)]" {...root}>
+    <section className="border-y border-[var(--color-border)] bg-[var(--color-surface)] py-[var(--spacing-section-y)]" {...aciRootAttrs(props)}>
       <div className="mx-auto max-w-[var(--layout-content-max)] px-[var(--layout-gutter)] text-center">
         <h2 className="text-[length:var(--text-h2)] font-[var(--font-weight-semibold)] text-[var(--color-fg)]">{title}</h2>
         {description ? <p className="mx-auto mt-3 max-w-2xl text-[var(--color-fg-muted)]">{description}</p> : null}

package/templates/nextjs/starter-content/src/components/sections/StatsBar.tsx

@@ -1,12 +1,13 @@
 import { Container } from '@/components/elements/Container';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { ContentProps } from '@/cms/contracts/components/statsBar.contract';
 
-export type StatsBarProps = ContentProps & RootIdentityProps;
+export type StatsBarProps = ContentProps & AciRootProps;
 
-export function StatsBar({ stats = [], ...root }: StatsBarProps) {
+export function StatsBar(props: StatsBarProps) {
+  const { stats = [] } = props;
   return (
-    <section {...root} className="theme-light relative border-y border-[var(--color-border-default)] bg-[var(--color-surface-100)] py-[var(--spacing-section-y)]">
+    <section {...aciRootAttrs(props)} className="theme-light relative border-y border-[var(--color-border-default)] bg-[var(--color-surface-100)] py-[var(--spacing-section-y)]">
       <div className="pointer-events-none absolute inset-0 bg-[image:var(--gradient-hero-base)] opacity-40" />
       <Container className="relative">
         <div className="grid gap-10 sm:grid-cols-2 lg:grid-cols-4">

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

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "ACI_CONTENT_PROVIDER=file next dev -H 0.0.0.0",
-    "build": "node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs prepare && next build && node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs emit",
+    "build": "aci error-pages prepare && next build && aci error-pages emit",
     "preview": "next start -H 0.0.0.0",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test tests/**/*.test.ts",