@taprootio/site-authoring 0.29.0 → 0.31.0

package/src/content/components.js

@@ -8,6 +8,8 @@ import registry from "./free-form-section-registry.json" with { type: "json" };
 import { hasAsciiControl } from "../errors.js";
 import { isSocialLinkUrl, SOCIAL_LINK_URL_MAX_LENGTH, trimSocialLinkInput } from "../social-link-url.js";
 import socialPlatforms from "../social-platforms.json" with { type: "json" };
+import { IMAGE_DESCRIPTION_MODES } from "./image-description-validation.js";
+import { stripImageDescriptionHydration } from "./image-description-document.js";
 import {
   CONTENT_ERROR_CODES as CODES,
   CONTENT_LIMITS,
@@ -69,8 +71,8 @@ const list = (item, options = {}) => Object.freeze({ kind: "array", item, ...opt
 const shape = (fields, options = {}) => Object.freeze({ kind: "object", fields: Object.freeze(fields), ...options });
 /**
  * A processed-image record or null. `required` refuses null, `altRequired`
- * refuses a blank alt and `dimensionsRequired` demands positive width and
- * height, for a component whose images are the content (TR01322).
+ * requires authored alt unless inherited, and `dimensionsRequired` demands
+ * positive width and height for a component whose images are the content (TR01322).
  */
 const image = (options = {}) => Object.freeze({ kind: "image", ...options });
 /**
@@ -115,6 +117,7 @@ const COMPONENT_IMAGE_FIELDS = Object.freeze({
   width: num({ integer: true, minimum: 0 }),
   height: num({ integer: true, minimum: 0 }),
   alt: str(),
+  descriptionMode: Object.freeze({ ...enumOf(...IMAGE_DESCRIPTION_MODES), nullable: true }),
 });
 
 /**
@@ -247,6 +250,22 @@ const LATEST_POSTS = Object.freeze({
   bannerScheme: enumOf("auto", "light", "dark"),
 });
 
+/** The registry owns the row heights; the help text and the renderer derive from the same map. */
+const IMAGE_ROW_HEIGHTS = registry.components["image-row"].heights;
+const IMAGE_ROW_HEIGHT_SIZES = Object.entries(IMAGE_ROW_HEIGHTS)
+  .map(([name, rem]) => `${name} ${rem} (${Number.parseFloat(rem) * 16}px)`)
+  .join(", ");
+const IMAGE_ROW_HEIGHT_HELP =
+  `Each image's height: ${IMAGE_ROW_HEIGHT_SIZES} at a 16px root; width follows each image's own shape, never cropped or framed.`;
+
+/** The registry owns the card image spacings too; each side takes the same four names (TR01326). */
+const CARD_IMAGE_SPACINGS = registry.components["card-grid"].imageSpacings;
+const CARD_IMAGE_SPACING_NAMES = Object.keys(CARD_IMAGE_SPACINGS);
+const CARD_IMAGE_SPACING_VALUES =
+  `none (0), small (${CARD_IMAGE_SPACINGS.small}), medium (${CARD_IMAGE_SPACINGS.medium}) or text (the same padding as around the card's text)`;
+const CARD_IMAGE_SPACING_SIDE_HELP = (side, defaults) =>
+  `Space on the ${side} of each card image: ${CARD_IMAGE_SPACING_VALUES}. Left out, it is ${defaults}.`;
+
 /** `CardGridData`. `cropState` is the one genuinely optional field in types.ts. */
 const CARD_GRID = Object.freeze({
   cards: withOmission(
@@ -262,6 +281,36 @@ const CARD_GRID = Object.freeze({
   columns: num({ values: Object.freeze([2, 3]) }),
   presentation: enumOf("cards", "editorial", "featured", "poster"),
   imageAspect: enumOf("auto", "landscape", "square", "portrait"),
+  imageFit: withOmission(
+    described(
+      enumOf("cover", "contain"),
+      "cover fills the card and crops each image to imageAspect; contain shows the whole image at imageHeight, never cropped or framed, and needs each image's width and height.",
+    ),
+    { kind: "value", value: "cover" },
+  ),
+  imageHeight: described(
+    enumOf(...Object.keys(IMAGE_ROW_HEIGHTS)),
+    `${IMAGE_ROW_HEIGHT_HELP} Only with imageFit contain, where it is medium when left out; refused otherwise.`,
+  ),
+  imageAlign: described(
+    enumOf("start", "center", "end"),
+    "Where each whole image sits across its card, not the text: start is the left edge and end the right edge in a left-to-right page. Only with imageFit contain, where it is start when left out; refused otherwise.",
+  ),
+  imageSpacing: described(
+    shape({
+      top: described(enumOf(...CARD_IMAGE_SPACING_NAMES), CARD_IMAGE_SPACING_SIDE_HELP("top", "none with cover and small with contain")),
+      bottom: described(enumOf(...CARD_IMAGE_SPACING_NAMES), CARD_IMAGE_SPACING_SIDE_HELP("bottom", "none")),
+      start: described(
+        enumOf(...CARD_IMAGE_SPACING_NAMES),
+        CARD_IMAGE_SPACING_SIDE_HELP("left edge (start)", "none with cover and text with contain"),
+      ),
+      end: described(
+        enumOf(...CARD_IMAGE_SPACING_NAMES),
+        CARD_IMAGE_SPACING_SIDE_HELP("right edge (end)", "none with cover and text with contain"),
+      ),
+    }),
+    "Space around each card image; name only the sides to change, and a side left out keeps its default for the fit. With imageFit contain, start moves an image aligned to start and end moves one aligned to end; otherwise they only limit how wide the image can be.",
+  ),
   interaction: enumOf("none", "lift", "zoom", "caption-reveal"),
   borderWidth: num({
     integer: true,
@@ -274,6 +323,7 @@ const CARD_GRID = Object.freeze({
 const IMAGE_BANNER = Object.freeze({
   image: image(),
   altText: str(),
+  descriptionMode: Object.freeze({ ...enumOf(...IMAGE_DESCRIPTION_MODES), nullable: true }),
   overlayText: str(),
   // One supporting sentence and at most one link under the headline: the copy
   // stack Espalier 6.1 lays out with a bounded measure (TR00819).
@@ -383,9 +433,11 @@ const FORM = Object.freeze({
  * The image field table an image spec validates against. The shared table
  * leaves alt and dimensions optional; a spec that requires them swaps in
  * stricter entries at the same positions so canonical order is unchanged.
+ * Inherited alt is delivery state, removed before a workspace round trip.
  */
-function imageFieldsFor(spec) {
-  if (!spec.altRequired && !spec.dimensionsRequired) return COMPONENT_IMAGE_FIELDS;
+function imageFieldsFor(spec, value) {
+  const altRequired = spec.altRequired && value?.descriptionMode !== "inherit";
+  if (!altRequired && !spec.dimensionsRequired) return COMPONENT_IMAGE_FIELDS;
   return Object.freeze({
     ...COMPONENT_IMAGE_FIELDS,
     ...(spec.dimensionsRequired
@@ -394,7 +446,7 @@ function imageFieldsFor(spec) {
         height: num({ integer: true, minimum: 1, required: true }),
       }
       : {}),
-    ...(spec.altRequired
+    ...(altRequired
       ? {
         alt: str({
           required: true,
@@ -408,14 +460,6 @@ function imageFieldsFor(spec) {
   });
 }
 
-/** The registry owns the row heights; the help text and the renderer derive from the same map. */
-const IMAGE_ROW_HEIGHTS = registry.components["image-row"].heights;
-const IMAGE_ROW_HEIGHT_HELP = `Each image's height: ${
-  Object.entries(IMAGE_ROW_HEIGHTS)
-    .map(([name, rem]) => `${name} ${rem} (${Number.parseFloat(rem) * 16}px)`)
-    .join(", ")
-} at a 16px root; width follows each image's own shape, never cropped or framed.`;
-
 /**
  * `ImageRowData` (TR01322). A row of pictures carries no other text, so every
  * image needs alt text and the dimensions the row sizes it by.
@@ -648,7 +692,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       "Icon images need descriptive alt text when they convey information; otherwise use an empty alt value.",
       "Item title and description are plain text: an item's url makes the whole item the link, and no link can be placed inside the text. Put linked prose in a paragraph beside the grid.",
       "iconSize sets the icon box: small 3rem (48px), medium 6rem (96px), large 10rem (160px), xlarge 16rem (256px) at a 16px root.",
-      "Icons are cropped to a square and framed by the site's image border. For badges, logos or any picture that must keep its shape, use the image-row component instead.",
+      "Icons are cropped to a square and framed by the site's image border. For badges, logos or any picture that must keep its shape, use the image-row component instead, or a card-grid with imageFit contain when each needs a card.",
     ],
     {
       items: [
@@ -713,6 +757,14 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       "Every linked card needs a title that describes its destination.",
       "Card images need descriptive alt text unless they are decorative.",
       "Card title and description are plain text: a card's linkUrl makes the whole card the link, and no link can be placed inside the text. Put linked prose in a paragraph beside the grid.",
+      "Images are cropped when imageFit is cover, the default: each is cut to the fixed imageAspect, while imageAspect auto follows the picture's own shape up to the page's height cap. imageFit contain never crops; it shows the whole image.",
+      "For a logo or mark use imageFit contain with a tightly cropped file that has no built-in padding, and set the size with imageHeight and the space around it with imageSpacing, not by padding the file.",
+      `imageHeight sets the height of a whole image: ${IMAGE_ROW_HEIGHT_SIZES} at a 16px root. Width follows the image's shape, and an image wider than its card shrinks to fit.`,
+      "imageHeight and imageAlign are refused with cover, and when imageFit is left out, which means cover. With contain, imageHeight is medium and imageAlign is start when left out. imageAlign moves the image only, never the text.",
+      `imageSpacing is an object with any of top, bottom, start and end, each ${CARD_IMAGE_SPACING_VALUES}. It works with either fit.`,
+      "A side left out of imageSpacing keeps its default, so name only the sides to change. Defaults for cover: none on every side. Defaults for contain: top small, bottom none, start and end text.",
+      "imageFit contain needs each card image's width and height, which media upload records; a card image with a missing or zero size is refused.",
+      "A card with a saved crop shows that crop under contain; replace the image with the whole file to show all of it. The Zoom interaction has no effect on a whole image.",
     ],
     {
       cards: [
@@ -856,7 +908,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     "A wrapping row of pictures at one height, each with alt text and an optional link, never cropped or framed.",
     { height: "medium", align: "start" },
     [
-      "Every image needs alt text: a row of pictures carries no other text. For a linked image the alt is the link's name, so name the destination or action, such as \"Download on the App Store\"; for an unlinked image, describe the picture.",
+      "Every image needs alt text unless its descriptionMode is inherit, in which case the inherited description must resolve to non-blank text before deployment. A row of pictures carries no other text. For a linked image the alt is the link's name, so name the destination or action, such as \"Download on the App Store\"; for an unlinked image, describe the picture.",
       "In Markdown the alt comes from the media manifest entry the image path names; a blank alt is refused.",
       "Each image keeps its own shape at the chosen height and is never cropped or framed; an image wider than the row shrinks to fit. Width and height are required so the row can size the image; media upload records them.",
       "Links open in the same tab, as card-grid and feature-grid links do.",
@@ -1077,6 +1129,7 @@ function referenceSchema(spec) {
         type: spec.nullable ? ["object", "null"] : "object",
         additionalProperties: false,
         properties: referenceProperties(spec.fields),
+        ...(spec.description ? { description: spec.description } : {}),
       };
     case "image":
       return {
@@ -1086,7 +1139,7 @@ function referenceSchema(spec) {
         description: `In Markdown, a media path recorded by media upload (such as "media/photo.webp")${
           spec.required ? "" : ", or null"
         }; pages push stores the image record. A .pm.json document carries that record: keep imageId, src, and urls keys so the server can rewrite delivery URLs.${
-          spec.altRequired ? " Alt text is required." : ""
+          spec.altRequired ? " Alt text is required unless descriptionMode is inherit; inherited text must resolve before deployment." : ""
         }${spec.dimensionsRequired ? " Width and height are required." : ""}`,
         additionalProperties: false,
         properties: referenceProperties(imageFieldsFor(spec)),
@@ -1278,7 +1331,7 @@ function validateValue(spec, value, path, errors) {
         fail(spec.required ? "an image object" : "an image object or null");
         return;
       }
-      validateFields(imageFieldsFor(spec), value, path, errors);
+      validateFields(imageFieldsFor(spec, value), value, path, errors);
       return;
     }
     default:
@@ -1341,6 +1394,44 @@ export function expandComponentAuthoringShorthand(componentType, source) {
   return { source: JSON.stringify({ provider: target.provider, videoId: target.videoId, ...rest }) };
 }
 
+/**
+ * The card grid's image rules that need two fields (TR01326): imageHeight and
+ * imageAlign only mean something with `contain`, and a contained image is
+ * sized from its stored width and height. The published renderer's readiness
+ * check applies the same rules at the same paths.
+ */
+function validateCardImageFit(parsed, dataPath, errors) {
+  const fit = parsed.imageFit;
+  // An invalid imageFit was already reported by `validateFields`.
+  if (fit !== undefined && fit !== "cover" && fit !== "contain") return;
+  if (fit !== "contain") {
+    for (const field of ["imageHeight", "imageAlign"]) {
+      if (parsed[field] === undefined) continue;
+      errors.push(contentError(
+        `${dataPath}/${field}`,
+        CODES.componentData,
+        `${field} applies only when imageFit is "contain"; remove ${field}, or set imageFit to "contain".`,
+      ));
+    }
+    return;
+  }
+  if (!Array.isArray(parsed.cards)) return;
+  for (const [index, card] of parsed.cards.entries()) {
+    if (!isPlainObject(card) || !isPlainObject(card.image)) continue;
+    for (const dimension of ["width", "height"]) {
+      const value = card.image[dimension];
+      // A wrong-type dimension was already reported by `validateFields`.
+      if (value !== undefined && typeof value !== "number") continue;
+      if (value !== undefined && value !== 0) continue;
+      errors.push(contentError(
+        `${dataPath}/cards/${index}/image/${dimension}`,
+        CODES.componentData,
+        `With imageFit "contain" a card image needs its ${dimension} in pixels; upload the image again with media upload, or set imageFit to "cover".`,
+      ));
+    }
+  }
+}
+
 /**
  * Validates a `componentBlock`'s `componentType` and `componentData` pair.
  *
@@ -1392,6 +1483,7 @@ export function validateComponentBlock(componentType, componentData, basePath) {
   const fields = isComponentType(componentType) ? COMPONENT_SHAPES[componentType] : undefined;
   if (!fields) return errors;
   validateFields(fields, parsed, dataPath, errors);
+  if (componentType === "card-grid") validateCardImageFit(parsed, dataPath, errors);
   if (componentType === "card-grid" && Array.isArray(parsed.cards)) {
     for (const [index, card] of parsed.cards.entries()) {
       if (
@@ -1507,9 +1599,10 @@ export function canonicalizeComponentData(componentType, data) {
   const fields = isComponentType(componentType) ? COMPONENT_SHAPES[componentType] : undefined;
   if (!fields) throw new TypeError("canonicalizeComponentData requires a known component type.");
   if (!isPlainObject(data)) throw new TypeError("canonicalizeComponentData requires an object.");
+  const authored = stripImageDescriptionHydration(data);
   const ordered = {};
   for (const key of Object.keys(fields)) {
-    if (Object.hasOwn(data, key)) ordered[key] = orderValue(fields[key], data[key]);
+    if (Object.hasOwn(authored, key)) ordered[key] = orderValue(fields[key], authored[key]);
   }
   for (const key of Object.keys(data)) {
     if (!Object.hasOwn(fields, key)) throw new TypeError("canonicalizeComponentData requires validated data.");

package/src/content/free-form-section-registry.json

@@ -1,5 +1,16 @@
 {
-  "version": 13,
+  "version": 15,
+
+  "imageDescription": {
+    "fields": {
+      "descriptionMode": { "kind": "mode", "storage": "persisted" },
+      "defaultDescription": { "kind": "text", "storage": "hydratedReadOnly" },
+      "descriptionRevision": { "kind": "revision", "storage": "hydratedReadOnly" }
+    },
+    "modes": ["inherit", "custom", "decorative"],
+    "maxDefaultDescriptionScalars": 1000,
+    "maxRevision": "9223372036854775807"
+  },
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -84,7 +95,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,
@@ -124,7 +138,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,
@@ -237,7 +254,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,
@@ -548,7 +568,13 @@
     "card-grid": {
       "label": "Card Grid",
       "measure": "wide",
-      "rootPlacement": "flow"
+      "rootPlacement": "flow",
+      "imageSpacings": {
+        "none": "0rem",
+        "small": "1em",
+        "medium": "2em",
+        "text": "var(--esp-size-small-to-normal, 1rem)"
+      }
     },
     "image-banner": {
       "label": "Image Banner",

package/src/content/free-form-sections.js

@@ -1,4 +1,5 @@
 import registry from "./free-form-section-registry.json" with { type: "json" };
+import { imageDescriptionIssues, pickImageDescriptionFields } from "./image-description-validation.js";
 
 import {
   CONTENT_ERROR_CODES as CODES,
@@ -45,6 +46,12 @@ function decorationDeliveryUrlIsSafe(value) {
   }
 }
 
+function validateImageDescription(image, path, label, report) {
+  for (const issue of imageDescriptionIssues(image)) {
+    report(`${path}/${issue.field}`, CODES.attrInvalid, `${label} ${issue.field} must ${issue.expected}.`);
+  }
+}
+
 function normalizeProcessedSectionImage(value, definition, path, label, report) {
   let valid = true;
   const reject = (errorPath, code, message) => {
@@ -170,6 +177,7 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
     reject(`${path}/alt`, CODES.attrInvalid, `${label} alt must be a string.`);
   }
 
+  validateImageDescription(value, path, label, reject);
   if (!valid) return undefined;
   return Object.freeze({
     imageId: value.imageId,
@@ -182,6 +190,7 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
     ...(Object.hasOwn(value, "width") ? { width: value.width } : {}),
     ...(Object.hasOwn(value, "height") ? { height: value.height } : {}),
     ...(Object.hasOwn(value, "alt") ? { alt: value.alt } : {}),
+    ...pickImageDescriptionFields(value),
   });
 }
 
@@ -457,6 +466,7 @@ export function normalizeFreeFormSectionDecoration(
     if (Object.hasOwn(image, "alt") && typeof image.alt !== "string") {
       report(`${imagePath}/alt`, CODES.attrInvalid, "Section decoration image alt must be a string.");
     }
+    validateImageDescription(image, imagePath, "Section decoration image", report);
   }
 
   for (const [name, definition] of Object.entries(fields)) {
@@ -500,6 +510,7 @@ export function normalizeFreeFormSectionDecoration(
     ...(Object.hasOwn(image, "width") ? { width: image.width } : {}),
     ...(Object.hasOwn(image, "height") ? { height: image.height } : {}),
     ...(Object.hasOwn(image, "alt") ? { alt: image.alt } : {}),
+    ...pickImageDescriptionFields(image),
   };
   const normalized = { image: Object.freeze(normalizedImage) };
   for (const [name, definition] of Object.entries(fields)) {

package/src/content/image-description-document.js

@@ -0,0 +1,108 @@
+// Generated from shared/image-description-document.ts by scripts/sync-field-validation.mjs. Do not edit.
+import { IMAGE_DESCRIPTION_HYDRATED_KEYS, resolveImageDescription } from "./image-description-validation.js";
+export function imageDescriptionImageId(image) {
+    return typeof image.imageId === "string"
+        ? image.imageId
+        : typeof image.id === "string" && "caption" in image
+            ? image.id
+            : undefined;
+}
+/** Component data may be serialized inside a structured document. Keep unchanged bytes intact. */
+export function visitImageDescriptionObjects(value, transform, seen = new WeakSet()) {
+    if (!value || typeof value !== "object" || seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const child of value)
+            visitImageDescriptionObjects(child, transform, seen);
+        return;
+    }
+    const record = value;
+    transform(record);
+    for (const [key, child] of Object.entries(record)) {
+        if (key === "componentData" && typeof child === "string") {
+            try {
+                const data = JSON.parse(child);
+                const before = JSON.stringify(data);
+                visitImageDescriptionObjects(data, transform, seen);
+                const after = JSON.stringify(data);
+                if (before !== after)
+                    record[key] = after;
+            }
+            catch { /* Existing content validation owns malformed component data. */ }
+        }
+        else
+            visitImageDescriptionObjects(child, transform, seen);
+    }
+}
+export function referencedImageDescriptionIds(value) {
+    const ids = new Set();
+    visitImageDescriptionObjects(value, image => {
+        const id = imageDescriptionImageId(image);
+        if (id)
+            ids.add(id);
+    });
+    return ids;
+}
+/** API delivery state does not belong in authored documents or workspace hashes. */
+export function stripImageDescriptionHydration(value) {
+    const copy = structuredClone(value);
+    visitImageDescriptionObjects(copy, image => {
+        for (const key of IMAGE_DESCRIPTION_HYDRATED_KEYS)
+            delete image[key];
+        if (image.descriptionMode === "inherit") {
+            delete image.alt;
+            delete image.altText;
+        }
+        const nested = image.image;
+        if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+            const bannerImage = nested;
+            if ((image.descriptionMode ?? bannerImage.descriptionMode) === "inherit") {
+                delete image.altText;
+                delete bannerImage.alt;
+                delete bannerImage.altText;
+            }
+        }
+    });
+    return copy;
+}
+const text = (value) => typeof value === "string" ? value : undefined;
+const placementMode = (mode, contextual) => mode === undefined || mode === null || mode === "" ? contextual.trim() ? "custom" : "inherit" : mode;
+export function hydrateImageDescriptions(value, source) {
+    const copy = structuredClone(value);
+    const metadata = (image, delivery) => {
+        image.defaultDescription = delivery.defaultDescription ?? null;
+        image.descriptionRevision = delivery.descriptionRevision;
+    };
+    visitImageDescriptionObjects(copy, image => {
+        const id = imageDescriptionImageId(image);
+        const delivery = id ? source(id) : undefined;
+        if (delivery) {
+            const album = "caption" in image && "urls" in image;
+            const field = "altText" in image || album ? "altText" : "alt";
+            const contextual = text(image[field])
+                ?? (album && image.descriptionMode == null ? text(image.caption) : undefined) ?? "";
+            const mode = placementMode(text(image.descriptionMode), contextual);
+            image.descriptionMode = mode;
+            image[field] = resolveImageDescription(mode, contextual, delivery.defaultDescription ?? "");
+            metadata(image, delivery);
+        }
+        const nested = image.image;
+        if (!("altText" in image || "descriptionMode" in image || "overlayText" in image)
+            || !nested || typeof nested !== "object" || Array.isArray(nested))
+            return;
+        const bannerImage = nested;
+        const bannerId = imageDescriptionImageId(bannerImage);
+        const bannerSource = bannerId ? source(bannerId) : undefined;
+        if (!bannerSource)
+            return;
+        const contextual = text(image.altText) ?? "";
+        const mode = placementMode(text(image.descriptionMode) ?? text(bannerImage.descriptionMode), contextual);
+        image.descriptionMode = mode;
+        image.altText = resolveImageDescription(mode, contextual, bannerSource.defaultDescription ?? "");
+        metadata(image, bannerSource);
+        bannerImage.descriptionMode = mode;
+        bannerImage.alt = image.altText;
+    });
+    return copy;
+}

package/src/content/image-description-validation.js

@@ -0,0 +1,70 @@
+// Generated from shared/image-description-validation.ts by scripts/sync-field-validation.mjs. Do not edit.
+import registry from "./free-form-section-registry.json" with { type: "json" };
+const definition = registry.imageDescription;
+export const IMAGE_DESCRIPTION_MODES = Object.freeze([...definition.modes]);
+export const IMAGE_DESCRIPTION_KEYS = Object.freeze(Object.keys(definition.fields));
+const fields = Object.entries(definition.fields);
+export const IMAGE_DESCRIPTION_PERSISTED_KEYS = Object.freeze(fields.filter(([, field]) => field.storage === "persisted").map(([key]) => key));
+export const IMAGE_DESCRIPTION_HYDRATED_KEYS = Object.freeze(fields.filter(([, field]) => field.storage === "hydratedReadOnly").map(([key]) => key));
+export function isImageDescriptionMode(value) {
+    return value === undefined || value === null || IMAGE_DESCRIPTION_MODES.includes(value);
+}
+export function isImageDefaultDescription(value) {
+    return value === undefined || value === null || typeof value === "string"
+        && !/[\uD800-\uDFFF]/u.test(value) && [...value].length <= definition.maxDefaultDescriptionScalars;
+}
+/** Decimal strings retain int64 precision across JSON and JavaScript. */
+export function normalizeImageDescriptionRevision(value) {
+    if (typeof value === "number")
+        return Number.isSafeInteger(value) && value >= 0 ? String(value) : undefined;
+    if (typeof value !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(value))
+        return undefined;
+    const maximum = definition.maxRevision;
+    return value.length < maximum.length || value.length === maximum.length && value <= maximum ? value : undefined;
+}
+export function isImageDescriptionRevision(value) {
+    return value === undefined || value === null || normalizeImageDescriptionRevision(value) !== undefined;
+}
+/** Editor controls repair unknown choices; delivery validation reports them instead. */
+export function imageDescriptionMode(mode, contextual) {
+    return typeof mode === "string" && IMAGE_DESCRIPTION_MODES.includes(mode)
+        ? mode
+        : contextual?.trim()
+            ? "custom"
+            : "inherit";
+}
+export function resolveImageDescription(mode, contextual, fallback) {
+    switch (mode) {
+        case "decorative":
+            return "";
+        case "inherit":
+            return fallback;
+        case "custom":
+            return contextual;
+        default:
+            return contextual.trim() ? contextual : fallback;
+    }
+}
+const validators = {
+    mode: { accepts: isImageDescriptionMode, expected: `be ${IMAGE_DESCRIPTION_MODES.join(", ")}, or null` },
+    text: {
+        accepts: isImageDefaultDescription,
+        expected: "be valid Unicode text within the registry's scalar limit, or null",
+    },
+    revision: {
+        accepts: isImageDescriptionRevision,
+        expected: "be a nonnegative safe integer or canonical int64 decimal string, or null",
+    },
+};
+export function imageDescriptionIssues(value) {
+    return fields.flatMap(([field, contract]) => {
+        const validator = validators[contract.kind];
+        return validator.accepts(value[field])
+            ? []
+            : [{ field, storage: contract.storage, expected: validator.expected }];
+    });
+}
+export function pickImageDescriptionFields(value, storage) {
+    return Object.fromEntries(fields.filter(([key, field]) => (!storage || field.storage === storage)
+        && Object.prototype.hasOwnProperty.call(value, key)).map(([key]) => [key, value[key]]));
+}

package/src/content/tiptap-prosemirror.ts

@@ -8,6 +8,7 @@
  */
 
 import freeFormSectionRegistry from "./free-form-section-registry.json" with { type: "json" };
+import { imageDescriptionIssues } from "./image-description-validation.js";
 import {
   explicitImageMaxHeight,
   mediaOverrideStyleParts,
@@ -820,11 +821,15 @@ function renderSection(
 }
 
 type NormalizedSectionImage = {
+  imageId: string;
   src: string;
   urls: Array<{ minWidth: number; url: string }>;
   width?: number;
   height?: number;
   alt?: string;
+  descriptionMode?: string | null;
+  defaultDescription?: string | null;
+  descriptionRevision?: number | string | null;
 };
 
 type NormalizedSectionBackground = {
@@ -912,12 +917,17 @@ function normalizeSectionImage(
     || (hasOwn(value, "height") && !isPositiveInteger(value.height))
     || (hasOwn(value, "alt") && typeof value.alt !== "string")
   ) return undefined;
+  if (imageDescriptionIssues(value).length > 0) return undefined;
   return {
+    imageId: value.imageId as string,
     src,
     urls: candidates,
     width: isPositiveInteger(value.width) ? value.width : undefined,
     height: isPositiveInteger(value.height) ? value.height : undefined,
     alt: typeof value.alt === "string" ? value.alt : undefined,
+    descriptionMode: value.descriptionMode as string | null | undefined,
+    defaultDescription: value.defaultDescription as string | null | undefined,
+    descriptionRevision: value.descriptionRevision as number | string | null | undefined,
   };
 }
 

package/src/content/validate-document.js

@@ -1,3 +1,4 @@
+import { IMAGE_DESCRIPTION_MODES } from "./image-description-validation.js";
 import { validateComponentBlock } from "./components.js";
 import {
   FREE_FORM_SECTION_REGISTRY,
@@ -180,6 +181,7 @@ const IMAGE_ATTRS = Object.freeze({
   ),
   urls: URLS_SPEC,
   alt: optionalString(),
+  descriptionMode: optionalEnum(IMAGE_DESCRIPTION_MODES),
   width: optionalPositiveInteger(),
   height: optionalPositiveInteger(),
   crop: CROP_SPEC,