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

package/dist/types/image.d.ts

@@ -1,13 +1,19 @@
 import { z } from 'zod';
 export interface ImageSource {
-    /** Primary derivative URL for this rendition candidate. */
-    src: string;
-    /** Intrinsic width in pixels (0 when the format carries none, e.g. SVG). */
+    /** Authored asset path — static sources only; DAM sources never set it. */
+    src?: string;
+    /** Declared candidate widths for the srcset (DAM sources). Empty or absent
+     *  when the slot declares no outputs: the SDK renders the bare permalink
+     *  (no params, original bytes). */
+    widths?: number[];
+    /** Layout width in pixels — the largest declared width, or the intrinsic
+     *  width for static/original-aspect sources. */
     width?: number;
-    /** Intrinsic height in pixels (0 when the format carries none). */
+    /** Layout height in pixels — the height at `width` (aspect carrier). */
     height?: number;
-    /** Optional width-descriptor rendition candidates. */
-    srcset?: string;
+    /** Transform fit for DAM sources: 'max' fits inside the box; 'crop' fills
+     *  the declared aspect and emits an h param per srcset width. */
+    fit?: 'max' | 'crop';
     /** sizes attribute from the slot contract. */
     sizes?: string;
     /** Media query scoping this source (art direction). */
@@ -20,8 +26,9 @@ export interface Image {
     $type: 'gradial.image';
     /** DAM asset identifier (or "static:<path>" for non-DAM assets). */
     assetId: string;
-    /** DAM version identifier (or "static" for non-DAM assets). */
-    versionId: string;
+    /** DAM version identifier — absent for DAM images, which compile to the
+     *  versionless live URL /dam/{assetId}; never set for static images. */
+    versionId?: string;
     /** Accessible description of the image content. */
     alt: string;
     /** <source> candidates produced for the asset slot. */
@@ -38,10 +45,14 @@ export interface SlotOutput {
     media?: string;
 }
 export declare const ImageSourceSchema: z.ZodObject<{
-    src: z.ZodString;
-    srcset: z.ZodOptional<z.ZodString>;
+    src: z.ZodOptional<z.ZodString>;
+    widths: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
+    fit: z.ZodOptional<z.ZodEnum<{
+        max: "max";
+        crop: "crop";
+    }>>;
     sizes: z.ZodOptional<z.ZodString>;
     media: z.ZodOptional<z.ZodString>;
     type: z.ZodString;
@@ -49,19 +60,43 @@ export declare const ImageSourceSchema: z.ZodObject<{
 export declare const ImageSchema: z.ZodObject<{
     $type: z.ZodLiteral<"gradial.image">;
     assetId: z.ZodString;
-    versionId: z.ZodString;
+    versionId: z.ZodOptional<z.ZodString>;
     alt: z.ZodString;
     sources: z.ZodArray<z.ZodObject<{
-        src: z.ZodString;
-        srcset: z.ZodOptional<z.ZodString>;
+        src: z.ZodOptional<z.ZodString>;
+        widths: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         width: z.ZodOptional<z.ZodNumber>;
         height: z.ZodOptional<z.ZodNumber>;
+        fit: z.ZodOptional<z.ZodEnum<{
+            max: "max";
+            crop: "crop";
+        }>>;
         sizes: z.ZodOptional<z.ZodString>;
         media: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/** Default DAM delivery quality, matching the edge's DEFAULT_QUALITY. */
+export declare const DAM_IMAGE_QUALITY = 82;
+/**
+ * Configures the origin for DAM permalinks. The default is the empty string:
+ * relative same-origin URLs (`/dam/{assetId}`), served by the site's own
+ * hosting edge. Set a base (e.g. `https://assets.example.com`) when images
+ * are consumed off-origin — email, external CMS fields, social cards — or
+ * when delivery is hosted on a dedicated domain. Call once during app setup,
+ * before the first render.
+ */
+export declare function configureDamAssets(options?: {
+    baseUrl?: string;
+}): void;
+/**
+ * The DAM permalink for an asset: `{base}/dam/{assetId}`. No params means
+ * original bytes.
+ */
+export declare function damAssetUrl(assetId: string): string;
 export type ImageAttrs = Record<string, unknown>;
+/** True when the image resolves to authored static bytes, not a DAM asset. */
+export declare function isStaticImage(image: Image): boolean;
 /**
  * The primary rendition of an image — its first source entry.
  */
@@ -70,9 +105,11 @@ export declare function primaryImageSource(image: Image): ImageSource;
  * 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. 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.
+ * and spread the result into the native element. No HTML string
+ * serialization. DAM images construct their /dam/{assetId} permalink and
+ * srcset here from the slot-declared widths; static images pass their
+ * authored src through. 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 declare function imageAttrs(image: Image, overrides?: ImageAttrs): ImageAttrs;

package/dist/types/image.js

@@ -3,10 +3,11 @@ import { z } from 'zod';
 // Zod schema
 // ---------------------------------------------------------------------------
 export const ImageSourceSchema = z.object({
-    src: z.string().min(1),
-    srcset: z.string().min(1).optional(),
+    src: z.string().min(1).optional(),
+    widths: z.array(z.number().int().positive()).optional(),
     width: z.number().int().nonnegative().optional(),
     height: z.number().int().nonnegative().optional(),
+    fit: z.enum(['max', 'crop']).optional(),
     sizes: z.string().min(1).optional(),
     media: z.string().min(1).optional(),
     type: z.string().min(1),
@@ -14,10 +15,97 @@ export const ImageSourceSchema = z.object({
 export const ImageSchema = z.object({
     $type: z.literal('gradial.image'),
     assetId: z.string().min(1),
-    versionId: z.string().min(1),
+    versionId: z.string().min(1).optional(),
     alt: z.string(),
     sources: z.array(ImageSourceSchema).min(1),
 });
+// ---------------------------------------------------------------------------
+// DAM permalink construction (ADR 0062)
+// ---------------------------------------------------------------------------
+/** Default DAM delivery quality, matching the edge's DEFAULT_QUALITY. */
+export const DAM_IMAGE_QUALITY = 82;
+let damAssetBase = '';
+/**
+ * Configures the origin for DAM permalinks. The default is the empty string:
+ * relative same-origin URLs (`/dam/{assetId}`), served by the site's own
+ * hosting edge. Set a base (e.g. `https://assets.example.com`) when images
+ * are consumed off-origin — email, external CMS fields, social cards — or
+ * when delivery is hosted on a dedicated domain. Call once during app setup,
+ * before the first render.
+ */
+export function configureDamAssets(options = {}) {
+    damAssetBase = (options.baseUrl ?? '').replace(/\/+$/, '');
+}
+/**
+ * The DAM permalink for an asset: `{base}/dam/{assetId}`. No params means
+ * original bytes.
+ */
+export function damAssetUrl(assetId) {
+    return `${damAssetBase}/dam/${assetId}`;
+}
+const FORMAT_PARAMS = {
+    'image/avif': 'avif',
+    'image/webp': 'webp',
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+};
+function sourceFormatParams(source) {
+    const fm = FORMAT_PARAMS[source.type] ?? 'webp';
+    return `fm=${fm}&q=${DAM_IMAGE_QUALITY}`;
+}
+function srcsetWidth(assetId, source, width) {
+    const params = [`w=${width}`];
+    if (source.fit === 'crop' && source.width && source.height) {
+        const height = Math.round((width * source.height) / source.width);
+        params.push(`h=${height}`, 'fit=crop');
+    }
+    else {
+        params.push('fit=max');
+    }
+    params.push(sourceFormatParams(source));
+    return `${damAssetUrl(assetId)}?${params.join('&')} ${width}w`;
+}
+function damImageAttrs(image, primary) {
+    const base = {
+        src: damAssetUrl(image.assetId),
+        alt: image.alt,
+        width: primary.width && primary.width > 0 ? primary.width : undefined,
+        height: primary.height && primary.height > 0 ? primary.height : undefined,
+        loading: 'lazy',
+        decoding: 'async',
+    };
+    if (primary.widths && primary.widths.length > 0) {
+        // Primary src at the largest declared width; srcset covers them all.
+        const largest = primary.widths[primary.widths.length - 1];
+        const params = [`w=${largest}`];
+        if (primary.fit === 'crop' && primary.width && primary.height) {
+            params.push(`h=${Math.round((largest * primary.height) / primary.width)}`, 'fit=crop');
+        }
+        else {
+            params.push('fit=max');
+        }
+        params.push(sourceFormatParams(primary));
+        base.src = `${damAssetUrl(image.assetId)}?${params.join('&')}`;
+        if (primary.widths.length > 1) {
+            base.srcSet = primary.widths.map((w) => srcsetWidth(image.assetId, primary, w)).join(', ');
+        }
+    }
+    return base;
+}
+function staticImageAttrs(image, primary) {
+    return {
+        src: primary.src ?? '',
+        alt: image.alt,
+        width: primary.width && primary.width > 0 ? primary.width : undefined,
+        height: primary.height && primary.height > 0 ? primary.height : undefined,
+        loading: 'lazy',
+        decoding: 'async',
+    };
+}
+/** True when the image resolves to authored static bytes, not a DAM asset. */
+export function isStaticImage(image) {
+    return image.assetId.startsWith('static:');
+}
 /**
  * The primary rendition of an image — its first source entry.
  */
@@ -28,23 +116,19 @@ export function primaryImageSource(image) {
  * 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. 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.
+ * and spread the result into the native element. No HTML string
+ * serialization. DAM images construct their /dam/{assetId} permalink and
+ * srcset here from the slot-declared widths; static images pass their
+ * authored src through. 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, overrides = {}) {
     const primary = image.sources[0];
     const unscoped = image.sources.find((s) => !s.media) ?? primary;
-    return {
-        src: primary.src,
-        alt: image.alt,
-        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,
-    };
+    const base = isStaticImage(image) ? staticImageAttrs(image, primary) : damImageAttrs(image, primary);
+    if (unscoped?.sizes) {
+        base.sizes = unscoped.sizes;
+    }
+    return { ...base, ...overrides };
 }

package/dist/types/media.d.ts

@@ -7,13 +7,17 @@ export type Asset = Image | Video;
 export declare const AssetSchema: z.ZodUnion<readonly [z.ZodObject<{
     $type: z.ZodLiteral<"gradial.image">;
     assetId: z.ZodString;
-    versionId: z.ZodString;
+    versionId: z.ZodOptional<z.ZodString>;
     alt: z.ZodString;
     sources: z.ZodArray<z.ZodObject<{
-        src: z.ZodString;
-        srcset: z.ZodOptional<z.ZodString>;
+        src: z.ZodOptional<z.ZodString>;
+        widths: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         width: z.ZodOptional<z.ZodNumber>;
         height: z.ZodOptional<z.ZodNumber>;
+        fit: z.ZodOptional<z.ZodEnum<{
+            max: "max";
+            crop: "crop";
+        }>>;
         sizes: z.ZodOptional<z.ZodString>;
         media: z.ZodOptional<z.ZodString>;
         type: z.ZodString;
@@ -30,13 +34,17 @@ export declare const AssetSchema: z.ZodUnion<readonly [z.ZodObject<{
     poster: z.ZodOptional<z.ZodObject<{
         $type: z.ZodLiteral<"gradial.image">;
         assetId: z.ZodString;
-        versionId: z.ZodString;
+        versionId: z.ZodOptional<z.ZodString>;
         alt: z.ZodString;
         sources: z.ZodArray<z.ZodObject<{
-            src: z.ZodString;
-            srcset: z.ZodOptional<z.ZodString>;
+            src: z.ZodOptional<z.ZodString>;
+            widths: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
             width: z.ZodOptional<z.ZodNumber>;
             height: z.ZodOptional<z.ZodNumber>;
+            fit: z.ZodOptional<z.ZodEnum<{
+                max: "max";
+                crop: "crop";
+            }>>;
             sizes: z.ZodOptional<z.ZodString>;
             media: z.ZodOptional<z.ZodString>;
             type: z.ZodString;

package/dist/types/video.d.ts

@@ -50,13 +50,17 @@ export declare const VideoSchema: z.ZodObject<{
     poster: z.ZodOptional<z.ZodObject<{
         $type: z.ZodLiteral<"gradial.image">;
         assetId: z.ZodString;
-        versionId: z.ZodString;
+        versionId: z.ZodOptional<z.ZodString>;
         alt: z.ZodString;
         sources: z.ZodArray<z.ZodObject<{
-            src: z.ZodString;
-            srcset: z.ZodOptional<z.ZodString>;
+            src: z.ZodOptional<z.ZodString>;
+            widths: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
             width: z.ZodOptional<z.ZodNumber>;
             height: z.ZodOptional<z.ZodNumber>;
+            fit: z.ZodOptional<z.ZodEnum<{
+                max: "max";
+                crop: "crop";
+            }>>;
             sizes: z.ZodOptional<z.ZodString>;
             media: z.ZodOptional<z.ZodString>;
             type: z.ZodString;

package/migrations/conformance-registry.md

@@ -0,0 +1,22 @@
+# Designate the render registry for Next conformance
+
+Set `registry` in the site's conformance options to the module its page entry
+uses to create the ACI page:
+
+```ts
+import { conformancePreset } from '@gradial/aci/testing';
+
+conformancePreset({
+  framework: 'next',
+  registry: 'src/cms/registry.ts',
+});
+```
+
+Paths resolve against `rootDir`, which defaults to the test process's current
+working directory. Absolute paths also work. Use the app's full render registry,
+including every registered component. The named module must export the registry.
+
+Run the site's `npm test`. The `rootIdentity` check renders components from the
+named module and fails if a rendered root omits its ACI identity attributes.
+Missing configuration or a missing module fails before importing site code.
+Astro's existing authored-block scan does not require this option.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.52-rc.29",
+  "version": "0.1.52-rc.34-e2e.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -20,6 +20,7 @@
     "templates/nextjs",
     "templates/astro",
     "CHANGELOG.md",
+    "migrations",
     "README.md"
   ],
   "bin": {
@@ -159,11 +160,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.29",
-    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.29",
-    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.29",
-    "@gradial/aci-cli-linux-x64": "0.1.52-rc.29",
-    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.29",
-    "@gradial/aci-cli-win32-x64": "0.1.52-rc.29"
+    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.34-e2e.1",
+    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.34-e2e.1",
+    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.34-e2e.1",
+    "@gradial/aci-cli-linux-x64": "0.1.52-rc.34-e2e.1",
+    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.34-e2e.1",
+    "@gradial/aci-cli-win32-x64": "0.1.52-rc.34-e2e.1"
   }
 }

package/src/cli/compile-registry.mjs

@@ -346,12 +346,10 @@ function isImageSchema(schema) {
     return compiled?.type === 'object'
       && properties.$type?.const === 'gradial.image'
       && properties.assetId?.type === 'string'
-      && properties.versionId?.type === 'string'
       && properties.alt?.type === 'string'
       && properties.sources?.type === 'array'
       && required.has('$type')
       && required.has('assetId')
-      && required.has('versionId')
       && required.has('alt')
       && required.has('sources');
   } catch {

package/src/types/image.ts

@@ -3,19 +3,28 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 // Image source variants
 //
-// 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.
+// A DAM source carries the asset identity's slot presentation — the declared
+// candidate widths, the fit, and the MIME format — and NEVER a URL: the SDK
+// constructs the /dam/{assetId} permalink and its srcset at render time
+// (ADR 0062: the compiler emits asset ids only). Static assets keep their
+// authored src passthrough.
 // ---------------------------------------------------------------------------
 
 export interface ImageSource {
-  /** Primary derivative URL for this rendition candidate. */
-  src: string;
-  /** Intrinsic width in pixels (0 when the format carries none, e.g. SVG). */
+  /** Authored asset path — static sources only; DAM sources never set it. */
+  src?: string;
+  /** Declared candidate widths for the srcset (DAM sources). Empty or absent
+   *  when the slot declares no outputs: the SDK renders the bare permalink
+   *  (no params, original bytes). */
+  widths?: number[];
+  /** Layout width in pixels — the largest declared width, or the intrinsic
+   *  width for static/original-aspect sources. */
   width?: number;
-  /** Intrinsic height in pixels (0 when the format carries none). */
+  /** Layout height in pixels — the height at `width` (aspect carrier). */
   height?: number;
-  /** Optional width-descriptor rendition candidates. */
-  srcset?: string;
+  /** Transform fit for DAM sources: 'max' fits inside the box; 'crop' fills
+   *  the declared aspect and emits an h param per srcset width. */
+  fit?: 'max' | 'crop';
   /** sizes attribute from the slot contract. */
   sizes?: string;
   /** Media query scoping this source (art direction). */
@@ -25,7 +34,7 @@ export interface ImageSource {
 }
 
 // ---------------------------------------------------------------------------
-// Image — DAM-backed image asset with compiler-resolved derivatives
+// Image — DAM-backed image asset with compiler-resolved live asset URLs
 //
 // Content authors write an asset reference: { "$type": "dam.assetRef", ... }
 // or for static files: { "$type": "static.assetRef", "src": "/path" }
@@ -37,8 +46,9 @@ export interface Image {
   $type: 'gradial.image';
   /** DAM asset identifier (or "static:<path>" for non-DAM assets). */
   assetId: string;
-  /** DAM version identifier (or "static" for non-DAM assets). */
-  versionId: string;
+  /** DAM version identifier — absent for DAM images, which compile to the
+   *  versionless live URL /dam/{assetId}; never set for static images. */
+  versionId?: string;
   /** Accessible description of the image content. */
   alt: string;
   /** <source> candidates produced for the asset slot. */
@@ -66,10 +76,11 @@ export interface SlotOutput {
 // ---------------------------------------------------------------------------
 
 export const ImageSourceSchema = z.object({
-  src: z.string().min(1),
-  srcset: z.string().min(1).optional(),
+  src: z.string().min(1).optional(),
+  widths: z.array(z.number().int().positive()).optional(),
   width: z.number().int().nonnegative().optional(),
   height: z.number().int().nonnegative().optional(),
+  fit: z.enum(['max', 'crop']).optional(),
   sizes: z.string().min(1).optional(),
   media: z.string().min(1).optional(),
   type: z.string().min(1),
@@ -78,17 +89,113 @@ export const ImageSourceSchema = z.object({
 export const ImageSchema = z.object({
   $type: z.literal('gradial.image'),
   assetId: z.string().min(1),
-  versionId: z.string().min(1),
+  versionId: z.string().min(1).optional(),
   alt: z.string(),
   sources: z.array(ImageSourceSchema).min(1),
 });
 
+// ---------------------------------------------------------------------------
+// DAM permalink construction (ADR 0062)
+// ---------------------------------------------------------------------------
+
+/** Default DAM delivery quality, matching the edge's DEFAULT_QUALITY. */
+export const DAM_IMAGE_QUALITY = 82;
+
+let damAssetBase = '';
+
+/**
+ * Configures the origin for DAM permalinks. The default is the empty string:
+ * relative same-origin URLs (`/dam/{assetId}`), served by the site's own
+ * hosting edge. Set a base (e.g. `https://assets.example.com`) when images
+ * are consumed off-origin — email, external CMS fields, social cards — or
+ * when delivery is hosted on a dedicated domain. Call once during app setup,
+ * before the first render.
+ */
+export function configureDamAssets(options: { baseUrl?: string } = {}): void {
+  damAssetBase = (options.baseUrl ?? '').replace(/\/+$/, '');
+}
+
+/**
+ * The DAM permalink for an asset: `{base}/dam/{assetId}`. No params means
+ * original bytes.
+ */
+export function damAssetUrl(assetId: string): string {
+  return `${damAssetBase}/dam/${assetId}`;
+}
+
+const FORMAT_PARAMS: Record<string, string> = {
+  'image/avif': 'avif',
+  'image/webp': 'webp',
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+};
+
+function sourceFormatParams(source: ImageSource): string {
+  const fm = FORMAT_PARAMS[source.type] ?? 'webp';
+  return `fm=${fm}&q=${DAM_IMAGE_QUALITY}`;
+}
+
+function srcsetWidth(assetId: string, source: ImageSource, width: number): string {
+  const params = [`w=${width}`];
+  if (source.fit === 'crop' && source.width && source.height) {
+    const height = Math.round((width * source.height) / source.width);
+    params.push(`h=${height}`, 'fit=crop');
+  } else {
+    params.push('fit=max');
+  }
+  params.push(sourceFormatParams(source));
+  return `${damAssetUrl(assetId)}?${params.join('&')} ${width}w`;
+}
+
+function damImageAttrs(image: Image, primary: ImageSource): ImageAttrs {
+  const base: ImageAttrs = {
+    src: damAssetUrl(image.assetId),
+    alt: image.alt,
+    width: primary.width && primary.width > 0 ? primary.width : undefined,
+    height: primary.height && primary.height > 0 ? primary.height : undefined,
+    loading: 'lazy',
+    decoding: 'async',
+  };
+  if (primary.widths && primary.widths.length > 0) {
+    // Primary src at the largest declared width; srcset covers them all.
+    const largest = primary.widths[primary.widths.length - 1];
+    const params = [`w=${largest}`];
+    if (primary.fit === 'crop' && primary.width && primary.height) {
+      params.push(`h=${Math.round((largest * primary.height) / primary.width)}`, 'fit=crop');
+    } else {
+      params.push('fit=max');
+    }
+    params.push(sourceFormatParams(primary));
+    base.src = `${damAssetUrl(image.assetId)}?${params.join('&')}`;
+    if (primary.widths.length > 1) {
+      base.srcSet = primary.widths.map((w) => srcsetWidth(image.assetId, primary, w)).join(', ');
+    }
+  }
+  return base;
+}
+
+function staticImageAttrs(image: Image, primary: ImageSource): ImageAttrs {
+  return {
+    src: primary.src ?? '',
+    alt: image.alt,
+    width: primary.width && primary.width > 0 ? primary.width : undefined,
+    height: primary.height && primary.height > 0 ? primary.height : undefined,
+    loading: 'lazy',
+    decoding: 'async',
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Shared attrs helper — consumed by React, Astro, and Svelte components
 // ---------------------------------------------------------------------------
 
 export type ImageAttrs = Record<string, unknown>;
 
+/** True when the image resolves to authored static bytes, not a DAM asset. */
+export function isStaticImage(image: Image): boolean {
+  return image.assetId.startsWith('static:');
+}
+
 /**
  * The primary rendition of an image — its first source entry.
  */
@@ -100,24 +207,21 @@ export function primaryImageSource(image: Image): ImageSource {
  * 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. 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.
+ * and spread the result into the native element. No HTML string
+ * serialization. DAM images construct their /dam/{assetId} permalink and
+ * srcset here from the slot-declared widths; static images pass their
+ * authored src through. 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 = image.sources[0];
   const unscoped = image.sources.find((s) => !s.media) ?? primary;
 
-  return {
-    src: primary.src,
-    alt: image.alt,
-    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,
-  };
+  const base = isStaticImage(image) ? staticImageAttrs(image, primary) : damImageAttrs(image, primary);
+
+  if (unscoped?.sizes) {
+    base.sizes = unscoped.sizes;
+  }
+  return { ...base, ...overrides };
 }

package/src/types/video.ts

@@ -11,7 +11,7 @@ export interface VideoSource {
 }
 
 // ---------------------------------------------------------------------------
-// Video — DAM-backed video asset with compiler-resolved derivatives
+// Video — DAM-backed video asset with compiler-resolved live asset URLs
 //
 // Content authors write: { "$type": "dam.assetRef", ... }
 // or for static files: { "$type": "static.assetRef", "src": "/path" }

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

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

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

@@ -262,6 +262,7 @@ site or design into ACI.
 
 ## Deep Dive: DAM Delivery
 
-Read `.agents/skills/dam-delivery/SKILL.md` for signed on-demand image
-transform URLs: when to mint them, the closed parameter contract, expiry
-semantics, and why they must never be baked into published payloads.
+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.