@gradial/aci 0.1.52-rc.3 → 0.1.52-rc.34-e2e.1

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}

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

@@ -1,15 +1,16 @@
 ---
 import Container from '../elements/Container.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import type { RenderChildren, RenderableBlock } from '@gradial/aci/astro';
 
-interface Props {
+interface Props extends RootIdentityProps {
   theme?: 'auto' | 'light' | 'dark';
   className?: string;
   content?: any[];
   renderChildren?: RenderChildren;
 }
 
-const { theme = 'auto', className = '', content, renderChildren } = Astro.props;
+const { theme = 'auto', className = '', content, renderChildren, ...root } = Astro.props;
 const children: RenderableBlock[] = content && renderChildren ? renderChildren(content) : [];
 const buttonCount = content?.filter((b: any) => b.component === 'button').length ?? 0;
 const layout = buttonCount === 1
@@ -17,7 +18,7 @@ const layout = buttonCount === 1
   : 'flex-col items-center sm:flex-row sm:justify-center sm:gap-4';
 ---
 
-<section class={`theme-${theme} relative overflow-hidden py-[var(--spacing-section-y)] ${className}`}>
+<section {...root} 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,16 +1,17 @@
 ---
 import Icon from '../elements/Icon.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 
-interface Props {
+interface Props extends RootIdentityProps {
   icon?: string;
   title: string;
   description?: string;
 }
 
-const { icon = '', title = '', description = '' } = Astro.props;
+const { icon = '', title = '', description = '', ...root } = Astro.props;
 ---
 
-<div 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 {...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)]">
   {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,21 +1,22 @@
 ---
 import Container from '../elements/Container.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 import type { RenderChildren, RenderableBlock } from '@gradial/aci/astro';
 
-interface Props {
+interface Props extends RootIdentityProps {
   title?: string;
   subtitle?: string;
   features?: any[];
   renderChildren?: RenderChildren;
 }
 
-const { title = '', subtitle = '', features, renderChildren } = Astro.props;
+const { title = '', subtitle = '', features, renderChildren, ...root } = 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 class="theme-dark py-[var(--spacing-section-y)] bg-[var(--color-space-deep)]">
+<section {...root} 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 } from '@gradial/aci';
+import { imageAttrs, type Image, type RootIdentityProps } from '@gradial/aci';
 
-interface Props {
+interface Props extends RootIdentityProps {
   eyebrow?: string;
   headline: string;
   description?: string;
@@ -18,7 +18,8 @@ const {
   description = '',
   ctaLabel,
   ctaHref,
-  image
+  image,
+  ...root
 } = Astro.props;
 
 const imgAttrs = image ? imageAttrs(image, {
@@ -29,6 +30,7 @@ const imgAttrs = image ? imageAttrs(image, {
 ---
 
 <section
+  {...root}
   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,12 +1,13 @@
 ---
+import type { RootIdentityProps } from '@gradial/aci';
 import type { ContentProps } from '../../cms/contracts/components/personalizationChoice.contract';
 
-type Props = ContentProps;
+type Props = ContentProps & RootIdentityProps;
 
-const { title, description, redLabel, blueLabel, refreshLabel } = Astro.props;
+const { title, description, redLabel, blueLabel, refreshLabel, ...root } = Astro.props;
 ---
 
-<section class="border-y border-[var(--color-border)] bg-[var(--color-surface)] py-[var(--spacing-section-y)]">
+<section {...root} 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,5 +1,6 @@
 ---
 import Container from '../elements/Container.astro';
+import type { RootIdentityProps } from '@gradial/aci';
 
 interface Stat {
   label: string;
@@ -7,14 +8,14 @@ interface Stat {
   suffix?: string;
 }
 
-interface Props {
+interface Props extends RootIdentityProps {
   stats?: Stat[];
 }
 
-const { stats = [] } = Astro.props;
+const { stats = [], ...root } = Astro.props;
 ---
 
-<section class="theme-dark border-y border-[var(--color-edge-space)] bg-[var(--color-space-surface)] py-[var(--spacing-section-y)]">
+<section {...root} 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) => (

package/templates/astro/starter-content/src/fixtures/atomicBlocks.ts

@@ -13,17 +13,18 @@ export const atomicBlockStoryFixtures: AtomicBlockStoryFixture[] = [
     storybookId: 'core-atomic-blocks-button--variants',
     title: 'Button / All Variants',
     block: {
+      $type: 'component',
       id: 'fixture-button-variants',
       component: 'container',
       props: {
         theme: 'auto',
         blocks: [
-          { id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
-          { id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
-          { id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
-          { id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
-          { id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
-          { id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
+          { $type: 'component', id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
+          { $type: 'component', id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
+          { $type: 'component', id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
+          { $type: 'component', id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
+          { $type: 'component', id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
+          { $type: 'component', id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
         ]
       }
     }

package/templates/astro/starter-content/src/fixtures/composition.ts

@@ -14,14 +14,15 @@ export const compositionStoryFixtures: CompositionStoryFixture[] = [
     storybookId: 'composition-container--buttons',
     title: 'Container / Buttons',
     block: {
+      $type: 'component',
       id: 'fixture-container-buttons',
       component: 'container',
       props: {
         theme: 'auto',
         className: 'space-y-4',
         blocks: [
-          { id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
-          { id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
+          { $type: 'component', id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
+          { $type: 'component', id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
         ]
       }
     }

package/templates/astro/starter-content/src/fixtures/sections.ts

@@ -14,6 +14,7 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
     storybookId: 'sections-home-hero--default',
     title: 'Home Hero',
     block: {
+      $type: 'component',
       id: 'fixture-home-hero',
       component: 'home_hero',
       props: {
@@ -22,10 +23,9 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
         description: 'One content model, three renderers. Build once in Next.js, Astro, and SvelteKit—then prove parity with shared fixtures.',
         ctaLabel: 'Get started',
         ctaHref: '/docs',
-          image: {
+        image: {
           $type: 'gradial.image',
-          assetId: 'fixture_seattle',
-          versionId: 'v0001',
+          assetId: '3Ih26etWBTYfnAd0EjD0pP2h902',
           alt: 'Seattle skyline at dusk',
           sources: [
             { src: '/assets/seattle.avif', width: 1920, height: 1280, sizes: '100vw', type: 'image/avif' }

package/templates/astro/starter-content/src/stories/CompositionStoryFrame.astro

@@ -1,6 +1,7 @@
 ---
 import type { KernelPageBlock } from '@gradial/aci/content';
-import ContainerSection from '../components/sections/ContainerSection.astro';
+import { createRenderChildren } from '@gradial/aci/astro';
+import { registry } from '../cms/registry';
 
 interface Props {
   block: KernelPageBlock;
@@ -8,8 +9,12 @@ interface Props {
 }
 
 const { block, direction = 'ltr' } = Astro.props;
+// Stories render through the same seam as pages so the frame carries the
+// block's root identity (sdk I-19, ADR 0051).
+const [child] = createRenderChildren(registry)([block]);
+const Comp = child.Component as any;
 ---
 
 <div dir={direction}>
-  {block.component === 'container' ? <ContainerSection {...block.props} /> : null}
+  {Comp ? <Comp {...child.props} /> : null}
 </div>

package/templates/astro/template/.aci.yaml.tmpl

@@ -9,7 +9,6 @@ source:
   publicDir: "public"
 
 componentRegistry: ./src/cms/contracts/components/index.ts
-layoutRegistry: ./src/cms/contracts/layouts/index.ts
 
 routes:
   cmsManaged: "/[...slug]"

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

@@ -14,7 +14,7 @@
     "build:storybook": "storybook build"
   },
   "engines": {
-    "node": ">=22",
+    "node": ">=24",
     "npm": ">=10"
   },
   "dependencies": {
@@ -31,9 +31,9 @@
     "tsx": "^4.20.0",
     "typescript": "5.9.3",
     "vite": "^7.2.7",
-    "storybook": "^10.0.0",
-    "@storybook-astro/framework": "^1.6.0",
-    "@storybook/addon-docs": "^10.0.0",
-    "@storybook/builder-vite": "^10.0.0"
+    "storybook": "10.5.10",
+    "@storybook-astro/framework": "1.11.0",
+    "@storybook/addon-docs": "10.5.10",
+    "@storybook/builder-vite": "10.5.10"
   }
 }

package/templates/astro/template/src/layouts/SiteLayout.astro

@@ -48,8 +48,8 @@ const { title, description, canonical, siteName = 'Gradial', collectTag, assignm
       // island (@astrojs/react + @c15t/react) or any setup built on
       // c15t's createConsentManagerStore; this bridge picks it up either
       // way. Without a c15t setup the poll gives up silently and only the
-      // JS consent API (aci('consent', …) under the manual preset) writes
-      // envelopes.
+      // JS consent API (aci('consent', …)) writes envelopes — it is live
+      // under every preset, including c15t.
       //
       // Consents are mirrored only after a real visitor decision
       // (consentInfo set), never for pre-decision defaults, so the SDK

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

@@ -152,6 +152,56 @@ Optional (disabled by default):
 
 ## Troubleshooting
 
+### Deploying a starter to a hosted Vercel tenant
+
+Run the CLI from the starter repository root (where `.aci.yaml` lives), or
+pass `--site-dir .` from that directory. Do not pass an absolute site path
+from another working directory: older CLI versions can serialize it as a
+`../../../tmp/...` source folder, which makes the server-side build fail with
+a generic HTTP 500. The source ref must also be a pushed, cloneable branch;
+`ref: HEAD` from a detached worktree is not cloneable by the build service.
+
+The hosted publish sequence is:
+
+1. `GRADIAL_CODE_SOURCE_TOKEN="$(gh auth token)" aci code-build --site-dir . --branch <test-branch> ...`
+2. `aci branch land <test-branch>` to move the artifact link to `main`.
+3. Promote `/config/site.json` and the content paths needed by the release.
+4. Run `aci release publish --activate ...`.
+
+Match the tenant rendering mode to the starter's actual route capability. A
+Next starter with `dynamicParams = false` and no release-scoped runtime route
+is an SSG starter and must use `rendering.mode = "ssg"`; `ssr` is only valid
+when the frontend can resolve arbitrary host release routes at request time.
+A mismatch can build successfully but then fail SSG rendering or return a
+live Next 404 after the host rewrites a CMS page.
+
+Injected platform functions must be dependency-closed inside their own
+`.vercel/output/functions/<name>.func` mount. A prebuilt Vercel deploy does not
+install a function-local `package.json` after upload. Native dependencies such
+as `sharp` therefore belong to the host-function artifact, built for Vercel's
+Linux/x64 runtime and injected beside the handler; never add them to the
+starter's `package.json` merely to make a platform function resolve.
+
+Publish validates `refs/heads/live`, not only `main`. If `main` deletes a
+stale incompatible page or fragment that was previously promoted, promote
+that same path from `main` with `aci promote --path ... --yes`; because the
+source path is absent, the promote records a delete on `live`. This is the
+API-safe way to remove old live content—direct writes to `live` are forbidden.
+
+The same rule applies to breaking DAM identifier changes: every
+`dam.assetRef` in `live` is resolved during publish, so one legacy identifier
+blocks the release. Update the reference on a candidate branch through
+`aci content push`, land it, and promote that exact content path before
+publishing again. Do not weaken identifier validation or reactivate an old
+release to bypass the content migration.
+
+Legacy assets themselves are replaced through the product API, not rewritten
+in storage: download or retain the needed source bytes, upload them again so
+DAM creates fresh canonical IDs, approve them, replace every content reference,
+then land, promote, and publish the affected paths. This is the supported
+breaking cutover for pre-public tenants; there is no `ast_` alias or bulk
+object-store migration path.
+
 ### "Unknown component" error during content compile
 
 The content JSON references a `component` name that is not in the contract
@@ -194,10 +244,10 @@ If a value doesn't survive the round-trip, check:
 |------|---------|
 | `.aci.yaml` | ACI config: contract paths, framework, routes, capabilities |
 | `src/cms/contracts/components/index.ts` | Component contract barrel |
-| `src/cms/contracts/layouts/index.ts` | Layout contract barrel |
 | `src/cms/registry.ts` | Component registry (`createRegistry` with `[contract, component]` tuples) |
 | `src/components/` | Runtime component implementations |
 | `src/design-system/` | Design tokens and global styles |
+| `.content/templates/` | Page composition contracts |
 | `.content/` | Local content for development |
 
 ## Deep Dive: Authoring
@@ -209,3 +259,10 @@ development, design tokens, and the full contract/runtime split.
 
 Read `.agents/skills/migration/SKILL.md` for reverse-engineering a live
 site or design into ACI.
+
+## Deep Dive: DAM Delivery
+
+Read `.agents/skills/dam-delivery/SKILL.md` for public DAM asset links
+(`/dam/{assetId}`): how to shape an image with the `w`, `h`, `fit`, `fm`,
+`q` query, what makes a link serve or stop serving, and when to use a
+link instead of a pre-baked derivative.