@gradial/aci 0.1.28 → 0.1.30

package/src/types/image.ts

@@ -1,19 +1,25 @@
 import { z } from 'zod';
 
 // ---------------------------------------------------------------------------
-// Image source variant (responsive derivative)
+// Image source variants
 //
-// Each entry is one concrete derivative produced by the compiler for the asset
-// slot. Renderers pick the primary variant and build a srcset from the list.
+// Each source provides a primary src and may include a ready-made srcset
+// scoped by the optional media/sizes of the slot output that produced it.
 // ---------------------------------------------------------------------------
 
 export interface ImageSource {
-  /** Derivative URL. */
+  /** Primary derivative URL for this rendition candidate. */
   src: string;
-  /** Intrinsic width in pixels. */
-  width: number;
-  /** Intrinsic height in pixels. */
-  height: number;
+  /** Intrinsic width in pixels (0 when the format carries none, e.g. SVG). */
+  width?: number;
+  /** Intrinsic height in pixels (0 when the format carries none). */
+  height?: number;
+  /** Optional width-descriptor rendition candidates. */
+  srcset?: string;
+  /** sizes attribute from the slot contract. */
+  sizes?: string;
+  /** Media query scoping this source (art direction). */
+  media?: string;
   /** MIME type hint, e.g. image/webp. */
   type: string;
 }
@@ -35,7 +41,7 @@ export interface Image {
   versionId: string;
   /** Accessible description of the image content. */
   alt: string;
-  /** Responsive derivative variants produced for the asset slot. */
+  /** <source> candidates produced for the asset slot. */
   sources: ImageSource[];
 }
 
@@ -61,8 +67,11 @@ export interface SlotOutput {
 
 export const ImageSourceSchema = z.object({
   src: z.string().min(1),
-  width: z.number().int().nonnegative(),
-  height: z.number().int().nonnegative(),
+  srcset: z.string().min(1).optional(),
+  width: z.number().int().nonnegative().optional(),
+  height: z.number().int().nonnegative().optional(),
+  sizes: z.string().min(1).optional(),
+  media: z.string().min(1).optional(),
   type: z.string().min(1),
 });
 
@@ -81,38 +90,32 @@ export const ImageSchema = z.object({
 export type ImageAttrs = Record<string, unknown>;
 
 /**
- * Picks the primary variant from an image's sources.
- * Uses the largest width; ties fall back to the first entry.
+ * The primary rendition of an image — its first source entry.
  */
 export function primaryImageSource(image: Image): ImageSource {
-  return image.sources.reduce((largest, source) =>
-    source.width > largest.width ? source : largest,
-    image.sources[0],
-  );
+  return image.sources[0];
 }
 
 /**
  * Computes the full set of <img> attributes for an Image.
  *
  * Framework components (React <Picture>, Astro <img>, Svelte <img>) call this
- * and spread the result into their native element.  No HTML string serialization.
+ * and spread the result into their native element.  No HTML string
+ * serialization. Media-scoped sources need a <picture> wrapper and are not
+ * representable as plain <img> attributes, so srcset/sizes are taken from the
+ * first unscoped source only.
  */
 export function imageAttrs(image: Image, overrides: ImageAttrs = {}): ImageAttrs {
-  const primary = primaryImageSource(image);
-  const srcset = image.sources
-    .map((s) => `${s.src} ${s.width}w`)
-    .join(', ');
-  const sizes = image.sources
-    .map((s) => `(max-width: ${s.width}px) ${s.width}px`)
-    .join(', ');
+  const primary = image.sources[0];
+  const unscoped = image.sources.find((s) => !s.media) ?? primary;
 
   return {
     src: primary.src,
     alt: image.alt,
-    width: primary.width > 0 ? primary.width : undefined,
-    height: primary.height > 0 ? primary.height : undefined,
-    srcSet: srcset || undefined,
-    sizes: sizes || undefined,
+    width: primary.width && primary.width > 0 ? primary.width : undefined,
+    height: primary.height && primary.height > 0 ? primary.height : undefined,
+    srcSet: unscoped?.srcset || undefined,
+    sizes: unscoped?.sizes || undefined,
     loading: 'lazy',
     decoding: 'async',
     ...overrides,

package/templates/astro/template/src/fixtures/sections.ts

@@ -28,7 +28,7 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
           versionId: 'v0001',
           alt: 'Seattle skyline at dusk',
           sources: [
-            { src: '/assets/seattle.avif', width: 1920, height: 1280, type: 'image/avif' }
+            { src: '/assets/seattle.avif', width: 1920, height: 1280, sizes: '100vw', type: 'image/avif' }
           ]
         }
       }

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

@@ -6,9 +6,17 @@ interface Props {
   description: string;
   canonical?: string;
   siteName?: string;
+  /**
+   * Pre-rendered Gradial collect script tag (collectScriptTagHTML from
+   * '@gradial/aci/astro'). Empty string / undefined = personalization
+   * disabled, no tag. Emitted here because the Astro integration has no
+   * attribute-bearing HTML-injection seam (injectScript only injects script
+   * content).
+   */
+  collectTag?: string;
 }
 
-const { title, description, canonical, siteName = 'Gradial' } = Astro.props;
+const { title, description, canonical, siteName = 'Gradial', collectTag } = Astro.props;
 ---
 
 <!doctype html>
@@ -23,8 +31,76 @@ const { title, description, canonical, siteName = 'Gradial' } = Astro.props;
     <meta property="og:title" content={title} />
     <meta property="og:description" content={description} />
     <meta property="og:site_name" content={siteName} />
+    {collectTag ? <Fragment set:html={collectTag} /> : null}
   </head>
   <body>
     <slot />
+    <script>
+      // Gradial collect ↔ c15t bridge. The collect SDK's c15t preset
+      // (data-aci-consent="c15t" on the collect tag) reads
+      // window.c15t = { consents, onConsentChange }. c15t itself publishes
+      // its zustand store as window.c15tStore instead, so this bridge
+      // mirrors any c15t store on the page into the shape the SDK reads.
+      //
+      // c15t has no Astro UI package — add a consent banner via a React
+      // 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.
+      //
+      // Consents are mirrored only after a real visitor decision
+      // (consentInfo set), never for pre-decision defaults, so the SDK
+      // cannot mistake an untouched banner for a withdrawal.
+      type Consents = Record<string, boolean>;
+      type ConsentListener = (payload: { consents: Consents }) => void;
+      interface ConsentStoreState {
+        consents?: Consents;
+        consentInfo?: unknown;
+      }
+      interface ConsentStoreLike {
+        getState(): ConsentStoreState;
+        subscribe(listener: (state: ConsentStoreState) => void): () => void;
+      }
+
+      const listeners: ConsentListener[] = [];
+
+      function publish(consents: Consents): void {
+        const w = window as typeof window & {
+          c15t?: { consents?: Consents; onConsentChange?: (cb: ConsentListener) => void };
+        };
+        const bridge = (w.c15t ??= {});
+        bridge.consents = consents;
+        bridge.onConsentChange ??= (cb: ConsentListener) => {
+          listeners.push(cb);
+        };
+        for (const listener of [...listeners]) {
+          listener({ consents });
+        }
+      }
+
+      function onState(state: ConsentStoreState): void {
+        if (state.consentInfo && state.consents) publish(state.consents);
+      }
+
+      function connect(store: ConsentStoreLike): void {
+        onState(store.getState());
+        store.subscribe(onState);
+      }
+
+      // Bounded poll for the store global — same schedule the collect SDK
+      // uses for window.c15t (250 ms for up to 10 s, then give up silently).
+      let remaining = 40;
+      function poll(): void {
+        const store = (window as { c15tStore?: ConsentStoreLike }).c15tStore;
+        if (store) {
+          connect(store);
+          return;
+        }
+        remaining -= 1;
+        if (remaining > 0) setTimeout(poll, 250);
+      }
+      poll();
+    </script>
   </body>
 </html>

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

@@ -1,5 +1,5 @@
 ---
-import { getGradialStaticPaths, getPageRuntimeRenderInput, createRenderChildren } from '@gradial/aci/astro';
+import { getGradialStaticPaths, getPageRuntimeRenderInput, createRenderChildren, collectScriptTagHTML } from '@gradial/aci/astro';
 import { normalizeRoute, routeMetadataForContent, resolveSlots } from '@gradial/aci/content';
 import { FileContentProvider } from '@gradial/aci/providers/file';
 import type { KernelPage, KernelSiteConfig, LayoutEntry, FragmentData } from '@gradial/aci/content';
@@ -36,9 +36,10 @@ const resolvedSlots = await resolveSlots(
 );
 
 const renderChildren = createRenderChildren(registry);
+const collectTag = collectScriptTagHTML(siteConfig);
 ---
 
-<SiteLayout title={meta.title} description={meta.description} canonical={meta.canonical} siteName={meta.siteName}>
+<SiteLayout title={meta.title} description={meta.description} canonical={meta.canonical} siteName={meta.siteName} collectTag={collectTag}>
   {layout.slots.map((slot) => {
     const blocks = resolvedSlots[slot.name];
     if (!blocks?.length) return null;

package/templates/common/.content/config/site.json

@@ -17,6 +17,11 @@
     "description": "Global satellite internet from anywhere on Earth.",
     "siteName": "Meridian"
   },
+  "personalization": {
+    "collect": true,
+    "consentPreset": "c15t",
+    "consentCategories": "measurement,marketing"
+  },
   "navigation": [
     {
       "id": "home",

package/templates/common/.content/schemas/site.schema.json

@@ -76,6 +76,21 @@
         "description": { "type": "string" },
         "siteName": { "type": "string" }
       }
+    },
+    "personalization": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "collect": { "type": "boolean" },
+        "consentPreset": {
+          "enum": ["c15t", "onetrust", "cookiebot", "trustarc", "manual"]
+        },
+        "consentCategories": {
+          "type": "string",
+          "pattern": "^\\s*[A-Za-z0-9._-]+(\\s*,\\s*[A-Za-z0-9._-]+)*\\s*$"
+        },
+        "debug": { "type": "boolean" }
+      }
     }
   },
   "$defs": {

package/templates/common/README.md.tmpl

@@ -43,3 +43,18 @@ src/design-system/ Design tokens and global styles
 .agents/skills/    Skills for humans and agents
 .aci/              Generated artifacts (compiled, schemas)
 ```
+
+## Personalization
+
+The `personalization` block in `.content/config/site.json` controls the
+Gradial collect tag (`<script defer src="/_aci/aci.js" …>`); pages emit it
+automatically when `collect` is `true`, and not at all when the block is
+absent. Consent is bridged from c15t (`consentPreset: "c15t"`): the Next kit
+ships a full c15t setup (`src/app/_components/ConsentManager.tsx`, offline
+mode by default, hosted via `NEXT_PUBLIC_C15T_BACKEND_URL`); the Astro kit
+ships the store bridge in `SiteLayout.astro` — add a banner via a React
+island (`@astrojs/react` + `@c15t/react`) and it is picked up automatically.
+
+Personalization requires the deployed site to be served through a Gradial
+edge binding, which provides `/collect`, identity, and the SDK itself. See
+the `@gradial/aci` README ("Personalization: The One-Tag Install").

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

@@ -17,7 +17,9 @@
     "build:storybook": "storybook build"
   },
   "dependencies": {
+    "@c15t/nextjs": "^2.1.0",
     "@gradial/aci": "{{aciVersion}}",
+    "js-yaml": "^4.1.1",
     "next": "^15.1.6",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/nextjs/template/src/app/_components/ConsentManager.tsx

@@ -0,0 +1,132 @@
+'use client';
+
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentManagerProvider,
+  useConsentManager,
+  type ConsentManagerProviderProps,
+} from '@c15t/nextjs';
+import { useEffect, useMemo, type ReactNode } from 'react';
+
+// Hosted c15t backend (consent.io or self-hosted). Unset = offline mode:
+// consent is stored client-side and no network calls are made.
+const C15T_BACKEND_URL = process.env.NEXT_PUBLIC_C15T_BACKEND_URL;
+
+// The CMP's own categories. The mapping from categories to the Gradial
+// personalization purpose lives in .content/config/site.json
+// (personalization.consentCategories), not here.
+const CONSENT_CATEGORIES = ['necessary', 'measurement', 'marketing'] as const;
+
+// ---------------------------------------------------------------------------
+// Gradial collect bridge
+//
+// The Gradial collect SDK's c15t preset (the site config's
+// `personalization.consentPreset: "c15t"`, emitted as
+// `data-aci-consent="c15t"` on the collect tag) reads
+// `window.c15t = { consents, onConsentChange }`. c15t itself does not
+// publish that shape, so this bridge mirrors the store onto it — only after
+// a real visitor decision (`consentInfo` set), never for pre-decision
+// defaults, so the SDK cannot mistake an untouched banner for a withdrawal.
+// ---------------------------------------------------------------------------
+
+type Consents = Record<string, boolean>;
+type ConsentListener = (payload: { consents: Consents }) => void;
+
+declare global {
+  interface Window {
+    c15t?: {
+      consents?: Consents;
+      onConsentChange?: (cb: ConsentListener) => void;
+    };
+  }
+}
+
+const consentListeners: ConsentListener[] = [];
+
+function publishAciConsents(consents: Consents): void {
+  const bridge = (window.c15t ??= {});
+  bridge.consents = consents;
+  bridge.onConsentChange ??= (cb: ConsentListener) => {
+    consentListeners.push(cb);
+  };
+  for (const listener of [...consentListeners]) {
+    listener({ consents });
+  }
+}
+
+function AciConsentBridge() {
+  const { consents, consentInfo } = useConsentManager();
+  useEffect(() => {
+    if (!consentInfo || !consents) return;
+    publishAciConsents(consents as Consents);
+  }, [consents, consentInfo]);
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Consent manager
+// ---------------------------------------------------------------------------
+
+function getConsentOptions(): ConsentManagerProviderProps['options'] {
+  const baseOptions = {
+    consentCategories: [...CONSENT_CATEGORIES],
+    legalLinks: {
+      privacyPolicy: {
+        href: '/privacy/',
+        target: '_self' as const,
+        label: 'Privacy policy',
+      },
+    },
+  };
+
+  if (C15T_BACKEND_URL) {
+    return {
+      ...baseOptions,
+      mode: 'hosted',
+      backendURL: C15T_BACKEND_URL,
+    };
+  }
+
+  return {
+    ...baseOptions,
+    mode: 'offline',
+    offlinePolicy: {
+      policyPacks: [
+        {
+          id: 'default-opt-in',
+          match: { isDefault: true },
+          consent: {
+            model: 'opt-in',
+            categories: [...CONSENT_CATEGORIES],
+          },
+          ui: { mode: 'banner' },
+        },
+      ],
+    },
+  };
+}
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  const options = useMemo(() => getConsentOptions(), []);
+
+  return (
+    <ConsentManagerProvider options={options}>
+      {children}
+      <AciConsentBridge />
+      <ConsentBanner
+        title="Cookie preferences"
+        description="We use cookies to keep the site working, measure performance, and support marketing."
+        acceptButtonText="Accept all"
+        rejectButtonText="Reject all"
+        customizeButtonText="Customize"
+        legalLinks={['privacyPolicy']}
+        layout={[['reject', 'accept'], 'customize']}
+        primaryButton="accept"
+        scrollLock={false}
+        hideBranding
+      />
+      <ConsentDialog legalLinks={['privacyPolicy']} scrollLock trapFocus hideBranding />
+    </ConsentManagerProvider>
+  );
+}

package/templates/nextjs/template/src/app/layout.tsx

@@ -1,6 +1,8 @@
 import type { ReactNode } from 'react';
 import { Inter, Space_Grotesk } from 'next/font/google';
 import { DevRefresh } from '@gradial/aci/next';
+import { ConsentManager } from '@/app/_components/ConsentManager';
+import '@c15t/nextjs/styles.css';
 import '@/design-system/styles.css';
 
 const inter = Inter({
@@ -21,7 +23,7 @@ export default function Layout({ children }: { children: ReactNode }) {
   return (
     <html lang="en" className={`${inter.variable} ${spaceGrotesk.variable}`}>
       <body>
-        {children}
+        <ConsentManager>{children}</ConsentManager>
         <DevRefresh />
       </body>
     </html>

package/templates/nextjs/template/src/components/sections/HomeHero.tsx

@@ -57,6 +57,6 @@ export function HomeHero({ eyebrow = '', headline = '', description = '', ctaLab
 }
 
 function heroImageSrc(image?: HeroImage) {
-  if (!image || image.sources.length === 0) return '';
+  if (!image) return '';
   return primaryImageSource(image).src;
 }