@gradial/aci 0.1.52-rc.21 → 0.1.52-rc.24

package/dist/testing/conformance/root-identity.js

@@ -0,0 +1,380 @@
+/**
+ * Conformance check: rootIdentity (ADR 0051).
+ *
+ * The ACI renderer passes every block `data-aci-block` and
+ * `data-aci-component` as props; a component must spread them onto the
+ * element it returns. The registry type constraint proves a component
+ * declares the props. This check proves it renders them, by rendering every
+ * registered component through the SDK's own seam and reading the root of
+ * the markup.
+ *
+ * Next: components are rendered with react-dom/server from the site's own
+ * node_modules; next/link and next/image are stubbed (see next-stubs.ts)
+ * because their CommonJS interop objects cannot render outside Next.
+ * Astro: components cannot be rendered outside Astro, so the built site's
+ * HTML is scanned for every authored block id instead (building first when
+ * `dist/` is absent).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { execSync } from 'node:child_process';
+const CHECK = 'rootIdentity';
+const LABEL = 'components render data-aci-block on their root element';
+// ---------------------------------------------------------------------------
+// Pure core (unit-tested with in-memory registries)
+// ---------------------------------------------------------------------------
+/**
+ * Render each block through the SDK renderer and report every component
+ * whose root element lacks the identity attributes. `blocks` are the blocks
+ * to exercise; registry entries not covered by a block are probed with empty
+ * props so an unused component cannot hide a forgotten spread.
+ */
+export async function findRootIdentityFailures(registry, blocks, react, fileFor = () => undefined) {
+    const { renderBlock } = await import('../../next/render.js');
+    const failures = new Map();
+    const covered = new Set();
+    const probe = async (block, contentBacked) => {
+        if (failures.has(block.component))
+            return;
+        const element = await renderBlock(block, registry);
+        let html;
+        try {
+            html = await markupFor(element, react);
+        }
+        catch (err) {
+            // A component the content never uses is probed with empty props; if it
+            // needs real props to render, that proves nothing about identity, so
+            // it is skipped rather than reported. Content-backed renders that
+            // throw are real failures.
+            if (!contentBacked)
+                return;
+            failures.set(block.component, {
+                component: block.component,
+                file: fileFor(block.component),
+                missing: [`render threw: ${err instanceof Error ? err.message : String(err)}`],
+            });
+            return;
+        }
+        const root = rootAttributes(html);
+        const missing = [];
+        if (root.block !== block.id)
+            missing.push('data-aci-block');
+        if (root.component !== block.component)
+            missing.push('data-aci-component');
+        if (missing.length > 0) {
+            failures.set(block.component, { component: block.component, file: fileFor(block.component), missing });
+        }
+    };
+    for (const block of blocks) {
+        if (!registry.some((entry) => entry.id === block.component))
+            continue;
+        covered.add(block.component);
+        await probe(block, true);
+    }
+    for (const entry of registry) {
+        if (covered.has(entry.id))
+            continue;
+        await probe({ $type: 'component', id: `probe-${entry.id}`, component: entry.id, props: {} }, false);
+    }
+    return [...failures.values()];
+}
+/** The failure message: one line of what, the list, one line of fix. */
+export function formatRootIdentityFailures(failures, framework) {
+    const width = Math.max(...failures.map((f) => f.component.length), 0);
+    const lines = failures.map((f) => {
+        const note = f.missing.length === 1 && f.missing[0].startsWith('data-aci-') && f.missing[0] !== 'data-aci-block'
+            ? `(missing ${f.missing[0]})`
+            : f.missing[0]?.startsWith('render threw') ? `(${f.missing[0]})` : '';
+        return ['  ' + f.component.padEnd(width), f.file, note].filter(Boolean).join('  ');
+    });
+    const fix = framework === 'next'
+        ? [
+            'Fix: extend RootIdentityProps and spread the rest props onto the root:',
+            '  function StatsBar({ stats, ...root }: StatsBarProps) { return <section {...root} …',
+        ]
+        : [
+            'Fix: extend RootIdentityProps and spread the rest props onto the root:',
+            '  const { stats, ...root } = Astro.props;   <section {...root} …',
+        ];
+    return [
+        `${CHECK}: ${failures.length} component${failures.length === 1 ? '' : 's'} do${failures.length === 1 ? 'es' : ''} not render data-aci-block on their root element`,
+        '',
+        ...lines,
+        '',
+        ...fix,
+    ].join('\n');
+}
+/**
+ * Slot components are async server components in Next; react-dom/server
+ * cannot render those, so the element the SDK produced is unwrapped by
+ * awaiting the component function directly.
+ */
+async function markupFor(element, react) {
+    const el = element;
+    const type = el.type;
+    if (typeof type === 'function' && type.constructor?.name === 'AsyncFunction') {
+        const resolved = await type(el.props);
+        return react.renderToStaticMarkup(resolved);
+    }
+    return react.renderToStaticMarkup(element);
+}
+function rootAttributes(html) {
+    // react-dom hoists resource hints (<link rel="preload">, <meta>) ahead of
+    // the component's markup; they are not the root element.
+    const body = html.trim().replace(/^(?:<(?:link|meta)\b[^>]*\/?>\s*)+/i, '');
+    const root = /^<([a-z][a-z0-9-]*)([^>]*)>/i.exec(body);
+    if (!root)
+        return {};
+    const attrs = root[2];
+    return {
+        block: /\sdata-aci-block="([^"]*)"/.exec(attrs)?.[1],
+        component: /\sdata-aci-component="([^"]*)"/.exec(attrs)?.[1],
+    };
+}
+// ---------------------------------------------------------------------------
+// Site integration
+// ---------------------------------------------------------------------------
+export async function checkRootIdentity(ctx) {
+    return ctx.framework === 'next' ? checkNextRootIdentity(ctx) : checkAstroRootIdentity(ctx);
+}
+async function checkNextRootIdentity(ctx) {
+    const registryFile = findRegistryFile(ctx.rootDir);
+    if (!registryFile) {
+        return [fail(`${CHECK}: no registry file imports createRegistry from @gradial/aci`)];
+    }
+    const siteRequire = createRequire(join(ctx.rootDir, 'package.json'));
+    let react;
+    try {
+        react = siteRequire('react-dom/server');
+        // The site's tsconfig may keep `jsx: preserve` for Next, in which case
+        // the test transform emits classic React.createElement calls.
+        globalThis.React = siteRequire('react');
+    }
+    catch (err) {
+        return [fail(`${CHECK}: cannot load react-dom/server from the site (${err instanceof Error ? err.message : String(err)})`)];
+    }
+    const { register } = await import('node:module');
+    register(stubHookURL());
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(registryFile).href));
+    }
+    catch (err) {
+        return [fail(`${CHECK}: cannot load ${relative(ctx.rootDir, registryFile)} (${err instanceof Error ? err.message : String(err)})`)];
+    }
+    const registry = Object.values(mod).find(isRegistry);
+    if (!registry) {
+        return [fail(`${CHECK}: ${relative(ctx.rootDir, registryFile)} does not export the createRegistry result`)];
+    }
+    const source = readFileSync(registryFile, 'utf8');
+    const failures = await findRootIdentityFailures(registry, compiledBlocks(ctx.rootDir), react, componentFileResolver(source, registry));
+    if (failures.length === 0) {
+        return [ok(`${registry.length} registered components`)];
+    }
+    return [fail(formatRootIdentityFailures(failures, 'next'))];
+}
+async function checkAstroRootIdentity(ctx) {
+    const distDir = join(ctx.rootDir, 'dist');
+    if (!existsSync(distDir) || distIsStale(distDir, [join(ctx.rootDir, 'src'), join(ctx.rootDir, '.content')])) {
+        try {
+            execSync('npm run build', { cwd: ctx.rootDir, stdio: 'pipe', timeout: 300_000, env: { ...process.env, NODE_ENV: 'production' } });
+        }
+        catch (err) {
+            const stderr = err instanceof Error && 'stderr' in err ? String(err.stderr).slice(0, 500) : String(err);
+            return [fail(`${CHECK}: npm run build failed, cannot scan dist/ (${stderr})`)];
+        }
+    }
+    const authored = astroAuthoredBlocks(join(ctx.rootDir, '.content'));
+    if (authored.length === 0) {
+        return [fail(`${CHECK}: no authored blocks found under .content/pages`)];
+    }
+    const html = walkHTML(distDir).map((file) => readFileSync(file, 'utf8')).join('\n');
+    const missing = authored.filter(({ id, component }) => {
+        const pattern = new RegExp(`<[a-z][^>]*(?:data-aci-block="${escapeRegExp(id)}"[^>]*data-aci-component="${escapeRegExp(component)}"` +
+            `|data-aci-component="${escapeRegExp(component)}"[^>]*data-aci-block="${escapeRegExp(id)}")`);
+        return !pattern.test(html);
+    });
+    if (missing.length === 0) {
+        return [ok(`${authored.length} authored blocks found on component roots in dist/`)];
+    }
+    const byComponent = new Map();
+    for (const m of missing) {
+        if (!byComponent.has(m.component))
+            byComponent.set(m.component, { component: m.component, missing: ['data-aci-block'] });
+    }
+    return [fail(formatRootIdentityFailures([...byComponent.values()], 'astro'))];
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** The stub hook next to this module: compiled `.js` in dist, `.ts` when run from source. */
+function stubHookURL() {
+    const js = new URL('./next-stubs.js', import.meta.url);
+    if (existsSync(fileURLToPath(js)))
+        return js;
+    return new URL('./next-stubs.ts', import.meta.url);
+}
+function ok(detail) {
+    return { name: CHECK, label: LABEL, ok: true, detail };
+}
+// A failure's label is the message itself so the test runner prints it
+// without a generic prefix; the check name is the first word of the message.
+function fail(message) {
+    return { name: CHECK, label: message, ok: false };
+}
+function isRegistry(value) {
+    return Array.isArray(value) && value.length > 0
+        && value.every((e) => e && typeof e === 'object' && typeof e.id === 'string' && 'component' in e && 'contract' in e);
+}
+function findRegistryFile(rootDir) {
+    const skip = new Set(['node_modules', '.next', '.aci', 'dist', '.git', 'tests']);
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') && entry.name !== '.')
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (skip.has(entry.name))
+                    continue;
+                const found = walk(full);
+                if (found)
+                    return found;
+            }
+            else if (/\.(ts|tsx|js|mjs)$/.test(entry.name) && readFileSync(full, 'utf8').includes('createRegistry(')) {
+                return full;
+            }
+        }
+        return undefined;
+    };
+    return walk(rootDir);
+}
+/** Map a registered component id to the import path the registry file names for it. */
+function componentFileResolver(registrySource, registry) {
+    const imports = new Map();
+    for (const m of registrySource.matchAll(/import\s+(?:\{([^}]*)\}|(\w+))\s+from\s+['"]([^'"]+)['"]/g)) {
+        const names = (m[1] ?? m[2]).split(',').map((n) => n.trim().split(/\s+as\s+/).pop()).filter(Boolean);
+        for (const name of names)
+            imports.set(name, m[3]);
+    }
+    const byId = new Map();
+    for (const entry of registry) {
+        const fn = entry.component;
+        const file = typeof fn === 'function' && fn.name ? imports.get(fn.name) : undefined;
+        if (file)
+            byId.set(entry.id, file);
+    }
+    return (component) => byId.get(component);
+}
+/** Blocks from the site's compiled content, when `npm run content:compile` has run. */
+function compiledBlocks(rootDir) {
+    const compiled = join(rootDir, '.aci', 'compiled');
+    if (!existsSync(compiled))
+        return [];
+    const blocks = [];
+    const routes = join(compiled, 'routes');
+    if (existsSync(routes)) {
+        for (const file of walkJSON(routes)) {
+            const doc = JSON.parse(readFileSync(file, 'utf8'));
+            for (const region of Object.values(doc.regions ?? {}))
+                blocks.push(...region);
+        }
+    }
+    const fragments = join(compiled, 'fragments');
+    if (existsSync(fragments)) {
+        for (const file of walkJSON(fragments)) {
+            const doc = JSON.parse(readFileSync(file, 'utf8'));
+            if (doc.block) {
+                const id = file.slice(fragments.length + 1).replace(/\.json$/, '');
+                blocks.push({ $type: 'component', id, component: doc.block.component, props: doc.block.props });
+            }
+        }
+    }
+    return blocks;
+}
+/**
+ * Every block the Astro scan must find in dist/: page blocks by their own id,
+ * plus fragments (navbar, footer) by fragment id, which is the block id the
+ * renderer synthesizes when a layout slot default places them.
+ */
+export function astroAuthoredBlocks(contentDir) {
+    const out = authoredBlocks(join(contentDir, 'pages'));
+    const fragmentsDir = join(contentDir, 'fragments');
+    if (existsSync(fragmentsDir)) {
+        for (const entry of readdirSync(fragmentsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const file = join(fragmentsDir, entry.name, '_index.json');
+            if (!existsSync(file))
+                continue;
+            const doc = JSON.parse(readFileSync(file, 'utf8'));
+            const component = doc.block?.component;
+            if (typeof component === 'string' && component !== '') {
+                out.push({ id: doc.fragmentId ?? entry.name, component });
+            }
+        }
+    }
+    return out;
+}
+/** dist/ is stale when any source or content file is newer than its newest output. */
+function distIsStale(distDir, inputs) {
+    const newest = (dir) => {
+        if (!existsSync(dir))
+            return 0;
+        let max = 0;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            max = Math.max(max, entry.isDirectory() ? newest(full) : statSync(full).mtimeMs);
+        }
+        return max;
+    };
+    const built = newest(distDir);
+    return inputs.some((dir) => newest(dir) > built);
+}
+function authoredBlocks(pagesDir) {
+    if (!existsSync(pagesDir))
+        return [];
+    const out = [];
+    const collect = (value) => {
+        if (Array.isArray(value)) {
+            value.forEach(collect);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const node = value;
+        if (typeof node.component === 'string' && node.props && typeof node.props === 'object' && typeof node.id === 'string' && node.id !== '') {
+            out.push({ id: node.id, component: node.component });
+        }
+        Object.values(node).forEach(collect);
+    };
+    for (const file of walkJSON(pagesDir)) {
+        if (!file.endsWith('_index.json'))
+            continue;
+        const doc = JSON.parse(readFileSync(file, 'utf8'));
+        if (doc.$type === 'page')
+            collect(doc.regions);
+    }
+    return out;
+}
+function walkJSON(dir) {
+    return walkExt(dir, '.json');
+}
+function walkHTML(dir) {
+    return walkExt(dir, '.html');
+}
+function walkExt(dir, ext) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walkExt(full, ext));
+        else if (entry.name.endsWith(ext))
+            out.push(full);
+    }
+    return out;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/testing/conformance/stubs/next-image.d.ts

@@ -0,0 +1,7 @@
+export default function Image({ src, alt, ...rest }: {
+    src: unknown;
+    alt?: string;
+} & Record<string, unknown>): import("react").ReactElement<{
+    src: string;
+    alt: string;
+}, string | import("react").JSXElementConstructor<any>>;

package/dist/testing/conformance/stubs/next-image.js

@@ -0,0 +1,5 @@
+import { createElement } from 'react';
+export default function Image({ src, alt, ...rest }) {
+    const source = typeof src === 'object' && src !== null && 'src' in src ? String(src.src) : String(src);
+    return createElement('img', { src: source, alt: alt ?? '', ...rest });
+}

package/dist/testing/conformance/stubs/next-link.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+export default function Link({ href, children, ...rest }: {
+    href: unknown;
+    children?: ReactNode;
+} & Record<string, unknown>): import("react").ReactElement<{
+    href: string;
+}, string | import("react").JSXElementConstructor<any>>;

package/dist/testing/conformance/stubs/next-link.js

@@ -0,0 +1,4 @@
+import { createElement } from 'react';
+export default function Link({ href, children, ...rest }) {
+    return createElement('a', { href: String(href), ...rest }, children);
+}

package/dist/testing/conformance/types.d.ts

@@ -7,7 +7,7 @@
 /** Supported framework identifiers. */
 export type ConformanceFramework = 'next' | 'astro';
 /** Individual check names that can be enabled/disabled. */
-export type ConformanceCheckName = 'config' | 'registry' | 'pageEntry' | 'middleware' | 'noFileContentProvider' | 'noCustomContent' | 'noRequestTimeAssetRoute' | 'buildSucceeds' | 'contentCompile' | 'sdkVersion';
+export type ConformanceCheckName = 'config' | 'registry' | 'pageEntry' | 'middleware' | 'noFileContentProvider' | 'noCustomContent' | 'noRequestTimeAssetRoute' | 'buildSucceeds' | 'contentCompile' | 'sdkVersion' | 'rootIdentity';
 /**
  * Options for the conformance preset.
  *
@@ -51,7 +51,7 @@ export interface ConformanceResult {
     failures: ConformanceCheckResult[];
 }
 /** A conformance check function. */
-export type ConformanceCheckFn = (ctx: ConformanceContext) => ConformanceCheckResult[];
+export type ConformanceCheckFn = (ctx: ConformanceContext) => ConformanceCheckResult[] | Promise<ConformanceCheckResult[]>;
 /** Context passed to each check function. */
 export interface ConformanceContext {
     framework: ConformanceFramework;

package/dist/testing/index.js

@@ -53,9 +53,9 @@ export class FixtureContentProvider {
         return [...this.pages.entries()]
             .sort(([a], [b]) => a.localeCompare(b))
             .map(([routePath, page]) => ({
-            slug: routePath === '/' ? 'home' : routePath.replace(/^\//, ''),
+            slug: routePath === '/' ? '' : routePath.replace(/^\//, ''),
             path: routePath,
-            payloadRef: `routes/${routePath === '/' ? 'home' : routePath.replace(/^\//, '')}.json`,
+            payloadRef: routePath === '/' ? 'routes/index.json' : `routes/${routePath.replace(/^\//, '')}.json`,
             digest: '',
         }));
     }

package/dist/types/component.d.ts

@@ -18,6 +18,15 @@ export interface ComponentValidationIssue {
     message: string;
     severity?: 'error' | 'warning';
 }
+/**
+ * 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.
+ */
+export interface RootIdentityProps {
+    'data-aci-block'?: string;
+    'data-aci-component'?: string;
+}
 export interface ComponentDefinition<TId extends string = string, TSchema = unknown> {
     id: TId;
     displayName?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.52-rc.21",
+  "version": "0.1.52-rc.24",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -45,6 +45,10 @@
       "types": "./dist/edge/expression-capabilities.v1.d.ts",
       "import": "./dist/edge/expression-capabilities.v1.js"
     },
+    "./mintlify": {
+      "types": "./dist/mintlify/index.d.ts",
+      "import": "./dist/mintlify/index.js"
+    },
     "./providers/file": {
       "types": "./dist/providers/file.d.ts",
       "import": "./dist/providers/file.js"
@@ -155,11 +159,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.21",
-    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.21",
-    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.21",
-    "@gradial/aci-cli-linux-x64": "0.1.52-rc.21",
-    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.21",
-    "@gradial/aci-cli-win32-x64": "0.1.52-rc.21"
+    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.24",
+    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.24",
+    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.24",
+    "@gradial/aci-cli-linux-x64": "0.1.52-rc.24",
+    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.24",
+    "@gradial/aci-cli-win32-x64": "0.1.52-rc.24"
   }
 }

package/src/cli/mintlify-render.mjs

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import { loadCompiledMintlifySource, materializeMintlifySite } from '../../dist/mintlify/index.js';
+
+const [sourceArg, compiledArg, outputArg] = process.argv.slice(2);
+if (!sourceArg || !compiledArg || !outputArg) {
+  throw new Error('Mintlify renderer requires content, compiled, and output directories');
+}
+const source = await loadCompiledMintlifySource(path.resolve(sourceArg), path.resolve(compiledArg));
+await materializeMintlifySite({ ...source, outputDir: path.resolve(outputArg) });

package/src/types/component.ts

@@ -23,6 +23,16 @@ export interface ComponentValidationIssue {
   severity?: 'error' | 'warning';
 }
 
+/**
+ * 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.
+ */
+export interface RootIdentityProps {
+  'data-aci-block'?: string;
+  'data-aci-component'?: string;
+}
+
 export interface ComponentDefinition<TId extends string = string, TSchema = unknown> {
   id: TId;
   displayName?: string;

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

@@ -1,5 +1,6 @@
 ---
 import Container from '../elements/Container.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import Logo from '../elements/Logo.astro';
 
 interface FooterLink {
@@ -21,7 +22,7 @@ interface FooterColumn {
   links?: FooterLink[];
 }
 
-interface Props {
+interface Props extends RootIdentityProps {
   brandHref: string;
   brandLabel?: string;
   brandLogo?: { src: string; alt?: string } | null;
@@ -38,7 +39,8 @@ const {
   social = [],
   columns = [],
   legalLinks = [],
-  copyright = ''
+  copyright = '',
+  ...root
 } = Astro.props;
 
 function columnGroups(column: FooterColumn): FooterGroup[] {
@@ -54,7 +56,7 @@ function columnGroups(column: FooterColumn): FooterGroup[] {
 }
 ---
 
-<footer class="bm-footer [font-family:var(--font-family-base)] text-fg" id="footer">
+<footer {...root} 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,5 +1,6 @@
 ---
 import Button from '../elements/Button.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import Container from '../elements/Container.astro';
 import Icon from '../elements/Icon.astro';
 import Logo from '../elements/Logo.astro';
@@ -14,7 +15,7 @@ interface UtilityItem extends NavItem {
   variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
 }
 
-interface Props {
+interface Props extends RootIdentityProps {
   brandHref: string;
   brandLabel?: string;
   brandLogo?: { src: string; alt?: string } | null;
@@ -27,11 +28,12 @@ const {
   brandLabel = 'Gradial',
   brandLogo = null,
   navigation = [],
-  utilities = []
+  utilities = [],
+  ...root
 } = Astro.props;
 ---
 
-<header class="bm-header sticky top-0 z-[var(--z-header)] [font-family:var(--font-family-base)] text-fg">
+<header {...root} 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,5 +1,7 @@
 ---
-interface Props {
+import type { RootIdentityProps } from '@gradial/aci';
+
+interface Props extends RootIdentityProps {
   href: string;
   variant?: 'primary' | 'secondary' | 'tertiary' | 'outline' | 'ghost';
   className?: string;
@@ -7,7 +9,7 @@ interface Props {
   rel?: string;
 }
 
-const { href, variant = 'primary', className = '', target, rel } = Astro.props;
+const { href, variant = 'primary', className = '', target, rel, ...root } = Astro.props;
 
 const variantTokens = {
   primary: {
@@ -41,6 +43,7 @@ const tokenStyle = `background-color: ${variantTokens.background}; border-color:
 ---
 
 <a
+  {...root}
   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,9 +1,10 @@
 ---
 import Button from '../elements/Button.astro';
 import Icon from '../elements/Icon.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import type { ContentProps } from '../../cms/contracts/components/button.contract';
 
-type Props = ContentProps;
+type Props = ContentProps & RootIdentityProps;
 
 const {
   label,
@@ -12,13 +13,14 @@ const {
   newWindow = false,
   icon = '',
   iconPosition = 'before',
-  className = ''
+  className = '',
+  ...root
 } = Astro.props;
 const target = newWindow ? '_blank' : undefined;
 const rel = newWindow ? 'noreferrer' : undefined;
 ---
 
-<Button {href} {variant} {target} {rel} {className}>
+<Button {href} {variant} {target} {rel} {className} {...root}>
   {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}