@taprootio/site-authoring 0.30.0 → 0.32.0

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,8 @@
  */
 
 import freeFormSectionRegistry from "./free-form-section-registry.json" with { type: "json" };
+import { imageDescriptionIssues } from "./image-description-validation.js";
+import { isExternalLink, NEW_TAB_CUE_HTML, relWithNewTabTokens } from "./external-link.js";
 import {
   explicitImageMaxHeight,
   mediaOverrideStyleParts,
@@ -100,6 +102,12 @@ export interface RenderProseMirrorOptions {
   headingLevel?: (authored: number) => number;
   /** Claims the page's one LCP slot before rendering a section photo. */
   claimSectionBackgroundImage?: () => boolean;
+  /**
+   * The site's own hosts (TR01327). With it, external links open in a new tab
+   * unless the author chose otherwise; without it nothing is decided here, so
+   * previews and PDFs render as before.
+   */
+  siteHosts?: ReadonlySet<string>;
 }
 
 export function createEmptyProseMirrorDocument(): ProseMirrorDocument {
@@ -263,7 +271,7 @@ function renderNode(
         renderNodes(node.content ?? [], options, "nested"),
       );
     case "text":
-      return renderTextNode(node);
+      return renderTextNode(node, options);
     case "hardBreak":
       return "<br>";
     case "heading":
@@ -344,15 +352,15 @@ function renderIntegrationPlacement(node: ProseMirrorNode, options: RenderProseM
   }, selected.html);
 }
 
-function renderTextNode(node: ProseMirrorNode): string {
+function renderTextNode(node: ProseMirrorNode, options: RenderProseMirrorOptions): string {
   let rendered = escapeHtml(node.text ?? "");
   for (const mark of node.marks ?? []) {
-    rendered = wrapMark(rendered, mark);
+    rendered = wrapMark(rendered, mark, options);
   }
   return rendered;
 }
 
-function wrapMark(html: string, mark: ProseMirrorMark): string {
+function wrapMark(html: string, mark: ProseMirrorMark, options: RenderProseMirrorOptions): string {
   switch (mark.type) {
     case "bold":
       return `<strong>${html}</strong>`;
@@ -367,7 +375,7 @@ function wrapMark(html: string, mark: ProseMirrorMark): string {
     case "link": {
       const href = stringAttr(mark.attrs?.href);
       if (!href || !isSafeUrl(href)) return html;
-      return renderElement("a", { href, ...linkRelAttributes(mark.attrs) }, html);
+      return renderLink(href, mark.attrs, html, options);
     }
     default:
       return html;
@@ -409,7 +417,7 @@ type NormalizedTable = {
  * omit one malformed table rather than reinterpret arbitrary blocks as cells.
  */
 function renderTable(node: ProseMirrorNode, options: RenderProseMirrorOptions): string {
-  const table = normalizeTable(node);
+  const table = normalizeTable(node, options);
   if (!table) return "";
 
   const header = renderElement(
@@ -455,7 +463,7 @@ function renderTable(node: ProseMirrorNode, options: RenderProseMirrorOptions):
   );
 }
 
-function normalizeTable(node: ProseMirrorNode): NormalizedTable | undefined {
+function normalizeTable(node: ProseMirrorNode, options: RenderProseMirrorOptions): NormalizedTable | undefined {
   const definition = freeFormSectionRegistry.table;
   if (!hasOnlySerializedKeys(node, ["type", "attrs", "content"])) return undefined;
   const attrs = node.attrs;
@@ -495,7 +503,7 @@ function normalizeTable(node: ProseMirrorNode): NormalizedTable | undefined {
     return undefined;
   }
 
-  const headerCells = normalizeTableRow(headerRow, definition.nodeTypes.header, true);
+  const headerCells = normalizeTableRow(headerRow, definition.nodeTypes.header, true, options);
   if (!headerCells) return undefined;
   const normalizedDataRows: string[][] = [];
   for (const row of dataRows) {
@@ -507,7 +515,7 @@ function normalizeTable(node: ProseMirrorNode): NormalizedTable | undefined {
       || !Array.isArray(row.content)
       || row.content.length !== columnCount
     ) return undefined;
-    const normalized = normalizeTableRow(row, definition.nodeTypes.cell, false);
+    const normalized = normalizeTableRow(row, definition.nodeTypes.cell, false, options);
     if (!normalized) return undefined;
     normalizedDataRows.push(normalized);
   }
@@ -523,6 +531,7 @@ function normalizeTableRow(
   row: ProseMirrorNode,
   expectedCellType: string,
   header: boolean,
+  options: RenderProseMirrorOptions,
 ): string[] | undefined {
   if (!Array.isArray(row.content)) return undefined;
   const cells: string[] = [];
@@ -533,7 +542,7 @@ function normalizeTableRow(
       || cell.type !== expectedCellType
       || !hasNoAttrs(cell)
     ) return undefined;
-    const normalized = normalizeTableCell(cell);
+    const normalized = normalizeTableCell(cell, options);
     if (!normalized) return undefined;
     if (header && freeFormSectionRegistry.table.cells.headerNonWhitespace && normalized.text.trim() === "") {
       return undefined;
@@ -543,7 +552,10 @@ function normalizeTableRow(
   return cells;
 }
 
-function normalizeTableCell(cell: ProseMirrorNode): { html: string; text: string } | undefined {
+function normalizeTableCell(
+  cell: ProseMirrorNode,
+  options: RenderProseMirrorOptions,
+): { html: string; text: string } | undefined {
   const paragraphs = cell.content;
   const paragraph = paragraphs?.[0];
   if (
@@ -573,7 +585,7 @@ function normalizeTableCell(cell: ProseMirrorNode): { html: string; text: string
         || inlineNode.text === ""
       ) return undefined;
       text += inlineNode.text;
-      html.push(renderTextNode(inlineNode));
+      html.push(renderTextNode(inlineNode, options));
     } else if (inlineNode.type === "hardBreak") {
       if (
         !hasOnlySerializedKeys(inlineNode, ["type", "attrs", "marks"])
@@ -658,7 +670,7 @@ function renderInlineFacts(
   if (!facts) return "";
   const items = facts.map((fact) => {
     const value = fact.url
-      ? renderElement("a", { href: fact.url }, escapeHtml(fact.value))
+      ? renderLink(fact.url, {}, escapeHtml(fact.value), options)
       : escapeHtml(fact.value);
     const label = fact.label === undefined
       ? ""
@@ -820,11 +832,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 +928,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,
   };
 }
 
@@ -1020,7 +1041,7 @@ type NormalizedSectionDecoration = {
   anchor: string;
   inlineOffsetPercent: number;
   blockOffsetPercent: number;
-  inlineSizePercent: number;
+  size: string;
   opacity: number;
   tintToken: string;
 };
@@ -1032,7 +1053,7 @@ function normalizedSectionDecorationStyle(value: unknown): string[] | undefined
     `--esp-section-decoration-image: url("${escapeCssString(decoration.imageUrl)}")`,
     `--esp-section-decoration-color: var(${decoration.tintToken})`,
     `--esp-section-decoration-position: ${sectionDecorationPosition(decoration)}`,
-    `--esp-section-decoration-size: ${decoration.inlineSizePercent}% auto`,
+    `--esp-section-decoration-size: ${decoration.size}`,
     `--esp-section-decoration-opacity: ${decoration.opacity}`,
   ];
 }
@@ -1054,6 +1075,10 @@ function normalizeSectionDecoration(value: unknown): NormalizedSectionDecoration
   const anchor = value.anchor ?? fields.anchor.default;
   const inlineOffsetPercent = value.inlineOffsetPercent ?? fields.inlineOffsetPercent.default;
   const blockOffsetPercent = value.blockOffsetPercent ?? fields.blockOffsetPercent.default;
+  // TR01329: width and height sizes are exclusive. Read the raw keys, because
+  // the width default is filled in below.
+  if (value.inlineSizePercent !== undefined && value.blockSizePercent !== undefined) return undefined;
+  const blockSizePercent = value.blockSizePercent;
   const inlineSizePercent = value.inlineSizePercent ?? fields.inlineSizePercent.default;
   const opacity = value.opacity ?? fields.opacity.default;
   const tint = value.tint ?? fields.tint.default;
@@ -1064,7 +1089,12 @@ function normalizeSectionDecoration(value: unknown): NormalizedSectionDecoration
   if (!isBoundedNumber(blockOffsetPercent, fields.blockOffsetPercent.minimum, fields.blockOffsetPercent.maximum)) {
     return undefined;
   }
-  if (
+  if (blockSizePercent !== undefined) {
+    if (
+      !isBoundedNumber(blockSizePercent, fields.blockSizePercent.minimum, fields.blockSizePercent.maximum)
+      || !Number.isInteger(blockSizePercent)
+    ) return undefined;
+  } else if (
     !isBoundedNumber(inlineSizePercent, fields.inlineSizePercent.minimum, fields.inlineSizePercent.maximum)
     || !Number.isInteger(inlineSizePercent)
   ) return undefined;
@@ -1078,7 +1108,7 @@ function normalizeSectionDecoration(value: unknown): NormalizedSectionDecoration
     anchor,
     inlineOffsetPercent,
     blockOffsetPercent,
-    inlineSizePercent,
+    size: blockSizePercent !== undefined ? `auto ${blockSizePercent}%` : `${inlineSizePercent}% auto`,
     opacity,
     tintToken,
   };
@@ -1406,7 +1436,11 @@ export const LINK_REL_TOKENS = [
   "privacy-policy",
   "terms-of-service",
 ] as const;
-/** The targets a link may carry; only `_blank` changes what renders. */
+/**
+ * The targets a link may carry. `_blank` opens a new tab and `_self` keeps the
+ * tab; with a site host set, any other value leaves the choice to the external
+ * link rule (TR01327).
+ */
 export const LINK_TARGETS = ["_blank", "_self"] as const;
 /**
  * The editor stored this rel, with `target="_blank"`, on every link before
@@ -1435,18 +1469,42 @@ export function chosenLinkRelTokens(rel: unknown): string[] | undefined {
 /**
  * The `rel` and `target` a link publishes with: the author's allowed tokens in
  * their order, and noopener and noreferrer whenever it opens a new tab.
- * Anything else stored is ignored.
+ * `_blank` opens a new tab and `_self` keeps the tab. Any other target, or a
+ * mark with the old editor rel (whose target was never a choice), follows the
+ * external link rule when a host set is supplied, and otherwise stays in the
+ * tab. Anything else stored is ignored.
  */
-export function linkRelAttributes(attrs: Record<string, unknown> | undefined): { rel?: string; target?: string } {
+export function linkRelAttributes(
+  attrs: Record<string, unknown> | undefined,
+  href?: string,
+  siteHosts?: ReadonlySet<string>,
+): { rel?: string; target?: string } {
   const stored = chosenLinkRelTokens(attrs?.rel);
-  if (!stored) return {};
-  const newTab = stringAttr(attrs?.target)?.trim().toLowerCase() === "_blank";
+  const target = stringAttr(attrs?.target)?.trim().toLowerCase();
+  const byRule = () => siteHosts !== undefined && isExternalLink(href, siteHosts);
+  const newTab = stored && (target === "_blank" || target === "_self")
+    ? target === "_blank"
+    : byRule();
   const allowed: readonly string[] = LINK_REL_TOKENS;
-  const rel = new Set([
-    ...stored.filter((token) => allowed.includes(token)),
-    ...(newTab ? ["noopener", "noreferrer"] : []),
-  ]);
-  return { ...(rel.size ? { rel: [...rel].join(" ") } : {}), ...(newTab ? { target: "_blank" } : {}) };
+  const kept = (stored ?? []).filter((token) => allowed.includes(token));
+  const rel = newTab ? relWithNewTabTokens(kept.join(" ")) : [...new Set(kept)].join(" ");
+  return { ...(rel ? { rel } : {}), ...(newTab ? { target: "_blank" } : {}) };
+}
+
+/**
+ * An anchor with the attributes `linkRelAttributes` chooses. Only a publish
+ * passes a host set, and only then does a new-tab link carry its hidden cue,
+ * because the editor preview and legal PDFs have no rule to hide it (TR01327).
+ */
+function renderLink(
+  href: string,
+  attrs: Record<string, unknown> | undefined,
+  html: string,
+  options: RenderProseMirrorOptions,
+): string {
+  const linkAttributes = linkRelAttributes(attrs, href, options.siteHosts);
+  const cue = options.siteHosts !== undefined && linkAttributes.target === "_blank" ? NEW_TAB_CUE_HTML : "";
+  return renderElement("a", { href, ...linkAttributes }, `${html}${cue}`);
 }
 
 function isSafeUrl(url: string): boolean {

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,

package/src/image-description-contract.js

@@ -0,0 +1,84 @@
+import { normalizeImageDescriptionRevision } from "./content/image-description-validation.js";
+import { LIMITS } from "./constants.js";
+import { hasControlCharacter, SiteAuthoringError } from "./errors.js";
+
+export const IMAGE_LIST_DEFAULT_PAGE_SIZE = 25;
+export const IMAGE_LIST_MAXIMUM_PAGE_SIZE = 100;
+const IMAGE_ID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/u;
+
+export function isImageId(value) {
+  return typeof value === "string" && IMAGE_ID.test(value) && value !== "00000000-0000-0000-0000-000000000000";
+}
+
+export function requireImageId(value) {
+  if (!isImageId(value)) {
+    throw new SiteAuthoringError("media.image_id_invalid", "Name exactly one canonical lowercase image UUID.", {
+      field: "imageId", exitCode: 2,
+    });
+  }
+  return value;
+}
+
+export { normalizeImageDescriptionRevision as imageDescriptionRevision } from "./content/image-description-validation.js";
+
+export function imageListOptions(invocation = {}) {
+  const pageSize = invocation.pageSize === undefined ? IMAGE_LIST_DEFAULT_PAGE_SIZE : Number(invocation.pageSize);
+  if ((invocation.pageSize !== undefined && !["number", "string"].includes(typeof invocation.pageSize))
+    || !Number.isInteger(pageSize) || pageSize < 1 || pageSize > IMAGE_LIST_MAXIMUM_PAGE_SIZE
+    || (typeof invocation.pageSize === "string" && !/^[1-9][0-9]*$/u.test(invocation.pageSize))) {
+    throw new SiteAuthoringError("media.image_page_size_invalid", "--page-size must be a whole number from 1 to 100.", {
+      field: "pageSize", exitCode: 2,
+    });
+  }
+  const pageToken = invocation.pageToken ?? "";
+  if (typeof pageToken !== "string" || !pageToken.isWellFormed()
+    || Buffer.byteLength(pageToken, "utf8") > LIMITS.configPathBytes) {
+    throw new SiteAuthoringError("media.image_page_token_invalid", "--page-token must be the cursor from the previous result.", {
+      field: "pageToken", exitCode: 2,
+    });
+  }
+  return { pageSize, pageToken, missingDescription: invocation.missingDescription === true };
+}
+
+export function imageDescriptionOptions(invocation = {}) {
+  const hasDescription = invocation.imageDescription !== undefined;
+  const clear = invocation.clearDescription === true;
+  if (hasDescription === clear) {
+    throw new SiteAuthoringError("media.image_description_choice", "Supply exactly one of --description or --clear.", {
+      field: "description", exitCode: 2,
+    });
+  }
+  const description = clear ? "" : invocation.imageDescription;
+  if (typeof description !== "string" || !description.isWellFormed()
+    || Buffer.byteLength(description, "utf8") > LIMITS.configBytes) {
+    throw new SiteAuthoringError("media.image_description_invalid", "--description needs bounded, valid Unicode text.", {
+      field: "description", exitCode: 2,
+    });
+  }
+  const expectedRevision = normalizeImageDescriptionRevision(invocation.expectedRevision);
+  if (expectedRevision === undefined) {
+    throw new SiteAuthoringError("media.image_revision_required",
+      "Supply --expected-revision from the image's list/get result, as a nonnegative int64 decimal integer.", {
+        field: "expectedRevision", exitCode: 2,
+      });
+  }
+  const onlyIfMissing = invocation.onlyIfMissing === true;
+  if (onlyIfMissing && description.trim() === "") {
+    throw new SiteAuthoringError("media.image_condition_clear", "--if-missing cannot clear a description.", {
+      field: "onlyIfMissing", exitCode: 2,
+    });
+  }
+  return { defaultDescription: description, expectedRevision, onlyIfMissing };
+}
+
+export function safeImagePreviewUrl(value) {
+  if (typeof value !== "string" || !value.isWellFormed() || value.length > LIMITS.configPathBytes
+    || hasControlCharacter(value) || /[\s\\]/u.test(value)) return "";
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.username === "" && url.password === ""
+        && url.search === "" && url.hash === "" ? url.href : "";
+  } catch {
+    return "";
+  }
+}

package/src/navigation-readiness.js

@@ -0,0 +1,47 @@
+const READY = "NAVIGATION_PUBLISHING_READINESS_STATE_READY";
+const BLOCKED = "NAVIGATION_PUBLISHING_READINESS_STATE_BLOCKED";
+const UNKNOWN = "NAVIGATION_PUBLISHING_READINESS_STATE_UNKNOWN";
+const REASON_PREFIX = "NAVIGATION_PUBLISHING_READINESS_BLOCKER_REASON_";
+const MESSAGES = {
+  PAGE_NOT_INCLUDED: "Include this approved page in the release.",
+  PAGE_NOT_APPROVED: "Approve this page and include it in the release.",
+  FOLDER_NEEDS_RELEASED_CONTENT: "Publish a qualifying page under this path, or approve and include one in this release.",
+  TARGET_UNAVAILABLE: "Remove or replace this unavailable navigation target.",
+};
+
+export function normalizeNavigationReadiness(value) {
+  return {
+    state: [READY, BLOCKED].includes(value?.state) ? value.state : UNKNOWN,
+    blockers: (Array.isArray(value?.blockers) ? value.blockers : []).map((blocker) => ({
+      resourceId: typeof blocker?.resourceId === "string" ? blocker.resourceId : "",
+      pageId: typeof blocker?.pageId === "string" ? blocker.pageId : "",
+      title: typeof blocker?.title === "string" ? blocker.title : "",
+      path: typeof blocker?.path === "string" ? blocker.path : "",
+      reason: typeof blocker?.reason === "string" ? blocker.reason : "",
+    })),
+  };
+}
+
+export function isNavigationReady(navigation) {
+  return navigation.state === READY;
+}
+
+export function describeNavigationReadiness(navigation) {
+  if (isNavigationReady(navigation)) return "Navigation is ready.";
+  if (navigation.state !== BLOCKED) return "Navigation could not be checked. Try the readiness check again.";
+  const details = navigation.blockers.slice(0, 20).map((blocker) => {
+    const target = blocker.title || "Unavailable page";
+    const path = blocker.pageId ? ` (/${blocker.path.replace(/^\/+/, "")})` : "";
+    const message = MESSAGES[blocker.reason.replace(REASON_PREFIX, "")] || MESSAGES.TARGET_UNAVAILABLE;
+    return `${target}${path}: ${message}`;
+  });
+  return details.length ? `Navigation is blocked. ${details.join(" ")}` : "Navigation cannot be published with this set.";
+}
+
+export function reportNavigationReadiness(navigation) {
+  return {
+    state: navigation.state,
+    blockers: navigation.blockers.slice(0, 20),
+    ...(navigation.blockers.length > 20 ? { blockersTruncated: true } : {}),
+  };
+}

package/src/output.js

@@ -159,6 +159,14 @@ export async function writeGithubActionsOutput(outputPath, result) {
   const safeResult = structuredClone(result);
   if (safeResult.verb === "preview page") delete safeResult.url;
   if (safeResult.stagingPreview) delete safeResult.stagingPreview.url;
+  if (["media images list", "media images get", "media images describe"].includes(safeResult.verb)) {
+    const images = safeResult.image ? [safeResult.image] : safeResult.images?.items ?? [];
+    for (const image of images) {
+      delete image.previewUrl;
+      delete image.responsivePreviewUrls;
+    }
+  }
+  for (const image of safeResult.siteHealth?.imageFindings ?? []) delete image.previewUrl;
   const json = requireBoundedJson(safeResult);
   const delimiter = githubDelimiter(json);
   const lines = [