@gradial/aci 0.1.27 → 0.1.29

package/dist/types/media.d.ts

@@ -9,10 +9,16 @@ export declare const AssetSchema: z.ZodUnion<readonly [z.ZodObject<{
     assetId: z.ZodString;
     versionId: z.ZodString;
     alt: z.ZodString;
-    sources: z.ZodArray<z.ZodObject<{
+    fallback: z.ZodObject<{
         src: z.ZodString;
         width: z.ZodNumber;
         height: z.ZodNumber;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    sources: z.ZodArray<z.ZodObject<{
+        srcset: z.ZodString;
+        sizes: z.ZodOptional<z.ZodString>;
+        media: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
@@ -29,10 +35,16 @@ export declare const AssetSchema: z.ZodUnion<readonly [z.ZodObject<{
         assetId: z.ZodString;
         versionId: z.ZodString;
         alt: z.ZodString;
-        sources: z.ZodArray<z.ZodObject<{
+        fallback: z.ZodObject<{
             src: z.ZodString;
             width: z.ZodNumber;
             height: z.ZodNumber;
+            type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        sources: z.ZodArray<z.ZodObject<{
+            srcset: z.ZodString;
+            sizes: z.ZodOptional<z.ZodString>;
+            media: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;

package/dist/types/page.d.ts

@@ -1,9 +1,11 @@
 import type { VaryDimension } from './render-mode.js';
+import type { TaxonomyAssignments } from './data.js';
 export interface PageDocument {
     path: string;
     layout: string;
     locale: string;
     metadata: PageMetadata;
+    taxonomy?: TaxonomyAssignments;
     regions: Record<string, RegionNode>;
 }
 export interface PageMetadata {

package/dist/types/video.d.ts

@@ -52,10 +52,16 @@ export declare const VideoSchema: z.ZodObject<{
         assetId: z.ZodString;
         versionId: z.ZodString;
         alt: z.ZodString;
-        sources: z.ZodArray<z.ZodObject<{
+        fallback: z.ZodObject<{
             src: z.ZodString;
             width: z.ZodNumber;
             height: z.ZodNumber;
+            type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        sources: z.ZodArray<z.ZodObject<{
+            srcset: z.ZodString;
+            sizes: z.ZodOptional<z.ZodString>;
+            media: z.ZodOptional<z.ZodString>;
             type: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -74,6 +74,11 @@
       "types": "./dist/next/dev-refresh.d.ts",
       "import": "./dist/next/dev-refresh.js"
     },
+    "./next/server": {
+      "types": "./dist/next/server.d.ts",
+      "import": "./dist/next/server.js",
+      "default": "./dist/next/server.js"
+    },
     "./astro": {
       "types": "./dist/astro/index.d.ts",
       "import": "./dist/astro/index.js",

package/src/types/data.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+export type TaxonomyAssignments = Record<string, string[]>;
+
 type InferDataProps<TSchema> = TSchema extends z.ZodType<infer T>
   ? T
   : Record<string, unknown>;
@@ -19,6 +21,7 @@ export interface DataModelContract<TSchema = unknown, TType extends string = str
 export interface DataEntry<TProps = Record<string, unknown>, TType extends string = string> {
   $type: TType;
   props: TProps;
+  taxonomy?: TaxonomyAssignments;
 }
 
 export type InferDataModelProps<TContract> = TContract extends DataModelContract<infer TSchema, string>

package/src/types/image.ts

@@ -1,20 +1,32 @@
 import { z } from 'zod';
 
 // ---------------------------------------------------------------------------
-// Image source variant (responsive derivative)
+// Image fallback + 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.
+// The fallback is the base <img> rendition (largest derivative); each source
+// entry is one <source> element candidate with a ready-made srcset scoped by
+// the optional media/sizes of the slot output that produced it.
 // ---------------------------------------------------------------------------
 
-export interface ImageSource {
-  /** Derivative URL. */
+export interface ImageFallback {
+  /** Derivative URL for the base <img>. */
   src: string;
-  /** Intrinsic width in pixels. */
+  /** Intrinsic width in pixels (0 when the format carries none, e.g. SVG). */
   width: number;
-  /** Intrinsic height in pixels. */
+  /** Intrinsic height in pixels (0 when the format carries none). */
   height: number;
   /** MIME type hint, e.g. image/webp. */
+  type?: string;
+}
+
+export interface ImageSource {
+  /** srcset value — a single URL or a width-descriptor candidate list. */
+  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 +47,9 @@ export interface Image {
   versionId: string;
   /** Accessible description of the image content. */
   alt: string;
-  /** Responsive derivative variants produced for the asset slot. */
+  /** Base <img> rendition. */
+  fallback: ImageFallback;
+  /** <source> candidates produced for the asset slot. */
   sources: ImageSource[];
 }
 
@@ -59,10 +73,17 @@ export interface SlotOutput {
 // Zod schema
 // ---------------------------------------------------------------------------
 
-export const ImageSourceSchema = z.object({
+export const ImageFallbackSchema = z.object({
   src: z.string().min(1),
   width: z.number().int().nonnegative(),
   height: z.number().int().nonnegative(),
+  type: z.string().min(1).optional(),
+});
+
+export const ImageSourceSchema = z.object({
+  srcset: z.string().min(1),
+  sizes: z.string().min(1).optional(),
+  media: z.string().min(1).optional(),
   type: z.string().min(1),
 });
 
@@ -71,6 +92,7 @@ export const ImageSchema = z.object({
   assetId: z.string().min(1),
   versionId: z.string().min(1),
   alt: z.string(),
+  fallback: ImageFallbackSchema,
   sources: z.array(ImageSourceSchema).min(1),
 });
 
@@ -81,38 +103,31 @@ 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 fallback (base <img>) entry.
  */
-export function primaryImageSource(image: Image): ImageSource {
-  return image.sources.reduce((largest, source) =>
-    source.width > largest.width ? source : largest,
-    image.sources[0],
-  );
+export function primaryImageSource(image: Image): ImageFallback {
+  return image.fallback;
 }
 
 /**
  * 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 unscoped = image.sources.find((s) => !s.media);
 
   return {
-    src: primary.src,
+    src: image.fallback.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: image.fallback.width > 0 ? image.fallback.width : undefined,
+    height: image.fallback.height > 0 ? image.fallback.height : undefined,
+    srcSet: unscoped?.srcset || undefined,
+    sizes: unscoped?.sizes || undefined,
     loading: 'lazy',
     decoding: 'async',
     ...overrides,

package/src/types/page.ts

@@ -1,10 +1,12 @@
 import type { VaryDimension } from './render-mode.js';
+import type { TaxonomyAssignments } from './data.js';
 
 export interface PageDocument {
   path: string;
   layout: string;
   locale: string;
   metadata: PageMetadata;
+  taxonomy?: TaxonomyAssignments;
   regions: Record<string, RegionNode>;
 }
 

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

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@astrojs/node": "^10.1.4",
-    "@gradial/aci": "0.1.23",
+    "@gradial/aci": "{{aciVersion}}",
     "astro": "^6.1.9",
     "zod": "^4.0.0"
   },

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

@@ -27,8 +27,9 @@ export const sectionStoryFixtures: SectionStoryFixture[] = [
           assetId: 'fixture_seattle',
           versionId: 'v0001',
           alt: 'Seattle skyline at dusk',
+          fallback: { src: '/assets/seattle.avif', width: 1920, height: 1280, type: 'image/avif' },
           sources: [
-            { src: '/assets/seattle.avif', width: 1920, height: 1280, type: 'image/avif' }
+            { srcset: '/assets/seattle.avif', 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/.agents/AGENTS.md

@@ -22,6 +22,11 @@ Skills live in `.agents/skills/`. Each has a `SKILL.md` entry point and
 - Registry lives in `src/cms/registry.ts` (`createRegistry` with `[contract, component]` tuples).
 - Compiled output goes to `.aci/compiled/` (generated, not checked in).
 - Framework integration via `withAci()` in the framework config.
+- Next.js server functions from `@gradial/aci/next` — use `getSiteConfig()`, `getPage()`, `getFragment()` instead of importing `FileContentProvider` or `S3ContentProvider` directly.
+- Rich text from `@gradial/aci/react` — use `RichText` component, never raw `marked`/`dangerouslySetInnerHTML`.
+- Images from `@gradial/aci` — use `imageAttrs()` or SDK components, never manual `srcSet` construction.
+- Block slots use `blockRefArray()` in contracts and `renderChildren` in components — never hardcoded component name matching.
+- No `as any` casts — use `ContentProps` from contracts.
 - Supported frameworks: Astro and Next.js (SvelteKit removed).
 
 ## Commands

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

@@ -588,3 +588,34 @@ chrome-specific override scopes, and token creation workflow.
 Read `references/repo-structure.md` for the full annotated directory
 layout, framework-specific paths, naming conventions, and generated
 files list.
+
+## Deep Dive: SDK Server Functions
+
+Read `references/sdk-server-functions.md` for `@gradial/aci/next`
+server-side functions (`createPage`, `getSiteConfig`, `getFragment`,
+etc.), the three-tier content resolution chain, and the critical rule
+against importing `FileContentProvider` or `S3ContentProvider`
+directly in app code.
+
+## Deep Dive: Block Slots
+
+Read `references/block-slots.md` for `blockRefArray()` in contracts,
+`renderChildren` in components, and the rules for nested block
+rendering without hardcoded component name matching.
+
+## Deep Dive: Rich Text
+
+Read `references/rich-text.md` for the SDK `RichText` component from
+`@gradial/aci/react`, sanitization policy, and why you should never
+use `marked` or `dangerouslySetInnerHTML` directly.
+
+## Deep Dive: Asset Rendering
+
+Read `references/asset-rendering.md` for `imageAttrs()`, `Picture`,
+`Image`, `Media` components, and CSS background image patterns.
+
+## Deep Dive: Type Safety
+
+Read `references/type-safety.md` for `ContentProps` from contracts,
+`as any` prohibition, CSS custom property typing, site config
+generics, and block slot type imports.

package/templates/common/.agents/skills/authoring/references/asset-rendering.md

@@ -0,0 +1,110 @@
+# Asset Rendering Reference
+
+## Rules
+
+- **NEVER** construct `<img>` tags manually with `src`/`srcSet` from
+  image sources.
+- **ALWAYS** use the SDK's `imageAttrs()` function from `@gradial/aci`
+  or the `Image`/`Picture` component from `@gradial/aci/react`.
+- **NEVER** duplicate the `Image` type locally — always import from
+  `@gradial/aci`.
+
+## SDK Exports
+
+### From `@gradial/aci`
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `Image` | type | The DAM-backed image type (`$type`, `assetId`, `versionId`, `alt`, `sources`) |
+| `ImageSource` | type | A single responsive derivative (`src`, `width`, `height`, `type`) |
+| `imageAttrs(image, overrides?)` | function | Returns a complete attributes object for `<img>` |
+| `primaryImageSource(image)` | function | Picks the largest-width source from an image |
+| `ImageSchema` | Zod schema | Schema for image fields in contracts |
+
+### From `@gradial/aci/react`
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `Image` | component | Renders an `Image` as `<img>` with computed attrs |
+| `Picture` | component | Renders an `Image` as responsive `<img>` (delegates to `imageAttrs()`) |
+| `Media` | component | Renders media assets (images, videos) with type detection |
+
+## imageAttrs()
+
+`imageAttrs(image, overrides?)` returns a complete attributes object
+including `src`, `alt`, `width`, `height`, `srcSet`, `sizes`, `loading`,
+and `decoding`. Spread the result into a native `<img>` element:
+
+```tsx
+import { imageAttrs, type Image } from '@gradial/aci';
+
+export function HeroImage({ image }: { image: Image }) {
+  return <img {...imageAttrs(image)} />;
+}
+```
+
+Override specific attributes by passing a second argument:
+
+```tsx
+<img {...imageAttrs(image, { loading: 'eager' })} />
+```
+
+## SDK Components
+
+```tsx
+import { Picture, Image } from '@gradial/aci/react';
+
+// Picture: delegates to imageAttrs() internally
+<Picture image={image} />
+
+// Image: same behavior, accepts image or value prop
+<Image image={image} />
+```
+
+Both components call `imageAttrs()` internally and spread the result
+into a native `<img>` element.
+
+## CSS Background Images
+
+For CSS background images, use `primaryImageSource()` to get the URL:
+
+```tsx
+import { primaryImageSource } from '@gradial/aci';
+
+export function HeroBackground({ image }: { image: Image }) {
+  const src = primaryImageSource(image).src;
+  return (
+    <div style={{ backgroundImage: `url(${src})` } as React.CSSProperties} />
+  );
+}
+```
+
+## In Contracts
+
+Use `ImageSchema` for DAM-managed image fields:
+
+```ts
+import { ImageSchema, defineComponentContract } from '@gradial/aci';
+import { z } from 'zod';
+
+export const schema = z.object({
+  image: ImageSchema,
+  cards: z.array(z.object({
+    image: ImageSchema.optional(),
+  })),
+});
+```
+
+Declare `imageSlots` matching every `ImageSchema` field, including
+nested dot paths like `cards.image`. See
+`references/image-assets.md` for full image slot configuration.
+
+## Anti-Patterns
+
+- Manually building `srcSet` strings from `image.sources` — use
+  `imageAttrs()` instead
+- Constructing `<img src={image.sources[0].src} />` — use `imageAttrs()`
+  or SDK components
+- Duplicating the `Image` type locally — import from `@gradial/aci`
+- Ignoring `width`/`height` — `imageAttrs()` includes them to prevent
+  layout shift