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

package/src/cli/emit-error-pages.mjs

@@ -1,73 +1,15 @@
 #!/usr/bin/env node
-// Authorable error pages — build integration (spec:
-// specs/features/authorable-error-pages, T3/T11; REQ-10/REQ-11/REQ-14, D-9,
-// D-16).
-//
-// ACI_CODE_ARTIFACT_BUILD=1 makes both phases content-independent: prepare
-// serializes only the code-owned policy at its existing .aci/compiled path.
-// Emit uses the shipped default without resolving authored error-page bindings.
-//
-// Two phases. The Next template wires both around `next build`; the Astro
-// template runs only `prepare` before `astro build` (its 404/500 seats
-// render through the framework, but the D-16 instrumentation artifact must
-// still reach the compiled content root for the AWS lane):
-//
-//   prepare  (before `next build`)
-//     Ensures compiled content exists at .aci/compiled so withAci() can
-//     serialize the bound catchAll page for the client-only error seat
-//     (D-9). Compiles ./.content via the platform CLI when needed; when
-//     neither compiled content nor authored content exists, it warns and
-//     leaves the shipped default in play (REQ-4, warn posture). Then writes
-//     error-pages/instrumentation.json (both kinds' serialized tags) into
-//     the compiled content root so the tag crosses the JS→Go boundary as
-//     data: builders retain the instrumentation file at its existing capsule
-//     path, and the Go publish materializer stamps the kind-matching tag into the CDN
-//     error artifacts (D-16). An unserializable tenant push fails the build
-//     loudly here (delta FIND-006).
-//
-//   emit     (after `next build`)
-//     Materializes `public/500.html` from the page bound to
-//     site.json#errorPages.catchAll by booting the standalone build,
-//     fetching the bound route, and post-processing the document. Boot-and-
-//     fetch beats re-rendering the page here because the standalone server
-//     is the only renderer that produces the document exactly as served
-//     (layout shell, resolved fragments, RSC-injected head and styles).
-//     Post-processing:
-//       - all script tags and preload/prefetch links stripped — this
-//         removes the collect and assignment tags (REQ-11) along with the
-//         framework runtime, which is useless in a statically served copy;
-//       - same-origin stylesheets inlined from .next/static (REQ-14 spirit:
-//         inline styles; note @font-face/image URLs inside the CSS keep
-//         their same-origin paths — this copy is served by the Vercel
-//         platform on the deployment that owns those assets);
-//       - one self-contained inline script appended pushing the D-14
-//         `page_view` (page_type "error") — a static document executes
-//         inline scripts, unlike the flight-rendered not-found seat. The
-//         push body is site policy (D-15): the tenant-owned
-//         src/aci/error-page-instrumentation.mjs when present, the SDK
-//         default otherwise;
-//       - hard size budget: ≤150 KB raw (REQ-14) — exceeding it fails the
-//         build; trimming the design system or falling back to system
-//         fonts is the sanctioned escape hatch.
-//     Skips when the site already provides its own public/500.html (a file
-//     without the generation marker); regenerates its own prior output.
-//     Absent bindings emit the shipped branded-neutral default (REQ-4).
-//     Vercel picks static per-status files out of the build output
-//     ("file presence = configuration"); on the current Pro plan the file
-//     serves app-level 500s only and lights up for platform 5xx on a plan
-//     upgrade (REQ-10, P-1).
-//
-// Usage: node ./node_modules/@gradial/aci/src/cli/emit-error-pages.mjs <prepare|emit>
+// Code-build error artifacts. prepare transports code-owned analytics policy;
+// emit writes a content-independent static 500. Authored error-page bindings
+// and rendering belong to content preview/publish, never the framework build.
+// Usage: emit-error-pages.mjs <prepare|emit>
 
-import { execFileSync, spawn } from 'node:child_process';
 import fs from 'node:fs';
-import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const MARKER = '<!-- aci:error-pages generated -->';
 const SIZE_BUDGET = 150 * 1024;
-const BOOT_DEADLINE_MS = 60_000;
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const siteRoot = process.cwd();
@@ -76,9 +18,6 @@ const contentRoot = path.resolve(siteRoot, process.env.ACI_CONTENT_ROOT || '.aci
 function log(message) {
   console.log(`[aci error-pages] ${message}`);
 }
-function warn(message) {
-  console.warn(`\n[aci error-pages] WARNING: ${message}\n`);
-}
 function fail(message) {
   console.error(`\n[aci error-pages] ERROR: ${message}\n`);
   process.exit(1);
@@ -88,181 +27,12 @@ async function sdkContent() {
   return await import(pathToFileURL(path.join(packageRoot, 'dist', 'content', 'index.js')).href);
 }
 
-function hasCompiledContent() {
-  return fs.existsSync(path.join(contentRoot, 'manifest.json'));
-}
-
-// ---------------------------------------------------------------------------
-// prepare
-// ---------------------------------------------------------------------------
-
-// Retain the deployed transport path for SDK-first upgrades. This file is
-// executable policy, not a compiled page snapshot; do not compile content here.
-export async function prepareCodeArtifact(root = siteRoot, content) {
+// Keep the existing capsule transport path for SDK-first upgrades. This file
+// is executable policy, not a compiled content snapshot.
+export async function prepare(root = siteRoot, content) {
   return writeInstrumentationArtifact(root, content, path.join(root, '.aci', 'compiled'));
 }
 
-async function prepare() {
-  if (process.env.ACI_CODE_ARTIFACT_BUILD === '1') {
-    // Code artifacts carry executable policy only. The selected content and
-    // its error-page bindings belong to preview/publish, never this build.
-    await prepareCodeArtifact();
-    return;
-  }
-  if (hasCompiledContent()) {
-    log(`compiled content present at ${contentRoot}`);
-  } else {
-    const authored = path.join(siteRoot, '.content');
-    if (!fs.existsSync(authored)) {
-      warn(
-        `neither compiled content (${contentRoot}) nor authored content (./.content) exists; `
-        + 'the error seat and 500.html will serve the shipped default page (REQ-4)',
-      );
-    } else {
-      log('compiling ./.content for the error-page build steps');
-      execFileSync(
-        'node',
-        [path.join(packageRoot, 'bin', 'aci.js'), 'content', 'compile', '--content', authored, '--out', contentRoot],
-        { cwd: siteRoot, stdio: 'inherit' },
-      );
-    }
-  }
-  // D-16: the instrumentation artifact rides the compiled content root into
-  // the AWS-lane code capsule (source/.aci/compiled/**). Written even when
-  // content is absent — the tenant policy module is independent of authored
-  // content, and an artifact the Go materializer never receives silently
-  // degrades to the default tags (the exact gap D-16 closes).
-  try {
-    await writeInstrumentationArtifact();
-  } catch (error) {
-    fail(error.message);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// emit
-// ---------------------------------------------------------------------------
-
-async function resolveCatchAllRoute() {
-  const { resolveErrorPageBindings, defaultErrorPageHtml, errorPagePostureFromEnv } = await sdkContent();
-  // D-5 posture: the one shared config surface (ACI_ERROR_PAGES_POSTURE);
-  // unknown values fail closed here just like the Go stack.
-  let posture;
-  try {
-    posture = errorPagePostureFromEnv();
-  } catch (error) {
-    fail(error.message);
-  }
-  if (!hasCompiledContent()) {
-    if (posture === 'enforce') {
-      fail(`no compiled content at ${contentRoot}; the enforce posture fails closed (D-5)`);
-    }
-    warn(`no compiled content at ${contentRoot}; emitting the shipped default 500.html (REQ-4)`);
-    return { route: null, defaultHtml: defaultErrorPageHtml() };
-  }
-  const { FileContentProvider } = await import(
-    pathToFileURL(path.join(packageRoot, 'dist', 'providers', 'file.js')).href
-  );
-  const provider = new FileContentProvider(contentRoot);
-  const siteConfig = await provider.getSiteConfig();
-  const resolution = await resolveErrorPageBindings(siteConfig, { source: provider, posture });
-  if (resolution.errors.length > 0) {
-    fail(`errorPages bindings are invalid (REQ-5, fail closed):\n- ${resolution.errors.join('\n- ')}`);
-  }
-  for (const warning of resolution.warnings) warn(warning);
-  if (resolution.defaulted || !resolution.bindings) {
-    return { route: null, defaultHtml: defaultErrorPageHtml() };
-  }
-  return { route: resolution.bindings.catchAll, defaultHtml: defaultErrorPageHtml() };
-}
-
-async function freePort() {
-  return new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on('error', reject);
-    server.listen(0, '127.0.0.1', () => {
-      const { port } = server.address();
-      server.close(() => resolve(port));
-    });
-  });
-}
-
-async function fetchRenderedRoute(route) {
-  const serverPath = path.join(siteRoot, '.next', 'standalone', 'server.js');
-  if (!fs.existsSync(serverPath)) {
-    fail(`${serverPath} missing — the emit phase must run after \`next build\` (withAci uses standalone output)`);
-  }
-  const port = await freePort();
-  const logChunks = [];
-  const child = spawn('node', [serverPath], {
-    cwd: siteRoot,
-    detached: true,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: {
-      ...process.env,
-      NODE_ENV: 'production',
-      PORT: String(port),
-      HOSTNAME: '127.0.0.1',
-      ACI_CONTENT_PROVIDER: 'file',
-      ACI_CONTENT_ROOT: contentRoot,
-    },
-  });
-  child.stdout.on('data', (c) => logChunks.push(String(c)));
-  child.stderr.on('data', (c) => logChunks.push(String(c)));
-  const exited = new Promise((resolve) => {
-    child.on('exit', resolve);
-    child.on('error', (error) => {
-      logChunks.push(`spawn failed: ${error.message}\n`);
-      resolve(null);
-    });
-  });
-
-  try {
-    const url = `http://127.0.0.1:${port}${route}`;
-    const start = Date.now();
-    let last = 'no attempt made';
-    while (Date.now() - start < BOOT_DEADLINE_MS) {
-      try {
-        const response = await fetch(url, { redirect: 'follow' });
-        if (response.status === 200) return await response.text();
-        last = `status ${response.status}`;
-      } catch (error) {
-        last = error.message;
-      }
-      await new Promise((r) => setTimeout(r, 500));
-    }
-    fail(`GET ${url} did not render within ${BOOT_DEADLINE_MS}ms (last: ${last})\n--- server output ---\n${logChunks.join('').slice(-4000)}`);
-    return '';
-  } finally {
-    const killGroup = (signal) => {
-      if (!child.pid) return;
-      try { process.kill(-child.pid, signal); } catch { /* gone */ }
-    };
-    killGroup('SIGTERM');
-    const killTimer = setTimeout(() => killGroup('SIGKILL'), 10_000);
-    await exited;
-    clearTimeout(killTimer);
-    killGroup('SIGKILL');
-  }
-}
-
-function inlineStylesheets(html) {
-  return html.replace(/<link\b[^>]*rel="stylesheet"[^>]*>/gi, (tag) => {
-    const href = tag.match(/href="([^"]+)"/i)?.[1];
-    if (!href || !href.startsWith('/_next/')) {
-      warn(`dropping non-inlinable stylesheet ${href ?? '<unknown>'} from 500.html (self-containment, REQ-14)`);
-      return '';
-    }
-    const cssPath = path.join(siteRoot, '.next', href.replace(/^\/_next\//, ''));
-    if (!fs.existsSync(cssPath)) {
-      warn(`stylesheet ${href} not found in .next output; dropping it from 500.html`);
-      return '';
-    }
-    return `<style>${fs.readFileSync(cssPath, 'utf8')}</style>`;
-  });
-}
-
 // Relative convention path of the tenant-owned instrumentation policy
 // module (D-15, code-organization R-14).
 const INSTRUMENTATION_MODULE = path.join('src', 'aci', 'error-page-instrumentation.mjs');
@@ -372,47 +142,17 @@ export function stampInstrumentation(html, instrumentationTag) {
   return stamped;
 }
 
-function postProcess(html, instrumentationTag) {
-  let out = html;
-  // Strip every script tag: framework runtime chunks are dead weight in a
-  // statically served copy, and this removes the collect script and the
-  // data-aci-assignments tag (REQ-11) in one sweep.
-  out = out.replace(/<script\b[\s\S]*?<\/script>/gi, '');
-  out = out.replace(/<link\b[^>]*rel="(?:preload|modulepreload|prefetch)"[^>]*>/gi, '');
-  out = inlineStylesheets(out);
-  return stampInstrumentation(out, instrumentationTag);
-}
-
-async function emit() {
-  const publicDir = path.join(siteRoot, 'public');
+export async function emit(root = siteRoot, content) {
+  const publicDir = path.join(root, 'public');
   const target = path.join(publicDir, '500.html');
   if (fs.existsSync(target) && !fs.readFileSync(target, 'utf8').includes(MARKER)) {
     log('public/500.html already provided by the site; leaving it untouched (skip-if-present)');
     return;
   }
 
-  const { route, defaultHtml } = process.env.ACI_CODE_ARTIFACT_BUILD === '1'
-    ? { route: null, defaultHtml: (await sdkContent()).defaultErrorPageHtml() }
-    : await resolveCatchAllRoute();
-  let instrumentationTag;
-  try {
-    instrumentationTag = await resolveInstrumentationTag();
-  } catch (error) {
-    fail(error.message);
-  }
-  let html;
-  try {
-    if (!route) {
-      // The shipped default is already self-contained; it gets the same
-      // instrumentation-plus-marker append used for rendered pages.
-      html = stampInstrumentation(defaultHtml, instrumentationTag);
-    } else {
-      log(`rendering bound catchAll page ${route} for public/500.html`);
-      html = postProcess(await fetchRenderedRoute(route), instrumentationTag);
-    }
-  } catch (error) {
-    fail(error.message);
-  }
+  const sdk = content ?? (await sdkContent());
+  const instrumentationTag = await resolveInstrumentationTag(root, sdk);
+  const html = stampInstrumentation(sdk.defaultErrorPageHtml(), instrumentationTag);
 
   const size = Buffer.byteLength(html);
   if (size > SIZE_BUDGET) {
@@ -424,7 +164,7 @@ async function emit() {
 
   fs.mkdirSync(publicDir, { recursive: true });
   fs.writeFileSync(target, html);
-  log(`wrote public/500.html (${size} bytes${route ? `, from ${route}` : ', shipped default'})`);
+  log(`wrote public/500.html (${size} bytes, shipped default)`);
 }
 
 // Run only when executed as a CLI — the module is also imported by unit

package/src/types/component.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { aciRootAttrs } from './component.js';
+
+test('aciRootAttrs returns exactly the two root identity keys (sdk D-9)', () => {
+  const props = {
+    'data-aci-block': 'hero-1',
+    'data-aci-component': 'hero',
+    title: 'Ship pages faster',
+    className: 'leak',
+  };
+  assert.deepEqual(aciRootAttrs(props), {
+    'data-aci-block': 'hero-1',
+    'data-aci-component': 'hero',
+  });
+});

package/src/types/component.ts

@@ -25,14 +25,29 @@ export interface ComponentValidationIssue {
 
 /**
  * Root identity props the SDK renderers inject into every page and fragment
- * block (sdk I-19, ADR 0051). A component spreads them onto its own root
- * element; the starter conformance test fails a component that drops them.
+ * block (sdk I-31, ADR 0051). A component places them on its own root
+ * element with `{...aciRootAttrs(props)}` or a rest-spread; the conformance
+ * check fails a component that drops them (ADR 0063).
  */
-export interface RootIdentityProps {
+export interface AciRootProps {
   'data-aci-block'?: string;
   'data-aci-component'?: string;
 }
 
+/** The former name of {@link AciRootProps} (sdk D-9). */
+export type RootIdentityProps = AciRootProps;
+
+/**
+ * Exactly the {@link AciRootProps} keys of `props`, for the root element:
+ * `<section {...aciRootAttrs(props)}>`. Nothing else in `props` leaks.
+ */
+export function aciRootAttrs(props: AciRootProps): AciRootProps {
+  return {
+    'data-aci-block': props['data-aci-block'],
+    'data-aci-component': props['data-aci-component'],
+  };
+}
+
 export interface ComponentDefinition<TId extends string = string, TSchema = unknown> {
   id: TId;
   displayName?: string;

package/templates/astro/starter-content/src/components/chrome/Footer.astro

@@ -1,6 +1,6 @@
 ---
 import Container from '../elements/Container.astro';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import Logo from '../elements/Logo.astro';
 
 interface FooterLink {
@@ -22,7 +22,7 @@ interface FooterColumn {
   links?: FooterLink[];
 }
 
-interface Props extends RootIdentityProps {
+interface Props extends AciRootProps {
   brandHref: string;
   brandLabel?: string;
   brandLogo?: { src: string; alt?: string } | null;
@@ -40,7 +40,6 @@ const {
   columns = [],
   legalLinks = [],
   copyright = '',
-  ...root
 } = Astro.props;
 
 function columnGroups(column: FooterColumn): FooterGroup[] {
@@ -56,7 +55,7 @@ function columnGroups(column: FooterColumn): FooterGroup[] {
 }
 ---
 
-<footer {...root} class="bm-footer [font-family:var(--font-family-base)] text-fg" id="footer">
+<footer {...aciRootAttrs(Astro.props)} class="bm-footer [font-family:var(--font-family-base)] text-fg" id="footer">
   <Container className="py-[var(--spacing-footer-y)]">
     <div class="grid gap-12 pb-24 md:grid-cols-[var(--footer-grid-columns)] lg:gap-24">
       <a href={brandHref} class="self-start">

package/templates/astro/starter-content/src/components/chrome/Header.astro

@@ -1,6 +1,6 @@
 ---
 import Button from '../elements/Button.astro';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import Container from '../elements/Container.astro';
 import Icon from '../elements/Icon.astro';
 import Logo from '../elements/Logo.astro';
@@ -15,7 +15,7 @@ interface UtilityItem extends NavItem {
   variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
 }
 
-interface Props extends RootIdentityProps {
+interface Props extends AciRootProps {
   brandHref: string;
   brandLabel?: string;
   brandLogo?: { src: string; alt?: string } | null;
@@ -29,11 +29,10 @@ const {
   brandLogo = null,
   navigation = [],
   utilities = [],
-  ...root
 } = Astro.props;
 ---
 
-<header {...root} class="bm-header sticky top-0 z-[var(--z-header)] [font-family:var(--font-family-base)] text-fg">
+<header {...aciRootAttrs(Astro.props)} class="bm-header sticky top-0 z-[var(--z-header)] [font-family:var(--font-family-base)] text-fg">
   <a
     href="#content-main"
     class="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-10 focus:rounded-button focus:bg-white focus:px-4 focus:py-2 focus:text-black"

package/templates/astro/starter-content/src/components/elements/Button.astro

@@ -1,7 +1,7 @@
 ---
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 
-interface Props extends RootIdentityProps {
+interface Props extends AciRootProps {
   href: string;
   variant?: 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost';
   className?: string;
@@ -9,7 +9,7 @@ interface Props extends RootIdentityProps {
   rel?: string;
 }
 
-const { href, variant = 'primary', className = '', target, rel, ...root } = Astro.props;
+const { href, variant = 'primary', className = '', target, rel } = Astro.props;
 
 const variantTokens = {
   primary: {
@@ -43,7 +43,7 @@ const tokenStyle = `background-color: ${variantTokens.background}; border-color:
 ---
 
 <a
-  {...root}
+  {...aciRootAttrs(Astro.props)}
   class={`inline-flex min-h-10 items-center justify-center rounded-button border px-[var(--spacing-button-x)] py-[var(--spacing-button-y)] [font-family:var(--font-family-base)] text-[length:var(--text-button)] font-[var(--font-weight-semibold)] leading-button transition duration-200 hover:opacity-85 ${className}`}
   href={href}
   target={target}

package/templates/astro/starter-content/src/components/elements/ButtonBlock.astro

@@ -1,10 +1,10 @@
 ---
 import Button from '../elements/Button.astro';
 import Icon from '../elements/Icon.astro';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { ContentProps } from '../../cms/contracts/components/button.contract';
 
-type Props = ContentProps & RootIdentityProps;
+type Props = ContentProps & AciRootProps;
 
 const {
   label,
@@ -14,13 +14,12 @@ const {
   icon = '',
   iconPosition = 'before',
   className = '',
-  ...root
 } = Astro.props;
 const target = newWindow ? '_blank' : undefined;
 const rel = newWindow ? 'noreferrer' : undefined;
 ---
 
-<Button {href} {variant} {target} {rel} {className} {...root}>
+<Button {href} {variant} {target} {rel} {className} {...aciRootAttrs(Astro.props)}>
   {icon && iconPosition === 'before' ? <Icon name={icon} className="mr-2 size-4" /> : null}
   <span>{label}</span>
   {icon && iconPosition === 'after' ? <Icon name={icon} className="ml-2 size-4" /> : null}

package/templates/astro/starter-content/src/components/sections/ContainerSection.astro

@@ -1,16 +1,16 @@
 ---
 import Container from '../elements/Container.astro';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { RenderChildren, RenderableBlock } from '@gradial/aci/astro';
 
-interface Props extends RootIdentityProps {
+interface Props extends AciRootProps {
   theme?: 'auto' | 'light' | 'dark';
   className?: string;
   content?: any[];
   renderChildren?: RenderChildren;
 }
 
-const { theme = 'auto', className = '', content, renderChildren, ...root } = Astro.props;
+const { theme = 'auto', className = '', content, renderChildren } = Astro.props;
 const children: RenderableBlock[] = content && renderChildren ? renderChildren(content) : [];
 const buttonCount = content?.filter((b: any) => b.component === 'button').length ?? 0;
 const layout = buttonCount === 1
@@ -18,7 +18,7 @@ const layout = buttonCount === 1
   : 'flex-col items-center sm:flex-row sm:justify-center sm:gap-4';
 ---
 
-<section {...root} class={`theme-${theme} relative overflow-hidden py-[var(--spacing-section-y)] ${className}`}>
+<section {...aciRootAttrs(Astro.props)} class={`theme-${theme} relative overflow-hidden py-[var(--spacing-section-y)] ${className}`}>
   {theme === 'dark' ? (
     <div class="pointer-events-none absolute inset-0 bg-[image:var(--gradient-hero-base)] opacity-30"></div>
   ) : null}

package/templates/astro/starter-content/src/components/sections/FeatureCard.astro

@@ -1,17 +1,17 @@
 ---
 import Icon from '../elements/Icon.astro';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 
-interface Props extends RootIdentityProps {
+interface Props extends AciRootProps {
   icon?: string;
   title: string;
   description?: string;
 }
 
-const { icon = '', title = '', description = '', ...root } = Astro.props;
+const { icon = '', title = '', description = '' } = Astro.props;
 ---
 
-<div {...root} class="rounded-card border border-[var(--color-edge-space)] bg-[var(--color-space-surface)] p-[var(--spacing-card)] transition-all duration-[var(--transition-duration-fast)] hover:border-[var(--color-edge-space-strong)] hover:bg-[var(--color-space-raised)] hover:shadow-[var(--shadow-card-default)]">
+<div {...aciRootAttrs(Astro.props)} class="rounded-card border border-[var(--color-edge-space)] bg-[var(--color-space-surface)] p-[var(--spacing-card)] transition-all duration-[var(--transition-duration-fast)] hover:border-[var(--color-edge-space-strong)] hover:bg-[var(--color-space-raised)] hover:shadow-[var(--shadow-card-default)]">
   {icon ? (
     <div class="mb-6 flex h-12 w-12 items-center justify-center rounded-button bg-[color-mix(in_srgb,var(--color-brand-blue)_12%,transparent)] text-[var(--color-brand-blue-light)]">
       <Icon name={icon} className="h-6 w-6" />

package/templates/astro/starter-content/src/components/sections/FeatureGrid.astro

@@ -1,22 +1,22 @@
 ---
 import Container from '../elements/Container.astro';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { RenderChildren, RenderableBlock } from '@gradial/aci/astro';
 
-interface Props extends RootIdentityProps {
+interface Props extends AciRootProps {
   title?: string;
   subtitle?: string;
   features?: any[];
   renderChildren?: RenderChildren;
 }
 
-const { title = '', subtitle = '', features, renderChildren, ...root } = Astro.props;
+const { title = '', subtitle = '', features, renderChildren } = Astro.props;
 const children: RenderableBlock[] = features && renderChildren ? renderChildren(features) : [];
 const count = features?.length ?? 0;
 const cols = count <= 2 ? 'sm:grid-cols-2' : 'sm:grid-cols-2 lg:grid-cols-3';
 ---
 
-<section {...root} class="theme-dark py-[var(--spacing-section-y)] bg-[var(--color-space-deep)]">
+<section {...aciRootAttrs(Astro.props)} class="theme-dark py-[var(--spacing-section-y)] bg-[var(--color-space-deep)]">
   <Container>
     <div class="mb-12 max-w-[var(--max-width-container-narrow)]">
       {title ? (

package/templates/astro/starter-content/src/components/sections/HomeHero.astro

@@ -1,9 +1,9 @@
 ---
 import Button from '../elements/Button.astro';
 import Container from '../elements/Container.astro';
-import { imageAttrs, type Image, type RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, imageAttrs, type Image, type AciRootProps } from '@gradial/aci';
 
-interface Props extends RootIdentityProps {
+interface Props extends AciRootProps {
   eyebrow?: string;
   headline: string;
   description?: string;
@@ -19,7 +19,6 @@ const {
   ctaLabel,
   ctaHref,
   image,
-  ...root
 } = Astro.props;
 
 const imgAttrs = image ? imageAttrs(image, {
@@ -30,7 +29,7 @@ const imgAttrs = image ? imageAttrs(image, {
 ---
 
 <section
-  {...root}
+  {...aciRootAttrs(Astro.props)}
   class="theme-dark relative min-h-[var(--height-hero-min)] overflow-hidden bg-black text-fg"
   aria-label={image?.alt || headline}
 >

package/templates/astro/starter-content/src/components/sections/PersonalizationChoice.astro

@@ -1,13 +1,13 @@
 ---
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 import type { ContentProps } from '../../cms/contracts/components/personalizationChoice.contract';
 
-type Props = ContentProps & RootIdentityProps;
+type Props = ContentProps & AciRootProps;
 
-const { title, description, redLabel, blueLabel, refreshLabel, ...root } = Astro.props;
+const { title, description, redLabel, blueLabel, refreshLabel } = Astro.props;
 ---
 
-<section {...root} class="border-y border-[var(--color-border)] bg-[var(--color-surface)] py-[var(--spacing-section-y)]">
+<section {...aciRootAttrs(Astro.props)} class="border-y border-[var(--color-border)] bg-[var(--color-surface)] py-[var(--spacing-section-y)]">
   <div class="mx-auto max-w-[var(--layout-content-max)] px-[var(--layout-gutter)] text-center">
     <h2 class="text-[length:var(--text-h2)] font-[var(--font-weight-semibold)] text-[var(--color-fg)]">{title}</h2>
     {description ? <p class="mx-auto mt-3 max-w-2xl text-[var(--color-fg-muted)]">{description}</p> : null}

package/templates/astro/starter-content/src/components/sections/StatsBar.astro

@@ -1,6 +1,6 @@
 ---
 import Container from '../elements/Container.astro';
-import type { RootIdentityProps } from '@gradial/aci';
+import { aciRootAttrs, type AciRootProps } from '@gradial/aci';
 
 interface Stat {
   label: string;
@@ -8,14 +8,14 @@ interface Stat {
   suffix?: string;
 }
 
-interface Props extends RootIdentityProps {
+interface Props extends AciRootProps {
   stats?: Stat[];
 }
 
-const { stats = [], ...root } = Astro.props;
+const { stats = [] } = Astro.props;
 ---
 
-<section {...root} class="theme-dark border-y border-[var(--color-edge-space)] bg-[var(--color-space-surface)] py-[var(--spacing-section-y)]">
+<section {...aciRootAttrs(Astro.props)} class="theme-dark border-y border-[var(--color-edge-space)] bg-[var(--color-space-surface)] py-[var(--spacing-section-y)]">
   <Container>
     <div class="grid gap-8 sm:grid-cols-2 lg:grid-cols-4">
       {stats.map((stat) => (