@taprootio/site-authoring 0.30.0 → 0.31.0

package/README.md

@@ -157,12 +157,20 @@ banner title or hero title is the page's `<h1>`; `seo.h1_demoted` when a `#` hea
 publishes as an `<h2>` because the banner's overlay text, a hero title or an earlier
 `#` heading already is the `<h1>` (`detail` says which); `seo.h1_multiple` for a hero
 title after the `<h1>`; `seo.heading_renumbered` and `seo.heading_before_title` for
-headings published at another level; and `a11y.image_alt_missing` and
-`a11y.link_text_empty`. Any page gets `seo.title_long` and `seo.description_missing`.
-`siteChecks.checkedInEditor` names the rules only the page editor evaluates (a cover, a description field, or a
-description's length, which `descriptionWarnings` reports here). `siteChecks.checkedBySite` names the rules that need the site's own
-records, such as placed images and forms: `status` reports those under
-`siteHealth`; `siteChecks.checkedAtDeploy` names the ones only a deploy applies. A redirect source the site would refuse also names its rule in
+headings published at another level; and `a11y.link_text_empty`. Image-default
+completeness (`a11y.image_default_missing`) comes from the stored deployment
+report, using frozen image defaults. Placement alt strings and decorative choices
+do not fill a missing reusable default. Known author-entered metadata receives missing, short and
+long title/description advice, plus `seo.description_matches_title` when the description
+repeats its title. The writing guidance is 15–70 characters for titles and 50–160 for
+descriptions, counted as Unicode characters after outer trimming. These suggestions
+never require padding or truncation and never refuse a save, push or deploy.
+Generated custom values are checked locally. Generated defaults, home-page settings
+and unknown fields defer to deployment in `siteChecks.deferredToDeployment`.
+`siteChecks.checkedInEditor` names rules only the page editor evaluates, such as a selected cover. `siteChecks.checkedBySite` names the rules that need the site's own
+records, such as referenced images and forms: `status` reads the stored deployment
+report under `siteHealth` without scanning current drafts or compiling a new report;
+`siteChecks.checkedAtDeploy` names the ones only a deploy applies. A redirect source the site would refuse also names its rule in
 `error.problems[].rule`.
 
 `taproot-site validate <fixture-directory>` checks a complete offline fixture
@@ -585,6 +593,49 @@ not atomic together: a failure reports in `error.completedWrites` which steps
 completed, which failed, and which did not run, and the next `plan` shows
 finished steps as nothing to do. Redirects, forms, approval, and deployment
 stay separate commands.
+Image defaults belong to the reusable image. Use the selected site's ordinary
+library, without rewriting page bodies:
+
+```bash
+taproot-site media images list --missing-description --page-size 25 --json
+taproot-site media images get <image-id> --json
+taproot-site media images describe <image-id> --description 'A red bird on a branch.' --expected-revision 0 --if-missing --json
+taproot-site media images describe <image-id> --clear --expected-revision 1 --json
+```
+
+List returns one page in `images.items`, `images.totalImages` for the filtered
+library, and `images.nextPageToken`; pass a nonempty cursor unchanged with
+`--page-token` to continue. `--page-size` accepts 1–100. Filtering happens on the
+server before pagination, and reads make no per-image requests. If a page's
+text and previews exceed the output bound, repeat the same cursor with a smaller
+page size. No rows are silently omitted. Zero matches is a successful empty list.
+
+Each image exposes `imageId`, `uploadedName`, nullable `defaultDescription`,
+`descriptionRevision`, dimensions, processing state, `previewUrl` and
+`responsivePreviewUrls`. Revisions are decimal strings so JavaScript cannot
+round an int64 value; pass them unchanged as `--expected-revision`. Preview URLs
+are validated HTTPS addresses for inspection, may expire, and stay out of
+`GITHUB_OUTPUT`. No image metadata is written to a workspace file by these verbs.
+
+Describe requires exactly one of `--description` and `--clear`. The server trims
+outer whitespace, turns empty/whitespace input into null, and rejects text longer
+than 1000 Unicode scalar values without truncation. Unicode and newlines are
+preserved in JSON. `--if-missing` is checked atomically at the write and cannot
+clear a default. A stale revision reports `media.image_description_conflict`; an
+existing default under the condition reports `media.image_description_exists`.
+Both exit 1 and leave the stored text alone. Read the current image, reconcile,
+and use its revision for a new intentional save; mutations never retry
+automatically. Invalid input exits 2. Permission and credential refusals keep the
+ordinary API error codes. Every verb requires `site.media.manage`, and images
+from another site, profile/account scope, or an installation remain inaccessible.
+
+Defaults apply to inherited usages after the next selected deployment. Current
+public output and in-flight releases retain their frozen text; custom overrides,
+decorative choices and unrelated album captions remain independent. Missing
+means the image's default is absent, even when a placement has contextual text.
+These commands populate no production content automatically. `help media` has
+the full read/write contract.
+
 `media upload [path...]` uploads raster files and records each one in
 `.taproot-site-media.json`; Markdown then names an image by its path (such as
 `media/photo.webp`) everywhere an image goes, from body images to component and
@@ -704,12 +755,17 @@ It stages; nothing reaches an audience until `deploy --staging` publishes the
 candidate and `deploy --production` promotes that completed staging
 deployment. `status` reports the platform authoring switch, the CLI release,
 deployments, readiness, image processing, and site health under Content
-permission. `siteHealth` lists the site checks' findings over the latest editable
-body of each page: a rule id, a severity (`error` or `warning`), the page, and
-the value found. It reports `covered: true`, `errors`, `warnings`, `pages`, and
-`findings`; an empty list means no check found anything. Output is bounded to 100
-findings, with an explicit `findingsTruncated` flag. A denied, malformed, or
-failed read fails `status` instead of implying a clean site.
+permission. `siteHealth` reads the last successful production deployment's stored
+report. It includes the deployment and output identities, input hash, checked time,
+rule version, coverage, assessed page count and status. Unpublished edits are
+outside that report. Page findings identify the rule, severity, page and value;
+image findings group each missing default description with its affected pages.
+Known reports include `covered: true`, `errors`, `warnings`, `pages` and `findings`.
+Only a complete report with zero findings establishes that the assessed candidate
+has no warnings. Missing, unsupported and incomplete assessments are explicit.
+Output is bounded to 100 page findings, with an explicit `findingsTruncated` flag.
+Preview URLs appear only in normal output and are omitted from GitHub output.
+A denied, malformed or failed read fails `status` instead of implying a clean site.
 
 ## Output contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "6.7.0",
+    "@taprootio/espalier": "6.8.0",
     "mediabunny": "1.61.1"
   },
   "scripts": {

package/src/api.js

@@ -1,4 +1,6 @@
+import { normalizeNavigationReadiness } from "./navigation-readiness.js";
 import { normalizeLatestCliVersion } from "./cli-release.js";
+import { imageDescriptionRevision, isImageId, safeImagePreviewUrl } from "./image-description-contract.js";
 import {
   BANDWIDTH_ALLOWANCE_REFUSAL_REASON,
   CANONICAL_TIMESTAMP,
@@ -1153,6 +1155,65 @@ export async function listSiteImages(client, siteId, requestOptions = {}, { imag
   return { images, summary, truncated: true };
 }
 
+function normalizeDescriptionImage(value, siteId, expectedImageId) {
+  const code = "api.image_description_contract";
+  const record = requireObject(value, code, "image library entry");
+  const wire = requireObject(record.image, code, "image");
+  const image = normalizeImage(wire);
+  if (!isImageId(image.imageId) || wire.siteId !== siteId
+    || wire.ownershipScope !== IMAGE_OWNERSHIP_SCOPE_SITE
+    || (expectedImageId !== undefined && image.imageId !== expectedImageId)) {
+    throw new SiteAuthoringError(code, "Taproot returned an image outside the requested site library.");
+  }
+  const descriptionRevision = imageDescriptionRevision(wire.descriptionRevision ?? "0");
+  const defaultDescription = wire.defaultDescription === undefined || wire.defaultDescription === null || wire.defaultDescription === ""
+    ? null : wire.defaultDescription;
+  if (descriptionRevision === undefined || (defaultDescription !== null
+    && (typeof defaultDescription !== "string" || !defaultDescription.isWellFormed()))) {
+    throw new SiteAuthoringError(code, "Taproot returned invalid image description metadata.");
+  }
+  return {
+    imageId: image.imageId,
+    uploadedName: image.uploadedName,
+    defaultDescription,
+    descriptionRevision,
+    width: image.width,
+    height: image.height,
+    processingState: image.processingState,
+    previewUrl: safeImagePreviewUrl(image.url),
+    responsivePreviewUrls: image.responsiveUrls.slice(0, 8)
+      .map((url) => ({ minWidth: url.minWidth, url: safeImagePreviewUrl(url.url) }))
+      .filter((url) => url.url !== ""),
+  };
+}
+
+/** One bounded page, filtered by the server before its cursor is applied. */
+export async function listSiteImageDescriptions(client, siteId, { pageSize, pageToken, missingDescription }) {
+  const response = requireObject(await client.request(sitePath(siteId, `images${query([
+    ["pageSize", pageSize], ["pageToken", pageToken], ["missingDescription", missingDescription || undefined],
+  ])}`)), "api.image_description_contract", "site images");
+  if (response.images !== undefined && !Array.isArray(response.images))
+    throw new SiteAuthoringError("api.image_description_contract", "Taproot returned an invalid image list.");
+  if (response.nextPageToken !== undefined && typeof response.nextPageToken !== "string")
+    throw new SiteAuthoringError("api.image_description_contract", "Taproot returned an invalid image cursor.");
+  return {
+    items: (response.images ?? []).map((entry) => normalizeDescriptionImage(entry, siteId)),
+    nextPageToken: response.nextPageToken ?? "",
+    totalImages: safeCount(response.totalImages),
+  };
+}
+
+export async function getSiteImageDescription(client, siteId, imageId) {
+  return normalizeDescriptionImage(
+    await client.request(sitePath(siteId, `images/${encodeURIComponent(imageId)}`)), siteId, imageId);
+}
+
+export async function updateSiteImageDescription(client, siteId, imageId, body) {
+  return normalizeDescriptionImage(await client.request(sitePath(siteId, `images/${encodeURIComponent(imageId)}/description`), {
+    method: "PATCH", body,
+  }), siteId, imageId);
+}
+
 /** The site checks' findings over the latest editable page bodies, authorized by Content. */
 export async function getSiteHealth(client, siteId) {
   const code = "api.site_health_contract";
@@ -1191,10 +1252,55 @@ export async function getSiteHealth(client, siteId) {
       detail: text(finding.detail),
     };
   });
+  const statuses = new Set(["not_checked", "complete", "incomplete", "unsupported"]);
+  const status = statuses.has(response.status) ? response.status : "unknown";
+  const optionalId = (value, field) => value === undefined || value === "" ? undefined : requireCanonicalUuid(value, code, field);
+  const deploymentId = optionalId(response.deploymentId, "deploymentId");
+  const outputReleaseId = optionalId(response.outputReleaseId, "outputReleaseId");
+  const claimsAssessment = status === "complete" || status === "incomplete" && Boolean(deploymentId || outputReleaseId);
+  if (claimsAssessment && (!deploymentId || !outputReleaseId || !CANONICAL_TIMESTAMP.test(response.checkedAt ?? "")
+    || typeof response.inputHash !== "string" || !/^[0-9a-f]{64}$/u.test(response.inputHash)
+    || typeof response.ruleVersion !== "string" || response.ruleVersion === ""
+    || !Array.isArray(response.coverage) || response.coverage.length === 0)) {
+    throw new SiteAuthoringError(code, "Taproot returned an assessed report without its immutable deployment identity.");
+  }
+  if (response.coverage !== undefined && (!Array.isArray(response.coverage) || response.coverage.some(area => typeof area !== "string"))) {
+    throw new SiteAuthoringError(code, "Taproot returned invalid health coverage.", { field: "coverage" });
+  }
+  if (response.images !== undefined && !Array.isArray(response.images)) {
+    throw new SiteAuthoringError(code, "Taproot returned invalid image findings.", { field: "images" });
+  }
+  const images = (response.images ?? []).map(value => {
+    const image = requireObject(value, code, "image finding");
+    if (!Array.isArray(image.affectedPages) || image.affectedPages.length === 0) {
+      throw new SiteAuthoringError(code, "Taproot returned an image finding without affected pages.");
+    }
+    return {
+      imageId: requireCanonicalUuid(image.imageId, code, "imageId"), name: text(image.name),
+      previewUrl: safeImagePreviewUrl(image.previewUrl),
+      affectedPages: image.affectedPages.map(page => ({
+        pageId: requireCanonicalUuid(page?.pageId, code, "affectedPages.pageId"),
+        title: text(page?.title), path: text(page?.path),
+      })),
+    };
+  });
+  const errors = count(response.errorCount, "errorCount");
+  const warnings = count(response.warningCount, "warningCount");
+  const keptErrors = findings.filter(finding => finding.severity === "error").length;
+  const keptWarnings = findings.length - keptErrors + images.length;
+  if (claimsAssessment && (errors < keptErrors || warnings < keptWarnings ||
+      response.truncated !== true && (errors !== keptErrors || warnings !== keptWarnings))) {
+    throw new SiteAuthoringError(code, "Taproot returned health totals that disagree with the stored findings.");
+  }
   return {
-    findings,
-    errorCount: count(response.errorCount, "errorCount"),
-    warningCount: count(response.warningCount, "warningCount"),
+    findings, images, status, assessmentKnown: status !== "unknown",
+    ...(deploymentId ? { deploymentId } : {}), ...(outputReleaseId ? { outputReleaseId } : {}),
+    inputHash: text(response.inputHash), checkedAt: text(response.checkedAt), ruleVersion: text(response.ruleVersion),
+    coverage: response.coverage ?? [], assessedPageCount: count(response.assessedPageCount, "assessedPageCount"),
+    environment: response.environment === "staging" ? "staging" : "production",
+    stagedDeploymentId: optionalId(response.stagedDeploymentId, "stagedDeploymentId"),
+    errorCount: errors,
+    warningCount: warnings,
     pageCount: count(response.pageCount, "pageCount"),
     truncated: response.truncated === true,
   };
@@ -1257,6 +1363,7 @@ export async function getPublishingReadiness(client, siteId, selection = {}) {
   }));
   return {
     state: typeof response.state === "string" ? response.state : "PAGE_PUBLISHING_READINESS_STATE_UNKNOWN",
+    navigationReadiness: normalizeNavigationReadiness(response.navigationReadiness),
     approvedPageCount: safeCount(response.approvedPageCount),
     selectedPageCount: safeCount(response.selectedPageCount),
     blockedPageCount: safeCount(response.blockedPageCount),

package/src/changelog.json

@@ -1,5 +1,24 @@
 {
   "entries": [
+    {
+      "version": "0.31.0",
+      "note": "Image defaults can be listed, read and changed safely through media images; metadata advice uses consistent title and description guidance.",
+      "behavior": [
+        "New verbs: media images list [--missing-description] [--page-size <1-100>] [--page-token <cursor>], media images get <image-id>, and media images describe <image-id> --description <text> (or --clear) --expected-revision <n> [--if-missing]. List returns one bounded page and its nextPageToken; the server filters missing defaults before pagination, without scanning page placements or fetching every image separately.",
+        "Get/list/describe report stable imageId, uploadedName, nullable defaultDescription, descriptionRevision as an exact decimal string, dimensions, processing state and validated preview URLs. Preview URLs are for inspection and may expire; they are omitted from GitHub Actions output and never written into a description or workspace manifest.",
+        "Description writes require the selected site's media permission and the expected revision from list/get. --if-missing is checked atomically by the server and cannot be combined with --clear or blank text. A stale revision or existing default is a refusal, with no automatic overwrite or mutation retry. The server trims outer whitespace, clears blank descriptions to null, and rejects more than 1000 Unicode scalar values without truncation. Existing published output keeps its frozen text until deployment; custom/decorative placement choices stay independent.",
+        "Local metadata advice checks known author-entered values consistently: a nonempty title outside 15–70 Unicode scalar values, a description outside 50–160, missing text, or a description matching the title after whitespace and case normalization. Warnings do not block saves. Fallback-dependent metadata remains deferred to the deployment evaluator.",
+        "The coordinated release replaces local a11y.image_alt_missing placement advice with a11y.image_default_missing in the stored deployment report. Completeness uses only the frozen image-owned default: contextual alt text, album captions and decorative choices do not waive a missing reusable description. status reads the report and never scans current drafts or triggers compilation.",
+        "Image Row and Product Grid image records now follow the shared description contract: descriptionMode selects inherit, custom or decorative, while defaultDescription and descriptionRevision are read-only hydrated metadata and are omitted from authored workspace sources. An Image Row image with descriptionMode inherit may omit alt locally, but its description must resolve to non-blank alt text before deployment; custom and legacy Image Row alt text remains required. See help component image-row and help component product-grid.",
+        "The help reference version is 50. Taproot accepts only this latest CLI after the API deploy; upgrade with npm install -g @taprootio/site-authoring@latest."
+      ],
+      "help": [
+        "media",
+        "pages",
+        "page",
+        "component"
+      ]
+    },
     {
       "version": "0.30.0",
       "note": "A card-grid can show each card's image whole at a set height, aligned and unframed, with chosen space on any side of the image, so a logo no longer needs a wide padded file.",

package/src/cli.js

@@ -39,6 +39,9 @@ import {
   VERB_MARKETING_PULL,
   VERB_MARKETING_PUSH,
   VERB_MEDIA_UPLOAD,
+  VERB_MEDIA_IMAGES_LIST,
+  VERB_MEDIA_IMAGES_GET,
+  VERB_MEDIA_IMAGES_DESCRIBE,
   VERB_NAV_PUSH,
   VERB_PAGES_DELETE,
   VERB_PAGES_META_SET,
@@ -94,6 +97,7 @@ import { FONT_CATEGORIES, getFontCatalogReference } from "./font-catalog.js";
 import { LINK_SOURCES } from "./marketing-contract.js";
 import { assertCliCurrent } from "./session.js";
 import { ApiError } from "./transport.js";
+import { imageDescriptionOptions, imageListOptions, requireImageId } from "./image-description-contract.js";
 import { formatThemeResolve } from "./theme-resolve.js";
 import { MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS } from "./theme-validation.js";
 import { VERB_HANDLERS } from "./verbs/index.js";
@@ -148,10 +152,14 @@ const VERBS = Object.freeze([
       + "title or hero title is the page's h1, seo.h1_demoted when a # heading is published as an h2 because the "
       + "banner's overlay text, a hero title or an earlier # heading already is the h1 (detail names which), "
       + "seo.heading_renumbered and seo.heading_before_title for headings published at another level, "
-      + "a11y.image_alt_missing and a11y.link_text_empty; for any page seo.title_long and seo.description_missing. "
-      + "siteChecks.checkedInEditor names the rules only the page editor evaluates (a cover, a description field, or a description's length, which descriptionWarnings reports here); "
-      + "siteChecks.checkedBySite names the rules that need the site's own records (images, forms), which "
-      + "'status' reports under siteHealth. A redirect source the site would refuse names its rule in "
+      + "a11y.link_text_empty. Image-default completeness is deferred to the stored deployment report that status reads; "
+      + "placement alt strings do not decide whether an image default is missing. Known author-entered metadata also receives missing, "
+      + "short, long and repeated-title description advice (title guidance 15–70 characters; description 50–160). "
+      + "These are writing suggestions, never requirements. Generated custom values are checked; generated "
+      + "defaults, home-page settings and unknown fields are listed in siteChecks.deferredToDeployment. "
+      + "siteChecks.checkedInEditor names rules only the page editor evaluates, such as a selected cover; "
+      + "siteChecks.checkedBySite names rules whose evidence comes from site records; 'status' reads their "
+      + "stored deployment report under siteHealth without compiling or rescanning drafts. A redirect source the site would refuse names its rule in "
       + "error.problems[].rule. This proves local structure and semantics only. It does not prove "
       + "authorization, live site ownership, concurrency, persisted round trips, or rendering: 'plan' checks a "
       + "workspace against the live site, and 'pages push --dry-run' does that for pages alone. "
@@ -712,6 +720,46 @@ const VERBS = Object.freeze([
     note: "Positional arguments name the files or directories to upload;"
       + " with none, the workspace's media/ directory is walked.",
   },
+  {
+    name: VERB_MEDIA_IMAGES_LIST,
+    surface: SURFACE_DOCS_PRESENTATION,
+    capabilities: [CAPABILITY_CONTENT],
+    surfaceCapabilities: { [SURFACE_DOCS_PRESENTATION]: [CAPABILITY_DESIGN] },
+    tokens: ["media", "images", "list"],
+    summary: "Read one page of the site's image defaults, optionally only missing descriptions.",
+    imageListOptions: true,
+    json: true,
+    note: "Returns images.items and images.nextPageToken. Pass that cursor unchanged for the next page. "
+      + "Filtering happens on the server before pagination; no page bodies or per-image reads are scanned. "
+      + "Description revisions are decimal strings. Preview URLs are for inspection, may expire, and are omitted from GITHUB_OUTPUT.",
+  },
+  {
+    name: VERB_MEDIA_IMAGES_GET,
+    surface: SURFACE_DOCS_PRESENTATION,
+    capabilities: [CAPABILITY_CONTENT],
+    surfaceCapabilities: { [SURFACE_DOCS_PRESENTATION]: [CAPABILITY_DESIGN] },
+    tokens: ["media", "images", "get"],
+    summary: "Read one site-owned library image's default description and revision.",
+    positionals: "imageId",
+    json: true,
+    note: "The image must belong to the selected site's ordinary library; profile, account and installation media are excluded. "
+      + "Use the returned descriptionRevision unchanged when saving. No workspace file is written.",
+  },
+  {
+    name: VERB_MEDIA_IMAGES_DESCRIBE,
+    surface: SURFACE_DOCS_PRESENTATION,
+    capabilities: [CAPABILITY_CONTENT],
+    surfaceCapabilities: { [SURFACE_DOCS_PRESENTATION]: [CAPABILITY_DESIGN] },
+    tokens: ["media", "images", "describe"],
+    summary: "Save or clear an image-owned default with its expected revision.",
+    positionals: "imageId",
+    imageDescriptionOptions: true,
+    json: true,
+    note: "Supply exactly one of --description and --clear, plus --expected-revision from list/get. "
+      + "Text is outer-trimmed and limited by the server to 1000 Unicode scalar values; blank text clears to null. "
+      + "--if-missing is checked atomically on the server and cannot clear. A conflict never retries or overwrites another edit. "
+      + "This changes the reusable image default, never a page-body override. Existing published output changes only after deployment.",
+  },
   {
     name: VERB_APPROVE,
     surface: SURFACE_STANDARD,
@@ -977,6 +1025,8 @@ function verbHelp(verb) {
     ? " <page-path> [--title <text>] [--description <text>] [--author <handle-or-email>]"
     : verb.positionals === "authorHandle"
     ? " <handle> --name <display-name> [--email <address>]"
+    : verb.positionals === "imageId"
+    ? " <image-id>"
     : verb.positionals
     ? ` [${verb.positionals === "paths" ? "path" : "page-path"}...]`
     : "";
@@ -1007,6 +1057,16 @@ function verbHelp(verb) {
   --description <text> The page's description for search results and link previews; '' clears it.
   --author <ref>       Credit a page that has no author: a site author's handle or a member's email address.`
     : "";
+  const imageOptions = verb.imageListOptions
+    ? `\n  --missing-description  Filter to images whose own default is missing.
+  --page-size <n>        Images in this page, 1–100 (default 25).
+  --page-token <cursor>  The preceding result's images.nextPageToken, unchanged.`
+    : verb.imageDescriptionOptions
+    ? `\n  --description <text>   Set the shared image default; --description=<text> accepts leading hyphens.
+  --clear                Clear the default instead of supplying --description.
+  --expected-revision <n> Required decimal revision from list/get, including 0.
+  --if-missing           Save only while the stored default is still null; cannot clear.`
+    : "";
   const authorOptions = verb.authorOptions
     ? `\n  --name <text>        The name readers see on the byline (required).
   --email <address>    A private address, kept to link the person to an account later (optional).`
@@ -1116,7 +1176,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${resolveOptions}${dryRunOption}${archiveOption}${linkOptions}${planOption}${nameOption}${note}
+${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${imageOptions}${jsonOption}${resolveOptions}${dryRunOption}${archiveOption}${linkOptions}${planOption}${nameOption}${note}
 `;
 }
 
@@ -1166,6 +1226,15 @@ function parseLinkOption(rest, index, argument) {
   return { name, value, consumed: inline === undefined ? 1 : 0 };
 }
 
+function parseImageOption(rest, index, argument) {
+  const equals = argument.indexOf("=");
+  const name = equals < 0 ? argument : argument.slice(0, equals);
+  const value = equals < 0 ? rest[index + 1] : argument.slice(equals + 1);
+  if (typeof value !== "string" || (equals < 0 && value.startsWith("--")))
+    throw usageError("cli.option_value", `${name} requires a value.`, { field: name.slice(2) });
+  return { name, value, consumed: equals < 0 ? 1 : 0 };
+}
+
 function usageError(code, message, options = {}) {
   return new SiteAuthoringError(code, message, { ...options, exitCode: 2 });
 }
@@ -1546,6 +1615,7 @@ function parseArguments(arguments_) {
   let planHash;
   let archive = false;
   const linkValues = {};
+  const imageValues = {};
   let metaTitle;
   let metaDescription;
   let metaAuthor;
@@ -1735,6 +1805,23 @@ function parseArguments(arguments_) {
       index += 1;
       continue;
     }
+    if ((verb.imageListOptions && (argument === "--missing-description"))
+      || (verb.imageDescriptionOptions && (argument === "--clear" || argument === "--if-missing"))) {
+      const field = { "--missing-description": "missingDescription", "--clear": "clearDescription", "--if-missing": "onlyIfMissing" }[argument];
+      if (imageValues[field]) throw usageError("cli.duplicate_option", `${argument} may be supplied only once.`);
+      imageValues[field] = true;
+      continue;
+    }
+    const imageOption = argument.split("=", 1)[0];
+    if ((verb.imageListOptions && ["--page-size", "--page-token"].includes(imageOption))
+      || (verb.imageDescriptionOptions && ["--description", "--expected-revision"].includes(imageOption))) {
+      const field = { "--page-size": "pageSize", "--page-token": "pageToken", "--description": "imageDescription", "--expected-revision": "expectedRevision" }[imageOption];
+      if (imageValues[field] !== undefined) throw usageError("cli.duplicate_option", `${imageOption} may be supplied only once.`);
+      const parsed = parseImageOption(rest, index, argument);
+      imageValues[field] = parsed.value;
+      index += parsed.consumed;
+      continue;
+    }
     if (argument.startsWith("-")) {
       throw usageError("cli.unknown_option", "The command contains an unknown option.");
     }
@@ -1838,6 +1925,12 @@ function parseArguments(arguments_) {
       { field: "title" },
     );
   }
+  if (verb.positionals === "imageId") {
+    if (positionals.length !== 1) throw usageError("media.image_id_invalid", "Name exactly one image UUID.", { field: "imageId" });
+    requireImageId(positionals[0]);
+  }
+  if (verb.imageListOptions) imageListOptions(imageValues);
+  if (verb.imageDescriptionOptions) imageDescriptionOptions(imageValues);
   if (verb.positionals === "authorHandle" && positionals.length !== 1) {
     throw usageError("authors.handle_missing", "authors add needs exactly one handle, such as jane-doe.", {
       field: "handle",
@@ -1908,6 +2001,7 @@ function parseArguments(arguments_) {
     ...(planHash === undefined ? {} : { planHash }),
     ...(archive ? { archive } : {}),
     ...linkValues,
+    ...imageValues,
     ...(metaTitle === undefined ? {} : { metaTitle }),
     ...(metaDescription === undefined ? {} : { metaDescription }),
     ...(metaAuthor === undefined ? {} : { metaAuthor }),
@@ -1919,7 +2013,7 @@ function parseArguments(arguments_) {
         values: positionals,
         scalar: verb.positionals === "pageSelector" || verb.positionals === "fixturePath" || verb.positionals === "metaPagePath"
           || verb.positionals === "deletePagePath" || verb.positionals === "siteSelector" || verb.positionals === "environmentSelector"
-          || verb.positionals === "authorHandle",
+          || verb.positionals === "authorHandle" || verb.positionals === "imageId",
       }
       : undefined,
   };
@@ -2016,6 +2110,8 @@ export async function runCli({
       ...(parsed.metaAuthor === undefined ? {} : { metaAuthor: parsed.metaAuthor }),
       ...(parsed.authorName === undefined ? {} : { authorName: parsed.authorName }),
       ...(parsed.authorEmail === undefined ? {} : { authorEmail: parsed.authorEmail }),
+      ...Object.fromEntries(["pageSize", "pageToken", "missingDescription", "imageDescription", "clearDescription", "expectedRevision", "onlyIfMissing"]
+        .filter((field) => parsed[field] !== undefined).map((field) => [field, parsed[field]])),
       capabilities: parsed.capabilities,
       surface: parsed.surface,
       surfaceCapabilities: parsed.surfaceCapabilities,

package/src/constants.js

@@ -101,6 +101,9 @@ export const VERB_THEME_PUSH = "theme push";
 export const VERB_THEME_RESOLVE = "theme resolve";
 export const VERB_FOOTER_PUSH = "footer push";
 export const VERB_MEDIA_UPLOAD = "media upload";
+export const VERB_MEDIA_IMAGES_LIST = "media images list";
+export const VERB_MEDIA_IMAGES_GET = "media images get";
+export const VERB_MEDIA_IMAGES_DESCRIBE = "media images describe";
 export const VERB_APPROVE = "approve";
 export const VERB_DEPLOY = "deploy";
 export const VERB_PREVIEW_PAGE = "preview page";

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 }),
 });
 
 /**
@@ -320,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).
@@ -429,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
@@ -440,7 +446,7 @@ function imageFieldsFor(spec) {
         height: num({ integer: true, minimum: 1, required: true }),
       }
       : {}),
-    ...(spec.altRequired
+    ...(altRequired
       ? {
         alt: str({
           required: true,
@@ -902,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.",
@@ -1133,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)),
@@ -1325,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:
@@ -1593,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.");