@gradial/aci 0.1.20-preview.3 → 0.1.20

package/src/cli/compile-registry.mjs

@@ -3,7 +3,8 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
-import { GradialImageSchema } from '../types/image.ts';
+import { ImageSchema } from '../types/image.ts';
+import { getBlockRefMeta } from '../types/block-ref.ts';
 
 const DATA_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
 
@@ -47,30 +48,20 @@ async function compileRegistry(options) {
   const schemaFiles = [];
   for (const [index, component] of components.entries()) {
     validateComponent(component, index, seenComponents);
-    const schema = compileSchema(component.schema, component.name);
-    const schemaFile = `schemas/${component.name}.schema.json`;
+    const componentId = component.id;
+    const schema = compileSchema(component.props, componentId);
+    const schemaFile = `schemas/${componentId}.schema.json`;
     const schemaPath = path.join(outDir, schemaFile);
     await writeFile(schemaPath, JSON.stringify(schema, null, 2) + '\n');
     schemaFiles.push(schemaPath);
-    const varyDimensions = component.varyDimensions ?? component.vary;
     const imageSlots = normalizeImageSlots(component.imageSlots);
-    const renderModes = component.renderModes ?? component.render;
+    const slots = extractBlockSlots(component.props, componentId);
     componentEntries.push({
-      name: component.name,
-      schemaFile,
-      render: renderModes ? {
-        static: Boolean(renderModes.canStatic ?? renderModes.static),
-        ssr: Boolean(renderModes.canSSR ?? renderModes.ssr),
-        clientIsland: Boolean(renderModes.canClientIsland ?? renderModes.clientIsland),
-      } : { static: true, ssr: true, clientIsland: false },
-      renderModes: renderModes ? {
-        canStatic: Boolean(renderModes.canStatic ?? renderModes.static),
-        canSSR: Boolean(renderModes.canSSR ?? renderModes.ssr),
-        canClientIsland: Boolean(renderModes.canClientIsland ?? renderModes.clientIsland),
-      } : { canStatic: true, canSSR: true, canClientIsland: false },
-      ...(component.defaultIslandMode ? { defaultIslandMode: component.defaultIslandMode } : {}),
-      ...(varyDimensions?.length ? { vary: varyDimensions, varyDimensions } : {}),
+      id: componentId,
+      name: componentId,
+      props: schemaFile,
       ...(Object.keys(imageSlots).length ? { imageSlots } : {}),
+      ...(Object.keys(slots).length ? { slots } : {}),
     });
   }
 
@@ -95,16 +86,14 @@ async function compileRegistry(options) {
     });
   }
 
-  // Post-compilation: detect nested block patterns in JSON schemas and
-  // validate that referenced component names exist in the registry.
-  const knownNames = new Set(componentEntries.map((c) => c.name));
+  const knownNames = new Set(componentEntries.map((c) => c.id));
   for (const entry of componentEntries) {
-    const schemaPath = path.join(outDir, entry.schemaFile);
-    const schemaRaw = await import('node:fs/promises').then((fs) => fs.readFile(schemaPath, 'utf-8'));
-    const schema = JSON.parse(schemaRaw);
-    const nestedBlocks = collectNestedBlockRefs(schema, knownNames, entry.name);
-    if (nestedBlocks.length > 0) {
-      entry.nestedBlocks = nestedBlocks;
+    for (const [slotName, slot] of Object.entries(entry.slots ?? {})) {
+      for (const childName of slot.allowed) {
+        if (!knownNames.has(childName)) {
+          throw new Error(`${entry.id}.slots.${slotName}.allowed references unknown component "${childName}"`);
+        }
+      }
     }
   }
 
@@ -148,29 +137,84 @@ function validateDataModel(dataModel, index, seen) {
 
 function validateComponent(component, index, seen) {
   if (!component || typeof component !== 'object') throw new Error(`components[${index}] must be an object`);
-  if (!component.name) throw new Error(`components[${index}].name is required`);
-  if (seen.has(component.name)) throw new Error(`duplicate component name ${component.name}`);
-  seen.add(component.name);
-  if (!component.schema) throw new Error(`components[${index}].schema is required`);
-  validateZodSubset(component.schema, `components[${index}].schema`);
+  if (!component.id) throw new Error(`components[${index}].id is required`);
+  if (seen.has(component.id)) throw new Error(`duplicate component id ${component.id}`);
+  seen.add(component.id);
+  if (!component.props) throw new Error(`components[${index}].props is required`);
+  validateZodSubset(component.props, `components[${index}].props`);
   validateImageSlotSchemaMatch(component, index);
 }
 
 function validateImageSlotSchemaMatch(component, index) {
   const imageSlots = normalizeImageSlots(component.imageSlots);
-  const imageFields = collectGradialImageFields(component.schema);
+  const imageFields = collectImageFields(component.props);
   for (const field of imageFields) {
     if (!Object.prototype.hasOwnProperty.call(imageSlots, field)) {
-      throw new Error(`components[${index}].imageSlots.${field} is required because schema field ${field} uses GradialImageSchema`);
+      throw new Error(`components[${index}].imageSlots.${field} is required because props field ${field} uses an image schema`);
     }
   }
   for (const field of Object.keys(imageSlots)) {
     if (!imageFields.has(field)) {
-      throw new Error(`components[${index}].schema.${field} must use GradialImageSchema because imageSlots.${field} is declared`);
+      throw new Error(`components[${index}].props.${field} must use an image schema because imageSlots.${field} is declared`);
     }
   }
 }
 
+function extractBlockSlots(schema, componentId) {
+  const shape = getSchemaShape(schema);
+  if (!shape) return {};
+  const out = {};
+  for (const [name, fieldSchema] of Object.entries(shape)) {
+    const unwrapped = unwrapOptionalSchema(fieldSchema);
+    const meta = getBlockRefMeta(unwrapped) ?? getBlockRefMeta(unwrapArraySchema(unwrapped));
+    if (meta) {
+      out[name] = {
+        allowed: [...meta.allowed],
+        multiple: meta.multiple,
+        required: false,
+      };
+    }
+  }
+  return out;
+}
+
+function unwrapOptionalSchema(schema) {
+  let current = schema;
+  const seen = new Set();
+  while (current && typeof current === 'object' && !seen.has(current)) {
+    seen.add(current);
+    const def = current._def;
+    if (!def || typeof def !== 'object') break;
+    const type = def.type;
+    const typeName = def.typeName;
+    if (type === 'optional' || type === 'nullable' || type === 'default' ||
+        typeName === 'ZodOptional' || typeName === 'ZodNullable' || typeName === 'ZodDefault') {
+      const inner = def.innerType ?? def.schema;
+      if (inner) { current = inner; continue; }
+    }
+    break;
+  }
+  return current;
+}
+
+function getSchemaShape(schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  const def = schema._def;
+  if (!def) return null;
+  const shape = typeof def.shape === 'function' ? def.shape() : def.shape;
+  if (shape && typeof shape === 'object') return shape;
+  return null;
+}
+
+function unwrapArraySchema(schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  const def = schema._def;
+  if (!def) return null;
+  if (def.type === 'array' && def.element) return def.element;
+  if (def.typeName === 'ZodArray' && def.type) return def.type;
+  return null;
+}
+
 function normalizeImageSlots(imageSlots) {
   if (imageSlots == null) return {};
   if (typeof imageSlots !== 'object' || Array.isArray(imageSlots)) {
@@ -228,34 +272,34 @@ function normalizeSlotOutput(slotKey, output, outputIndex) {
   };
 }
 
-function collectGradialImageFields(schema) {
+function collectImageFields(schema) {
   const out = new Set();
 
-  collectGradialImageFieldsFromSchema(schema, '', out);
+  collectImageFieldsFromSchema(schema, '', out);
 
   return out;
 }
 
-function collectGradialImageFieldsFromSchema(schema, prefix, out) {
+function collectImageFieldsFromSchema(schema, prefix, out) {
   if (!schema) {
     return;
   }
 
-  if (prefix && isGradialImageSchema(schema)) {
+  if (prefix && isImageSchema(schema)) {
     out.add(prefix);
     return;
   }
 
   const itemSchema = arrayItemSchema(schema);
   if (itemSchema) {
-    collectGradialImageFieldsFromSchema(itemSchema, prefix, out);
+    collectImageFieldsFromSchema(itemSchema, prefix, out);
     return;
   }
 
   const unionOptions = unionOptionSchemas(schema);
   if (unionOptions) {
     for (const option of unionOptions) {
-      collectGradialImageFieldsFromSchema(option, prefix, out);
+      collectImageFieldsFromSchema(option, prefix, out);
     }
     return;
   }
@@ -268,7 +312,7 @@ function collectGradialImageFieldsFromSchema(schema, prefix, out) {
 
   for (const [field, fieldSchema] of Object.entries(shape)) {
     const nextPrefix = prefix ? `${prefix}.${field}` : field;
-    collectGradialImageFieldsFromSchema(fieldSchema, nextPrefix, out);
+    collectImageFieldsFromSchema(fieldSchema, nextPrefix, out);
   }
 }
 
@@ -299,21 +343,27 @@ function arrayItemSchema(schema) {
   return null;
 }
 
-function isGradialImageSchema(schema) {
+function isImageSchema(schema) {
   const unwrapped = unwrapSchema(schema);
-  if (unwrapped === GradialImageSchema) return true;
+  if (unwrapped === ImageSchema) return true;
   try {
     const compiled = z.toJSONSchema(unwrapped, {
       target: 'draft-2020-12',
       unrepresentable: 'throw',
     });
-    const sources = compiled?.properties?.sources;
-    const sourcesIsArray = sources?.type === 'array'
-      || (Array.isArray(sources?.anyOf) && sources.anyOf.some((s) => s?.type === 'array'));
+    const properties = compiled?.properties ?? {};
+    const required = new Set(compiled?.required ?? []);
     return compiled?.type === 'object'
-      && compiled?.properties?.$type?.const === 'gradial.image'
-      && compiled?.properties?.fallback?.type === 'object'
-      && sourcesIsArray;
+      && 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 {
     return false;
   }
@@ -324,7 +374,7 @@ function unwrapSchema(schema) {
   const seen = new Set();
   while (current && !seen.has(current)) {
     seen.add(current);
-    if (current === GradialImageSchema) return current;
+    if (current === ImageSchema) return current;
     const def = current._def;
     const next = def?.innerType ?? def?.schema;
     if (!next) break;
@@ -381,6 +431,13 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
         id: { type: 'string', minLength: 1 },
         component: { type: 'string' },
         props: { type: 'object' },
+        slots: {
+          type: 'object',
+          additionalProperties: {
+            type: 'array',
+            items: { $ref: '#/$defs/baseBlock' },
+          },
+        },
       },
     },
     damAssetRef: {
@@ -397,11 +454,11 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
   };
   const oneOf = [];
   for (const entry of componentEntries) {
-    const schemaPath = path.join(outDir, entry.schemaFile);
+    const schemaPath = path.join(outDir, entry.props);
     const raw = await readFile(schemaPath, 'utf-8');
     const componentSchema = JSON.parse(raw);
     const { $schema: _s, title: _t, ...propsSchema } = componentSchema;
-    replaceGradialImagesWithDamAssetRef(propsSchema, defs.damAssetRef);
+    replaceImagesWithDamAssetRef(propsSchema, defs.damAssetRef);
     const defName = `${entry.name}Block`;
     defs[defName] = {
       allOf: [
@@ -453,37 +510,37 @@ async function generatePageSchema(schemaDir, componentEntries, outDir) {
   return pageSchemaPath;
 }
 
-function replaceGradialImagesWithDamAssetRef(schema, damAssetRef) {
+function replaceImagesWithDamAssetRef(schema, damAssetRef) {
   if (!schema || typeof schema !== 'object') return schema;
   if (schema.$ref) return;
   if (Array.isArray(schema.anyOf)) {
-    for (const s of schema.anyOf) replaceGradialImagesWithDamAssetRef(s, damAssetRef);
+    for (const s of schema.anyOf) replaceImagesWithDamAssetRef(s, damAssetRef);
   }
   if (Array.isArray(schema.allOf)) {
-    for (const s of schema.allOf) replaceGradialImagesWithDamAssetRef(s, damAssetRef);
+    for (const s of schema.allOf) replaceImagesWithDamAssetRef(s, damAssetRef);
   }
   if (Array.isArray(schema.oneOf)) {
-    for (const s of schema.oneOf) replaceGradialImagesWithDamAssetRef(s, damAssetRef);
+    for (const s of schema.oneOf) replaceImagesWithDamAssetRef(s, damAssetRef);
   }
   if (schema.properties) {
     for (const [key, value] of Object.entries(schema.properties)) {
-      if (isJsonGradialImage(value)) {
+      if (isJsonImage(value)) {
         schema.properties[key] = { $ref: '#/$defs/damAssetRef' };
       } else {
-        replaceGradialImagesWithDamAssetRef(value, damAssetRef);
+        replaceImagesWithDamAssetRef(value, damAssetRef);
       }
     }
   }
   if (schema.items) {
-    if (isJsonGradialImage(schema.items)) {
+    if (isJsonImage(schema.items)) {
       schema.items = { $ref: '#/$defs/damAssetRef' };
     } else {
-      replaceGradialImagesWithDamAssetRef(schema.items, damAssetRef);
+      replaceImagesWithDamAssetRef(schema.items, damAssetRef);
     }
   }
 }
 
-function isJsonGradialImage(node) {
+function isJsonImage(node) {
   return node?.type === 'object'
     && node?.properties?.$type?.const === 'gradial.image';
 }

package/src/cli/validate-content.mjs

@@ -53,20 +53,17 @@ async function validateContent(options) {
   const registry = JSON.parse(registryRaw);
 
   // Build schema map: component name → JSON Schema object
-  // Build nested blocks map: component name → array of { path, allow? }
   const schemaMap = new Map();
   const knownComponents = new Set();
-  const nestedBlocksMap = new Map();
+  const componentMap = new Map();
   for (const component of registry.components) {
     knownComponents.add(component.name);
-    if (component.schemaFile) {
-      const schemaPath = path.join(registryDir, component.schemaFile);
+    componentMap.set(component.name, component);
+    if (component.props) {
+      const schemaPath = path.join(registryDir, component.props);
       const schemaRaw = await readFile(schemaPath, 'utf-8');
       schemaMap.set(component.name, JSON.parse(schemaRaw));
     }
-    if (Array.isArray(component.nestedBlocks) && component.nestedBlocks.length > 0) {
-      nestedBlocksMap.set(component.name, component.nestedBlocks);
-    }
   }
 
   // Find all compiled route files
@@ -134,10 +131,7 @@ async function validateContent(options) {
         });
       }
 
-      // Recursively validate nested blocks (blockRef patterns)
-      const nestedIssues = validateNestedBlocks(
-        block.component, props, knownComponents, schemaMap, nestedBlocksMap,
-      );
+      const nestedIssues = validateNestedSlots(block, componentMap, schemaMap);
       for (const issue of nestedIssues) {
         collector.push({
           page: relativePath,
@@ -360,83 +354,52 @@ function resolveRef(ref, rootSchema) {
 // ---------------------------------------------------------------------------
 
 // ---------------------------------------------------------------------------
-// Nested block validation — recursively validates blocks inside blockRef slots
+// Block ref validation — recursively validates nested blocks inside props.
 // ---------------------------------------------------------------------------
 
-function validateNestedBlocks(parentComponent, props, knownComponents, schemaMap, nestedBlocksMap) {
+function validateNestedSlots(parentBlock, componentMap, schemaMap, path = 'props') {
   const issues = [];
-  // Find all block-shaped arrays in props by walking the data
-  const nestedBlocks = findNestedBlockArrays(props);
-  for (const { path: blockPath, blocks } of nestedBlocks) {
+  const parentComponent = componentMap.get(parentBlock.component);
+  if (!parentComponent) return issues;
+
+  const blockSlots = parentComponent.slots ?? {};
+  for (const [slotName, slot] of Object.entries(blockSlots)) {
+    const blocks = parentBlock.props?.[slotName];
+    if (!Array.isArray(blocks)) {
+      if (slot.required) {
+        issues.push({ path: `${path}.${slotName}`, message: `${parentBlock.component}: required block ref "${slotName}" has no children` });
+      }
+      continue;
+    }
+    if (!slot.multiple && blocks.length > 1) {
+      issues.push({ path: `${path}.${slotName}`, message: `${parentBlock.component}: block ref "${slotName}" allows at most one child` });
+    }
     for (const [index, nestedBlock] of blocks.entries()) {
-      if (!nestedBlock || typeof nestedBlock !== 'object') continue;
-      const childComponent = nestedBlock.component;
-      if (!childComponent || typeof childComponent !== 'string') continue;
-
-      const nestedPath = `${blockPath}[${index}]`;
-
-      // Check nested component exists in registry
-      if (!knownComponents.has(childComponent)) {
-        issues.push({
-          path: `${nestedPath}.component`,
-          message: `${parentComponent} → ${nestedPath}: unknown nested component "${childComponent}"`,
-        });
+      const nestedPath = `${path}.${slotName}[${index}]`;
+      if (!nestedBlock || typeof nestedBlock !== 'object' || typeof nestedBlock.component !== 'string') {
+        issues.push({ path: nestedPath, message: `${parentBlock.component}: block ref child must be a block` });
         continue;
       }
 
-      // Validate nested block's props against its own schema
-      const childSchema = schemaMap.get(childComponent);
-      if (!childSchema) continue;
-
-      const childProps = nestedBlock.props ?? {};
-      const childIssues = validateJsonSchema(childProps, childSchema, `${nestedPath}.props`);
-      for (const issue of childIssues) {
-        issues.push({
-          nestedComponent: childComponent,
-          path: issue.path,
-          message: `${parentComponent} → ${childComponent}: ${issue.message}`,
-        });
+      if (!componentMap.has(nestedBlock.component)) {
+        issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: unknown nested component "${nestedBlock.component}"` });
+        continue;
       }
-
-      // Recurse further if the nested component itself has nested blocks
-      const deeperIssues = validateNestedBlocks(
-        childComponent, childProps, knownComponents, schemaMap, nestedBlocksMap,
-      );
-      issues.push(...deeperIssues);
-    }
-  }
-  return issues;
-}
-
-/**
- * Walks a props object looking for arrays of block-shaped objects
- * (objects with `component` + `props` fields).
- */
-function findNestedBlockArrays(obj, prefix = 'props') {
-  const results = [];
-  if (!obj || typeof obj !== 'object') return results;
-
-  for (const [key, value] of Object.entries(obj)) {
-    const currentPath = `${prefix}.${key}`;
-    if (Array.isArray(value)) {
-      // Check if array contains block-shaped objects
-      const hasBlocks = value.some(
-        (item) => item && typeof item === 'object' && typeof item.component === 'string' && 'props' in item,
-      );
-      if (hasBlocks) {
-        results.push({ path: currentPath, blocks: value });
+      if (!slot.allowed.includes(nestedBlock.component)) {
+        issues.push({ path: `${nestedPath}.component`, message: `${parentBlock.component}: component "${nestedBlock.component}" is not allowed in block ref "${slotName}"` });
       }
-      // Also recurse into array items that are objects (for nested structures like tabs[].blocks[])
-      for (const item of value) {
-        if (item && typeof item === 'object' && !Array.isArray(item)) {
-          results.push(...findNestedBlockArrays(item, currentPath + '[]'));
+
+      const childSchema = schemaMap.get(nestedBlock.component);
+      const childProps = nestedBlock.props ?? {};
+      if (childSchema) {
+        for (const issue of validateJsonSchema(childProps, childSchema, `${nestedPath}.props`)) {
+          issues.push({ nestedComponent: nestedBlock.component, path: issue.path, message: `${parentBlock.component} → ${nestedBlock.component}: ${issue.message}` });
         }
       }
-    } else if (typeof value === 'object' && value !== null) {
-      results.push(...findNestedBlockArrays(value, currentPath));
+      issues.push(...validateNestedSlots(nestedBlock, componentMap, schemaMap, nestedPath));
     }
   }
-  return results;
+  return issues;
 }
 
 function collectBlocks(pageData) {

package/src/types/image.ts

@@ -1,28 +1,47 @@
 import { z } from 'zod';
 
+// ---------------------------------------------------------------------------
+// Image source variant (responsive derivative)
+//
+// 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.
+// ---------------------------------------------------------------------------
+
 export interface ImageSource {
+  /** Derivative URL. */
   src: string;
+  /** Intrinsic width in pixels. */
   width: number;
+  /** Intrinsic height in pixels. */
   height: number;
+  /** MIME type hint, e.g. image/webp. */
   type: string;
 }
 
-export interface PictureSource {
-  media?: string;
-  type: string;
-  srcset: string;
-  sizes?: string;
-}
+// ---------------------------------------------------------------------------
+// Image — DAM-backed image asset with compiler-resolved derivatives
+//
+// Content authors write an asset reference: { "$type": "dam.assetRef", ... }
+// The compiler resolves it to this Image value based on the asset's media type.
+// ---------------------------------------------------------------------------
 
-export interface GradialImage {
+export interface Image {
+  /** Discriminator — always 'gradial.image'. */
   $type: 'gradial.image';
+  /** DAM asset identifier. */
   assetId: string;
+  /** DAM version identifier. */
   versionId: string;
+  /** Accessible description of the image content. */
   alt: string;
-  fallback: ImageSource;
-  sources: PictureSource[] | null;
+  /** Responsive derivative variants produced for the asset slot. */
+  sources: ImageSource[];
 }
 
+// ---------------------------------------------------------------------------
+// Image slot contract (declared by components that accept image props)
+// ---------------------------------------------------------------------------
+
 export interface ImageSlotContract {
   outputs: SlotOutput[];
   formats: string[];
@@ -35,66 +54,66 @@ export interface SlotOutput {
   media?: string;
 }
 
-export const GradialImageSchema = z.object({
+// ---------------------------------------------------------------------------
+// Zod schema
+// ---------------------------------------------------------------------------
+
+export const ImageSourceSchema = z.object({
+  src: z.string().min(1),
+  width: z.number().int().nonnegative(),
+  height: z.number().int().nonnegative(),
+  type: z.string().min(1),
+});
+
+export const ImageSchema = z.object({
   $type: z.literal('gradial.image'),
   assetId: z.string().min(1),
   versionId: z.string().min(1),
   alt: z.string(),
-  fallback: z.object({
-    src: z.string().min(1),
-    width: z.number().int().nonnegative(),
-    height: z.number().int().nonnegative(),
-    type: z.string().min(1),
-  }),
-  sources: z.array(z.object({
-    media: z.string().optional(),
-    type: z.string().min(1),
-    srcset: z.string().min(1),
-    sizes: z.string().optional(),
-  })).nullable().default([]),
+  sources: z.array(ImageSourceSchema).min(1),
 });
 
-export type ImageHTMLAttributes = Record<string, string | number | boolean | undefined | null>;
+// ---------------------------------------------------------------------------
+// Shared attrs helper — consumed by React, Astro, and Svelte components
+// ---------------------------------------------------------------------------
 
-export function renderImageHTML(image: GradialImage, attrs: ImageHTMLAttributes = {}): string {
-  const imgAttrs = renderAttrs({
-    ...attrs,
-    src: image.fallback.src,
-    alt: image.alt,
-    width: image.fallback.width > 0 ? image.fallback.width : undefined,
-    height: image.fallback.height > 0 ? image.fallback.height : undefined,
-  });
-  const img = `<img${imgAttrs}>`;
-  if (!image.sources?.length) {
-    return img;
-  }
-  const sources = image.sources.map((source) => `<source${renderAttrs({
-    media: source.media,
-    type: source.type,
-    srcset: source.srcset,
-    sizes: source.sizes,
-  })}>`).join('');
-  return `<picture>${sources}${img}</picture>`;
-}
+export type ImageAttrs = Record<string, unknown>;
 
-function renderAttrs(attrs: ImageHTMLAttributes): string {
-  const rendered = Object.entries(attrs)
-    .filter(([, value]) => value !== undefined && value !== null && value !== false)
-    .map(([name, value]) => value === true ? escapeName(name) : `${escapeName(name)}="${escapeAttr(String(value))}"`);
-  if (!rendered.length) {
-    return '';
-  }
-  return ' ' + rendered.join(' ');
+/**
+ * Picks the primary variant from an image's sources.
+ * Uses the largest width; ties fall back to the first entry.
+ */
+export function primaryImageSource(image: Image): ImageSource {
+  return image.sources.reduce((largest, source) =>
+    source.width > largest.width ? source : largest,
+    image.sources[0],
+  );
 }
 
-function escapeName(name: string): string {
-  return name.replace(/[^A-Za-z0-9_:-]/g, '');
-}
+/**
+ * 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.
+ */
+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(', ');
 
-function escapeAttr(value: string): string {
-  return value
-    .replace(/&/g, '&amp;')
-    .replace(/"/g, '&quot;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+  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,
+    loading: 'lazy',
+    decoding: 'async',
+    ...overrides,
+  };
 }