@gradial/aci 0.1.41 → 0.1.43

package/src/cli/validate-content.mjs

@@ -19,21 +19,24 @@
  * Uses the JSON schemas generated by compile-registry — portable, no React/CSS
  * imports needed, same schemas usable by Go backend or other tools.
  */
+import { realpathSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-
-const args = parseArgs(process.argv.slice(2));
-
-try {
-  const result = await validateContent(args);
-  console.log(JSON.stringify(result, null, 2));
-  if (!result.success) process.exitCode = 1;
-} catch (error) {
-  console.error(JSON.stringify({
-    success: false,
-    errors: [{ message: String(error?.message ?? error) }],
-  }, null, 2));
-  process.exitCode = 1;
+import { fileURLToPath } from 'node:url';
+
+if (isMainModule()) {
+  const args = parseArgs(process.argv.slice(2));
+  try {
+    const result = await validateContent(args);
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.success) process.exitCode = 1;
+  } catch (error) {
+    console.error(JSON.stringify({
+      success: false,
+      errors: [{ message: String(error?.message ?? error) }],
+    }, null, 2));
+    process.exitCode = 1;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -95,6 +98,24 @@ async function validateContent(options) {
     for (const block of blocks) {
       blocksValidated++;
 
+      if (!block || typeof block !== 'object') {
+        collector.push({
+          page: relativePath,
+          blockId: '<unknown>',
+          message: 'page region entry must be a component block',
+        });
+        continue;
+      }
+
+      if (block.$type !== 'component') {
+        collector.push({
+          page: relativePath,
+          blockId: block.id ?? '<unknown>',
+          path: '$type',
+          message: 'block "$type" must be "component"',
+        });
+      }
+
       if (!block.component) {
         collector.push({
           page: relativePath,
@@ -380,6 +401,13 @@ function validateNestedSlots(parentBlock, componentMap, schemaMap, path = 'props
         issues.push({ path: nestedPath, message: `${parentBlock.component}: block ref child must be a block` });
         continue;
       }
+      if (nestedBlock.$type !== 'component') {
+        issues.push({
+          path: `${nestedPath}.$type`,
+          message: `${parentBlock.component}: block ref child "$type" must be "component"`,
+        });
+        continue;
+      }
 
       if (!componentMap.has(nestedBlock.component)) {
         issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: unknown nested component "${nestedBlock.component}"` });
@@ -450,3 +478,14 @@ function parseArgs(argv) {
   }
   return out;
 }
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+export { validateContent };

package/src/cli/verify-next-cdn-routes.mjs

@@ -52,16 +52,17 @@ checkMissing(
   'Use src/app/[[...slug]]/page.tsx (optional catch-all). The required [...slug] form breaks file-provider local dev where "/" arrives with an empty slug.',
 );
 
-checkMissing(
-  'legacy app-level asset route is removed',
+checkFile(
+  'canonical asset route exists',
   'src/app/gradial/assets/[...path]/route.ts',
-  'Assets are served via URL rewrites in withAci(), not an app-level route.',
+  (content) => content.includes('@gradial/aci/next/asset-route'),
+  'Expected the canonical asset route to use @gradial/aci/next/asset-route.',
 );
 
 checkMissing(
   'legacy release-scoped asset route is removed',
   'src/app/gradial/assets/[releaseId]/[...path]/route.ts',
-  'Assets are served via URL rewrites in withAci(), not an app-level route.',
+  'Release-scoped asset URLs are produced by withAci() rewrites into the canonical src/app/gradial/assets/[...path]/route.ts; do not add a [releaseId] route.',
 );
 
 checkMissing(

package/src/consent-banner/styles.css

@@ -0,0 +1,110 @@
+/* Base consent banner styles — sites override with their own CSS. */
+/* The banner is injected into document.body by mountConsentBanner(). */
+
+#aci-consent-banner {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  z-index: 9999;
+  background: #1a1a2e;
+  color: #fff;
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  transition: opacity 0.3s ease, transform 0.3s ease;
+  opacity: 1;
+  transform: translateY(0);
+}
+
+#aci-consent-banner.aci-consent-banner--hidden {
+  opacity: 0;
+  transform: translateY(100%);
+  pointer-events: none;
+}
+
+#aci-consent-banner .aci-consent-banner__content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 16px 24px;
+}
+
+#aci-consent-banner .aci-consent-banner__text {
+  flex: 1;
+  min-width: 0;
+}
+
+#aci-consent-banner .aci-consent-banner__heading {
+  margin: 0 0 4px 0;
+  font-size: 16px;
+  font-weight: 600;
+}
+
+#aci-consent-banner .aci-consent-banner__message {
+  margin: 0;
+  font-size: 13px;
+  opacity: 0.85;
+}
+
+#aci-consent-banner .aci-consent-banner__privacy-link {
+  margin-left: 8px;
+  color: #8ecae6;
+  text-decoration: underline;
+  font-size: 13px;
+}
+
+#aci-consent-banner .aci-consent-banner__actions {
+  display: flex;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+#aci-consent-banner .aci-consent-banner__btn {
+  padding: 8px 20px;
+  border: none;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background-color 0.15s ease;
+}
+
+#aci-consent-banner .aci-consent-banner__btn--accept {
+  background: #2196f3;
+  color: #fff;
+}
+
+#aci-consent-banner .aci-consent-banner__btn--accept:hover {
+  background: #1976d2;
+}
+
+#aci-consent-banner .aci-consent-banner__btn--reject {
+  background: transparent;
+  color: #fff;
+  border: 1px solid rgba(255, 255, 255, 0.3);
+}
+
+#aci-consent-banner .aci-consent-banner__btn--reject:hover {
+  background: rgba(255, 255, 255, 0.1);
+}
+
+@media (max-width: 640px) {
+  #aci-consent-banner .aci-consent-banner__content {
+    flex-direction: column;
+    align-items: stretch;
+    gap: 12px;
+  }
+
+  #aci-consent-banner .aci-consent-banner__actions {
+    flex-direction: column-reverse;
+  }
+
+  #aci-consent-banner .aci-consent-banner__btn {
+    width: 100%;
+    text-align: center;
+  }
+}

package/src/types/block-ref.test.ts

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { z } from 'zod';
+
+import { compileSchema } from '../compiler/zod-to-jsonschema.js';
+import { defineComponentContract } from '../define-component.js';
+import { blockRefArray } from './block-ref.js';
+
+const childContract = defineComponentContract({
+  id: 'child',
+  props: z.object({
+    label: z.string(),
+  }),
+});
+
+test('block references require and accept the component discriminator', () => {
+  const schema = blockRefArray([childContract]);
+  const typed = {
+    $type: 'component',
+    id: 'child-1',
+    component: 'child',
+    props: { label: 'Hello' },
+  };
+
+  assert.equal(schema.safeParse([typed]).success, true);
+  assert.equal(schema.safeParse([{
+    id: typed.id,
+    component: typed.component,
+    props: typed.props,
+  }]).success, false);
+});
+
+test('compiled block-reference schema exposes the component discriminator', () => {
+  const compiled = compileSchema(blockRefArray([childContract])) as {
+    items?: {
+      properties?: Record<string, { const?: string }>;
+      required?: string[];
+      additionalProperties?: boolean;
+    };
+  };
+
+  assert.equal(compiled.items?.properties?.$type?.const, 'component');
+  assert.equal(compiled.items?.required?.includes('$type'), true);
+  assert.equal(compiled.items?.additionalProperties, false);
+});

package/src/types/block-ref.ts

@@ -9,6 +9,7 @@ export interface BlockRefMeta {
 }
 
 const blockRefBase = z.object({
+  $type: z.literal('component'),
   id: z.string().min(1),
   component: z.string().min(1),
   props: z.record(z.string(), z.unknown()),
@@ -21,6 +22,7 @@ type InferContractProps<T> = T extends ComponentContract<string, infer Schema>
 type InferContractId<T> = T extends ComponentContract<infer Id, unknown> ? Id : never;
 
 export type BlockRefEntry<T extends ComponentContract> = {
+  $type: 'component';
   id: string;
   component: InferContractId<T>;
   props: InferContractProps<T>;

package/src/types/page.ts

@@ -31,7 +31,7 @@ export interface BlockNode {
   component: string;
   props: Record<string, unknown>;
   renderHints: BlockRenderHints;
-  contentRef?: string;
+  contentPath?: string;
 }
 
 export interface BlockRenderHints {

package/templates/astro/starter-content/src/cms/contracts/components/index.ts

@@ -3,12 +3,14 @@ import { containerContract } from './container.contract';
 import { featureCardContract } from './featureCard.contract';
 import { featureGridContract } from './featureGrid.contract';
 import { homeHeroContract } from './homeHero.contract';
+import { personalizationChoiceContract } from './personalizationChoice.contract';
 import { siteNavigationContract } from './siteNavigation.contract';
 import { siteFooterContract } from './siteFooter.contract';
 import { statsBarContract } from './statsBar.contract';
 
 const componentContracts = [
   homeHeroContract,
+  personalizationChoiceContract,
   containerContract,
   buttonContract,
   siteNavigationContract,

package/templates/astro/starter-content/src/cms/contracts/components/personalizationChoice.contract.ts

@@ -0,0 +1,17 @@
+import { defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  title: z.string().min(1),
+  description: z.string().optional(),
+  redLabel: z.string().min(1),
+  blueLabel: z.string().min(1),
+  refreshLabel: z.string().min(1),
+});
+
+export type ContentProps = z.infer<typeof schema>;
+
+export const personalizationChoiceContract = defineComponentContract({
+  id: 'personalization_choice',
+  props: schema,
+});

package/templates/astro/starter-content/src/cms/registry.ts

@@ -1,5 +1,6 @@
 import { createRegistry } from '@gradial/aci';
 import { homeHeroContract } from './contracts/components/homeHero.contract';
+import { personalizationChoiceContract } from './contracts/components/personalizationChoice.contract';
 import { containerContract } from './contracts/components/container.contract';
 import { buttonContract } from './contracts/components/button.contract';
 import { siteNavigationContract } from './contracts/components/siteNavigation.contract';
@@ -8,6 +9,7 @@ import { featureGridContract } from './contracts/components/featureGrid.contract
 import { featureCardContract } from './contracts/components/featureCard.contract';
 import { statsBarContract } from './contracts/components/statsBar.contract';
 import HomeHero from '../components/sections/HomeHero.astro';
+import PersonalizationChoice from '../components/sections/PersonalizationChoice.astro';
 import ContainerSection from '../components/sections/ContainerSection.astro';
 import ButtonBlock from '../components/elements/ButtonBlock.astro';
 import Header from '../components/chrome/Header.astro';
@@ -18,6 +20,7 @@ import StatsBar from '../components/sections/StatsBar.astro';
 
 export const registry = createRegistry([
   [homeHeroContract, HomeHero],
+  [personalizationChoiceContract, PersonalizationChoice],
   [containerContract, ContainerSection],
   [buttonContract, ButtonBlock],
   [siteNavigationContract, Header],

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

@@ -0,0 +1,41 @@
+---
+import type { ContentProps } from '../../cms/contracts/components/personalizationChoice.contract';
+
+type Props = ContentProps;
+
+const { title, description, redLabel, blueLabel, refreshLabel } = Astro.props;
+---
+
+<section 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}
+    <div class="mt-6 flex flex-wrap justify-center gap-3">
+      <button type="button" class="inline-flex min-h-10 items-center justify-center rounded-button border border-emerald-700 bg-emerald-600 px-[var(--spacing-button-x)] py-[var(--spacing-button-y)] font-[var(--font-weight-semibold)] text-white transition hover:bg-emerald-700" data-aci-consent-button>Enable personalization</button>
+      <button type="button" class="inline-flex min-h-10 items-center justify-center rounded-button border border-red-700 bg-red-600 px-[var(--spacing-button-x)] py-[var(--spacing-button-y)] font-[var(--font-weight-semibold)] text-white transition hover:bg-red-700" data-aci-event="preference" data-aci-prop-color="red">{redLabel}</button>
+      <button type="button" class="inline-flex min-h-10 items-center justify-center rounded-button border border-blue-700 bg-blue-600 px-[var(--spacing-button-x)] py-[var(--spacing-button-y)] font-[var(--font-weight-semibold)] text-white transition hover:bg-blue-700" data-aci-event="preference" data-aci-prop-color="blue">{blueLabel}</button>
+      <button type="button" class="inline-flex min-h-10 items-center justify-center rounded-button border border-[var(--button-outline-border)] bg-[var(--button-outline-bg)] px-[var(--spacing-button-x)] py-[var(--spacing-button-y)] font-[var(--font-weight-semibold)] text-[var(--button-outline-text)] transition hover:opacity-85" data-aci-refresh>{refreshLabel}</button>
+    </div>
+    <p class="mx-auto mt-4 max-w-2xl text-sm text-[var(--color-fg-muted)]" data-aci-cookie-status aria-live="polite">Consent: checking... | Browser marker: checking... | Identity and audience cookies: HttpOnly server-managed</p>
+  </div>
+</section>
+
+<script is:inline>
+  (() => {
+    const hasCookie = (name) => document.cookie.split('; ').some((value) => value.startsWith(`${name}=`));
+    const status = document.querySelector('[data-aci-cookie-status]');
+    const render = () => {
+      if (!status) return;
+      status.textContent = `Consent: ${hasCookie('aci_consent') ? 'granted' : 'not granted'} | Browser marker: ${hasCookie('aci_m') ? 'minted' : 'not minted'} | Identity and audience cookies: HttpOnly server-managed`;
+    };
+    document.querySelector('[data-aci-consent-button]')?.addEventListener('click', () => {
+      const envelope = encodeURIComponent(JSON.stringify({ v: 1, p: ['personalization'], t: new Date().toISOString(), src: 'demo-consent' }));
+      document.cookie = `aci_consent=${envelope}; Path=/; Max-Age=31536000; SameSite=Lax; Secure`;
+      window.aci?.('consent', { p: ['personalization'], src: 'demo-consent' });
+      render();
+      window.setTimeout(() => document.querySelector('[data-aci-refresh]')?.click(), 50);
+    }, true);
+    render();
+    window.setInterval(render, 1000);
+  })();
+</script>

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,7 +23,7 @@ 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',

package/templates/astro/starter-content/src/render/RenderPage.astro

@@ -1,7 +1,7 @@
 ---
 import SiteLayout from '../layouts/SiteLayout.astro';
 import type { KernelPage, KernelSiteConfig } from '@gradial/aci/content';
-import { registryLookup } from '@gradial/aci/astro';
+import { registryLookup, collectScriptTagHTML } from '@gradial/aci/astro';
 import { registry } from '../cms/registry';
 import Header from '../components/chrome/Header.astro';
 import Footer from '../components/chrome/Footer.astro';
@@ -24,12 +24,13 @@ const title = page.metadata?.title || siteConfig.seo?.title || siteConfig.title;
 const description = page.metadata?.description || siteConfig.seo?.description || '';
 const canonical = page.metadata?.canonical;
 const siteName = siteConfig.seo?.siteName || siteConfig.title;
+const collectTag = collectScriptTagHTML(siteConfig);
 
 const footer = siteConfig.footer || {};
 const blocks = page?.regions?.main || [];
 ---
 
-<SiteLayout {title} {description} {canonical} {siteName}>
+<SiteLayout {title} {description} {canonical} {siteName} {collectTag}>
   <Header
     brandHref={siteConfig.brandHref || '/'}
     brandLabel={siteConfig.title || 'Gradial'}

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

@@ -14,9 +14,10 @@ interface Props {
    * content).
    */
   collectTag?: string;
+  assignmentsTag?: string;
 }
 
-const { title, description, canonical, siteName = 'Gradial', collectTag } = Astro.props;
+const { title, description, canonical, siteName = 'Gradial', collectTag, assignmentsTag } = Astro.props;
 ---
 
 <!doctype html>
@@ -32,6 +33,7 @@ const { title, description, canonical, siteName = 'Gradial', collectTag } = Astr
     <meta property="og:description" content={description} />
     <meta property="og:site_name" content={siteName} />
     {collectTag ? <Fragment set:html={collectTag} /> : null}
+    {assignmentsTag ? <Fragment set:html={assignmentsTag} /> : null}
   </head>
   <body>
     <slot />

package/templates/astro/template/src/pages/[...slug].astro

@@ -17,6 +17,7 @@ const renderChildren = createRenderChildren(registry);
   canonical={data.meta.canonical}
   siteName={data.meta.siteName}
   collectTag={data.collectTag}
+  assignmentsTag={data.assignmentsTag}
 >
   {data.layout.slots.map((slot) => {
     const blocks = data.slots[slot.name];

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

@@ -98,6 +98,7 @@ The `home` slug is special-cased to route `/`. All other slugs map directly.
 
 ```json
 {
+  "$type": "component",
   "id": "hero-section",
   "component": "home_hero",
   "props": {
@@ -109,6 +110,7 @@ The `home` slug is special-cased to route `/`. All other slugs map directly.
 ```
 
 - `component` must match a contract `id` exactly.
+- Every embedded block must declare `"$type": "component"`.
 - `props` must validate against the contract's Zod schema.
 - `id` is unique within the page.
 
@@ -141,12 +143,14 @@ export const containerContract = defineComponentContract({
 **Content JSON:**
 ```json
 {
+  "$type": "component",
   "id": "cta-section",
   "component": "container",
   "props": {
     "className": "space-y-4",
     "content": [
       {
+        "$type": "component",
         "id": "primary-cta",
         "component": "button",
         "props": {
@@ -156,6 +160,7 @@ export const containerContract = defineComponentContract({
         }
       },
       {
+        "$type": "component",
         "id": "secondary-cta",
         "component": "button",
         "props": {
@@ -182,6 +187,7 @@ The `button` component is a common atomic block:
 
 ```json
 {
+  "$type": "component",
   "id": "cta-button",
   "component": "button",
   "props": {
@@ -411,6 +417,7 @@ framework.
 ```json
 // .content/pages/home/_index.json (inside regions.main)
 {
+  "$type": "component",
   "id": "features",
   "component": "feature_showcase",
   "props": {
@@ -499,9 +506,10 @@ export default [
 ];
 ```
 
-Fragment content lives in `.content/fragments/{id}/_index.json` and has
-a `component` + `props` just like page blocks. Chrome components (Header,
-Footer) are registered in the registry alongside page components.
+Fragment content lives in `.content/fragments/{id}/_index.json` and retains
+the resource envelope `"$type": "fragment"` while declaring `component` +
+`props`. Chrome components (Header, Footer) are registered in the registry
+alongside page components.
 
 The `layout` field in page JSON is **required** — there is no implicit
 default. Every page must declare which layout it uses.

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

@@ -113,12 +113,14 @@ type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<Reac
 
 ```json
 {
+  "$type": "component",
   "id": "cta-section",
   "component": "container",
   "props": {
     "theme": "dark",
     "blocks": [
       {
+        "$type": "component",
         "id": "primary-cta",
         "component": "callout",
         "props": {
@@ -127,6 +129,7 @@ type RenderChildren<T extends readonly BlockRef[]> = (blocks: T) => Promise<Reac
         }
       },
       {
+        "$type": "component",
         "id": "heading",
         "component": "heading",
         "props": {

package/templates/common/.content/audiences/preference-blue/_index.json

@@ -0,0 +1,11 @@
+{
+  "$type": "audience",
+  "props": {
+    "id": "preference-blue",
+    "displayName": "Blue preference",
+    "status": "enabled",
+    "priority": 100,
+    "membershipSource": "segment",
+    "segmentRef": "$ref:segments/preference-blue"
+  }
+}

package/templates/common/.content/audiences/preference-red/_index.json

@@ -0,0 +1,11 @@
+{
+  "$type": "audience",
+  "props": {
+    "id": "preference-red",
+    "displayName": "Red preference",
+    "status": "enabled",
+    "priority": 100,
+    "membershipSource": "segment",
+    "segmentRef": "$ref:segments/preference-red"
+  }
+}

package/templates/common/.content/overlays/audience/preference-blue/pages/home/_index.json

@@ -0,0 +1,13 @@
+{
+  "$type": "page-overlay",
+  "regions": {
+    "main": {
+      "personalization-choice": {
+        "props": {
+          "title": "Blue preference active",
+          "description": "Your latest preference is Blue. Choose Red to replace it."
+        }
+      }
+    }
+  }
+}

package/templates/common/.content/overlays/audience/preference-red/pages/home/_index.json

@@ -0,0 +1,13 @@
+{
+  "$type": "page-overlay",
+  "regions": {
+    "main": {
+      "personalization-choice": {
+        "props": {
+          "title": "Red preference active",
+          "description": "Your latest preference is Red. Choose Blue to replace it."
+        }
+      }
+    }
+  }
+}