@taprootio/site-authoring 0.30.0 → 0.31.0

package/src/page-structure-checks.js

@@ -26,11 +26,16 @@ export const RULE_H1_DEMOTED = "seo.h1_demoted";
 export const RULE_H1_MULTIPLE = "seo.h1_multiple";
 export const RULE_HEADING_RENUMBERED = "seo.heading_renumbered";
 export const RULE_HEADING_BEFORE_TITLE = "seo.heading_before_title";
-export const RULE_IMAGE_ALT_MISSING = "a11y.image_alt_missing";
+// Image completeness is assessed from frozen library defaults during deployment.
+export const RULE_IMAGE_DEFAULT_MISSING = "a11y.image_default_missing";
 export const RULE_LINK_TEXT_EMPTY = "a11y.link_text_empty";
+export const RULE_TITLE_MISSING = "seo.title_missing";
+export const RULE_TITLE_SHORT = "seo.title_short";
 export const RULE_TITLE_LONG = "seo.title_long";
 export const RULE_DESCRIPTION_MISSING = "seo.description_missing";
+export const RULE_DESCRIPTION_SHORT = "seo.description_short";
 export const RULE_DESCRIPTION_LONG = "seo.description_long";
+export const RULE_DESCRIPTION_MATCHES_TITLE = "seo.description_matches_title";
 export const RULE_SOCIAL_IMAGE_FALLBACK = "seo.social_image_fallback";
 const RULE_ORDER = [
     RULE_H1_MISSING,
@@ -38,17 +43,42 @@ const RULE_ORDER = [
     RULE_H1_MULTIPLE,
     RULE_HEADING_RENUMBERED,
     RULE_HEADING_BEFORE_TITLE,
-    RULE_IMAGE_ALT_MISSING,
     RULE_LINK_TEXT_EMPTY,
+    RULE_TITLE_MISSING,
+    RULE_TITLE_SHORT,
     RULE_TITLE_LONG,
     RULE_DESCRIPTION_MISSING,
+    RULE_DESCRIPTION_SHORT,
     RULE_DESCRIPTION_LONG,
+    RULE_DESCRIPTION_MATCHES_TITLE,
     RULE_SOCIAL_IMAGE_FALLBACK,
 ];
-/** Search results cut a title off after about this many characters. */
-export const TITLE_WARN_LENGTH = 60;
-/** Search results cut a description off after about this many characters. */
+/** Product guidance for useful metadata, not search-engine limits. */
+export const TITLE_MINIMUM_LENGTH = 15;
+export const TITLE_WARN_LENGTH = 70;
+export const DESCRIPTION_MINIMUM_LENGTH = 50;
 export const DESCRIPTION_WARN_LENGTH = 160;
+export const METADATA_RULE_IDS = [
+    RULE_TITLE_MISSING,
+    RULE_TITLE_SHORT,
+    RULE_TITLE_LONG,
+    RULE_DESCRIPTION_MISSING,
+    RULE_DESCRIPTION_SHORT,
+    RULE_DESCRIPTION_LONG,
+    RULE_DESCRIPTION_MATCHES_TITLE,
+];
+/** Local authoring cannot resolve a home page's site settings or generated fallbacks. */
+export function localAuthoringMetadata(input) {
+    if (input.homePage)
+        return {};
+    if (input.generated) {
+        return {
+            title: input.generated.customTitle?.trim() ? input.generated.customTitle : undefined,
+            description: input.generated.customDescription?.trim() ? input.generated.customDescription : undefined,
+        };
+    }
+    return { title: input.title, description: input.description };
+}
 const MAXIMUM_DEPTH = 256;
 const MAXIMUM_SUBJECT_LENGTH = 80;
 const characters = (value) => [...value].length;
@@ -162,16 +192,6 @@ function walkBody(body) {
             case "taprootImage": {
                 imageCount++;
                 seeContent();
-                if (!nonBlank(node.attrs?.alt)) {
-                    const id = node.attrs?.imageId;
-                    findings.push({
-                        ruleId: RULE_IMAGE_ALT_MISSING,
-                        severity: "warning",
-                        subject: typeof id === "string" ? id : "",
-                        detail: "",
-                        path,
-                    });
-                }
                 return;
             }
             case "componentBlock": {
@@ -182,19 +202,10 @@ function walkBody(body) {
                 const fixedLevel = componentFixedHeadingLevel(type, data);
                 if (type === "image-banner" && imageSource(data.image)) {
                     imageCount++;
-                    if (!nonBlank(data.altText)) {
-                        findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
-                    }
                 }
                 // The social preview also draws on a hero's picture.
                 if (type === "hero-section" && imageSource(data.media)) {
                     imageCount++;
-                    if (!nonBlank(data.media.alt)) {
-                        findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
-                    }
-                }
-                if (type === "cta" && imageSource(data.mediaImage) && !nonBlank(data.mediaImage.alt)) {
-                    findings.push({ ruleId: RULE_IMAGE_ALT_MISSING, severity: "warning", subject: "", detail: "", path });
                 }
                 if (opensPage) {
                     recordFixedHeading(outline, 1);
@@ -322,27 +333,21 @@ function collectFindings(page) {
         findings.push(...walked.findings);
         imageCount = walked.imageCount;
     }
-    if (typeof page.title === "string" && characters(page.title.trim()) > TITLE_WARN_LENGTH) {
-        findings.push({
-            ruleId: RULE_TITLE_LONG,
-            severity: "warning",
-            subject: "",
-            detail: String(characters(page.title.trim())),
-        });
-    }
-    if (typeof page.description === "string") {
-        const description = page.description.trim();
-        if (description === "") {
-            findings.push({ ruleId: RULE_DESCRIPTION_MISSING, severity: "warning", subject: "", detail: "" });
-        }
-        else if (characters(description) > DESCRIPTION_WARN_LENGTH) {
-            findings.push({
-                ruleId: RULE_DESCRIPTION_LONG,
-                severity: "warning",
-                subject: "",
-                detail: String(characters(description)),
-            });
-        }
+    const checkText = (value, minimum, maximum, missingRule, shortRule, longRule) => {
+        if (typeof value !== "string")
+            return;
+        const count = characters(value.trim());
+        const ruleId = count === 0 ? missingRule : count < minimum ? shortRule : count > maximum ? longRule : undefined;
+        if (ruleId)
+            findings.push({ ruleId, severity: "warning", subject: "", detail: count === 0 ? "" : String(count) });
+    };
+    checkText(page.title, TITLE_MINIMUM_LENGTH, TITLE_WARN_LENGTH, RULE_TITLE_MISSING, RULE_TITLE_SHORT, RULE_TITLE_LONG);
+    checkText(page.description, DESCRIPTION_MINIMUM_LENGTH, DESCRIPTION_WARN_LENGTH, RULE_DESCRIPTION_MISSING, RULE_DESCRIPTION_SHORT, RULE_DESCRIPTION_LONG);
+    const normalize = (value) => typeof value === "string" ? value.trim().replace(/\s+/gu, " ").toLowerCase() : undefined;
+    const title = normalize(page.title);
+    const description = normalize(page.description);
+    if (title && description && title === description) {
+        findings.push({ ruleId: RULE_DESCRIPTION_MATCHES_TITLE, severity: "warning", subject: "", detail: "" });
     }
     if (page.freeForm && page.hasCover === false) {
         findings.push({

package/src/reference-help.js

@@ -95,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 49;
+export const REFERENCE_VERSION = 50;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -1018,10 +1018,14 @@ const WORKFLOW_REFERENCES = Object.freeze({
     }),
   }),
   media: Object.freeze({
-    title: "Media upload contract",
-    summary: "Upload workspace-root-relative raster files and videos; images are recorded in .taproot-site-media.json and videos report their ids.",
-    usage: `${CLI_BINARY_NAME} media upload [path...]`,
+    title: "Image defaults and media upload",
+    summary: "Read and change site-owned image defaults by ID, or upload workspace-root-relative raster files and videos.",
+    usage: `${CLI_BINARY_NAME} media images list|get|describe | media upload [path...]`,
     details: Object.freeze([
+      "media images list returns one page in images.items and images.nextPageToken; pass --page-size 1–100 (default 25) and --page-token with that exact cursor for the next page. --missing-description is a server-side filter for a null image-owned default, independent of placement alt text, captions or decorative mode. No per-result reads or page-body scans run. The authoritative default-completeness findings are in the frozen deployment report that status reads; local validate does not infer them from placement strings.",
+      "media images get <image-id> reads one library image in the selected site. Both reads expose imageId, uploadedName, defaultDescription (null when missing), descriptionRevision as a decimal string, width, height, processingState, previewUrl and responsivePreviewUrls. Preview URLs are for inspection, may expire, and are omitted from GITHUB_OUTPUT. They are not descriptions and these verbs write no workspace file.",
+      "media images describe <image-id> --description <text> --expected-revision <n> saves the default; --clear replaces --description to remove it. Supply the exact revision from list/get, including 0. --if-missing is an atomic server condition, requires nonblank text, and refuses an existing default. Conflicts report media.image_description_conflict or media.image_description_exists with exit 1; read the current image and reconcile, never retry by overwriting it blindly. Input/option errors use exit 2.",
+      "The server owns the 1000-Unicode-scalar limit: outer whitespace is trimmed, blank text becomes null, and oversized text is rejected without truncation. Descriptions may contain Unicode and newlines. The CLI preserves their text in JSON and never copies preview URLs or resolved defaults into page bodies. Site media management is required for all three verbs; profile/account/installation media are excluded. A default edit affects inherited usages at the next selected deployment; current published and in-flight snapshots keep their frozen text, while contextual overrides and decorative placements keep their choices.",
       "Paths are relative to the configured workspace root, not the shell's current directory.",
       "PNG, JPEG, GIF, and WebP are accepted. Each file uploads as its own image: a name such as logo@2x.png is only a filename, nothing pairs it with logo.png, and the platform generates the display sizes from the one file you assign (see help appearance for logos).",
       "For header logos prefer genuine transparent PNG/WebP, check contrast in both themes, and include a simplified square favicon. See help appearance for branding guidance.",

package/src/site-check-findings.js

@@ -2,7 +2,7 @@ import { sanitizeDiagnostic } from "./errors.js";
 import { boundedByBytes } from "./session.js";
 import rules from "./site-check-rules.json" with { type: "json" };
 import { isFormKey } from "./forms-contract.js";
-import { DESCRIPTION_WARN_LENGTH, pageStructureFindings, TITLE_WARN_LENGTH } from "./page-structure-checks.js";
+import { DESCRIPTION_MINIMUM_LENGTH, DESCRIPTION_WARN_LENGTH, localAuthoringMetadata, METADATA_RULE_IDS, pageStructureFindings, TITLE_MINIMUM_LENGTH, TITLE_WARN_LENGTH } from "./page-structure-checks.js";
 import { missingPageLinkFindings, normalizedPathSet } from "./site-checks.js";
 import { documentTemplate, TEMPLATE_FREE_FORM, TEMPLATE_GENERATED } from "./typed-pages.js";
 import { displayPagePath } from "./workspace.js";
@@ -51,13 +51,15 @@ export const SITE_CHECK_WORDING = Object.freeze({
   },
   "seo.heading_before_title": (finding) =>
     `has the heading '${finding.subject}' before the page's h1; it publishes as an h${finding.detail}`,
-  "a11y.image_alt_missing": () => "places an image with no alt text",
+  "a11y.image_default_missing": () => "has no default image description; set one with media images describe, then deploy",
   "a11y.link_text_empty": (finding) => `has a link to ${finding.subject} with no text`,
-  "seo.title_long": (finding) =>
-    `has a title of ${finding.detail} characters; search results show about ${TITLE_WARN_LENGTH}`,
-  "seo.description_missing": () => "has no description; search results use the start of the page instead",
-  "seo.description_long": (finding) =>
-    `has a description of ${finding.detail} characters; search results show about ${DESCRIPTION_WARN_LENGTH}`,
+  "seo.title_missing": () => "has no title; add one that identifies the page",
+  "seo.title_short": (finding) => `has a title of ${finding.detail} characters; consider a more specific title (guidance: ${TITLE_MINIMUM_LENGTH}–${TITLE_WARN_LENGTH})`,
+  "seo.title_long": (finding) => `has a title of ${finding.detail} characters; consider shortening it (guidance: ${TITLE_MINIMUM_LENGTH}–${TITLE_WARN_LENGTH})`,
+  "seo.description_missing": () => "has no description; add a short account of what the page offers",
+  "seo.description_short": (finding) => `has a description of ${finding.detail} characters; consider adding useful detail (guidance: ${DESCRIPTION_MINIMUM_LENGTH}–${DESCRIPTION_WARN_LENGTH})`,
+  "seo.description_long": (finding) => `has a description of ${finding.detail} characters; consider shortening it (guidance: ${DESCRIPTION_MINIMUM_LENGTH}–${DESCRIPTION_WARN_LENGTH})`,
+  "seo.description_matches_title": () => "has a description that repeats its title; explain what readers will find",
   "seo.social_image_fallback": (finding) =>
     finding.detail === "first_image"
       ? "has no cover image; link previews use the page's first image only when it is public and at least 1200 pixels wide"
@@ -91,15 +93,17 @@ const OFFLINE_DOCUMENT_RULES = new Set(
 function structureFindingsFor(page) {
   if (page.document === null || typeof page.document !== "object") return [];
   const template = documentTemplate(page.document);
-  // A generated page's title and description come from the site, not from an author.
-  if (template === TEMPLATE_GENERATED) return [];
   const freeForm = template === TEMPLATE_FREE_FORM;
   return pageStructureFindings(
     {
       freeForm,
       body: freeForm ? page.document : undefined,
-      title: page.title,
-      description: page.declaredDescription ?? page.description,
+      ...localAuthoringMetadata({
+        title: page.title,
+        description: page.metadataDescriptionKnown === false ? undefined : page.declaredDescription ?? page.description,
+        homePage: page.pagePath === "" || page.pagePath === "/",
+        generated: template === TEMPLATE_GENERATED ? page.document.data ?? {} : undefined,
+      }),
     },
     OFFLINE_DOCUMENT_RULES,
   );
@@ -166,6 +170,8 @@ export function evaluateOfflineSiteChecks({
     },
     siteChecks: {
       ranOffline: rulesRunningAt("validate"),
+      // Local values are checked above; only a deployment knows every effective fallback.
+      deferredToDeployment: [...METADATA_RULE_IDS],
       // Rules that need the site's own records; `taproot-site status` shows what the site finds.
       checkedBySite: SITE_CHECK_RULES.filter((rule) => !rule.runsAt.includes("validate") && rule.runsAt.includes("health"))
         .map((rule) => rule.id),
@@ -173,7 +179,7 @@ export function evaluateOfflineSiteChecks({
       checkedAtDeploy: SITE_CHECK_RULES.filter((rule) =>
         !rule.runsAt.includes("validate") && !rule.runsAt.includes("health") && rule.runsAt.includes("deploy")
       ).map((rule) => rule.id),
-      // Rules only the page editor evaluates: a cover, a description field, or a description's length (which the CLI reports as descriptionWarnings).
+      // Rules only the page editor evaluates, such as its selected cover.
       checkedInEditor: SITE_CHECK_RULES.filter((rule) =>
         !rule.runsAt.includes("validate") && !rule.runsAt.includes("health") && !rule.runsAt.includes("deploy")
         && rule.runsAt.includes("edit")

package/src/site-check-rules.json

@@ -1,10 +1,11 @@
 {
-  "version": 1,
-  "about": "The catalogue of site checks (TR01085, TR00947). Severity: 'error' blocks a deploy, 'warning' informs. Scope: 'page' rules read one page body plus cheap site lookups, 'site' rules read the site's own records, 'document' rules read only one document and its metadata, so the editor and the CLI evaluate them from shared/page-structure-checks.ts and the server does not. runsAt names the run points that evaluate the rule: save, validate (the CLI, offline), deploy, health, edit (the editor, over the open document in the browser). appliesTo, when present, limits a rule to those page types. subject and detail say what a finding's two values hold. The typed registry in Taproot.Domain/SiteChecks/SiteCheckRules.cs must list the same rules; SiteCheckTests fails on a difference.",
+  "version": 2,
+  "about": "The catalogue of site checks (TR01085, TR00947). Severity: 'error' blocks a deploy, 'warning' informs. Scope: 'page' rules read one page body plus cheap site lookups, 'site' rules read the site's own records, 'document' rules read only one document and its metadata, so the editor and the CLI evaluate them from shared/page-structure-checks.ts and the generator compiles deployment advice from the same pure evaluator. runsAt names the run points that evaluate the rule: save, validate (the CLI, offline), deploy, health, edit (the editor, over the open document in the browser). appliesTo, when present, limits a rule to those page types. subject and detail say what a finding's two values hold. The typed registry in Taproot.Domain/SiteChecks/SiteCheckRules.cs must list the same rules; SiteCheckTests fails on a difference.",
   "runPoints": ["save", "validate", "deploy", "health", "edit"],
   "rules": [
     { "id": "link.page_missing", "severity": "warning", "scope": "page", "runsAt": ["save", "validate", "health"], "subject": "page_path", "detail": "none" },
     { "id": "image.missing", "severity": "warning", "scope": "page", "runsAt": ["save", "health"], "subject": "image_id", "detail": "none" },
+    { "id": "a11y.image_default_missing", "severity": "warning", "scope": "site", "runsAt": ["deploy", "health"], "subject": "image_id", "detail": "none" },
     { "id": "form.none_chosen", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "none", "detail": "none" },
     { "id": "form.unreadable", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "form_reference_text", "detail": "none" },
     { "id": "form.missing", "severity": "error", "scope": "page", "runsAt": ["save", "deploy", "health"], "subject": "form_id", "detail": "none" },
@@ -24,11 +25,14 @@
     { "id": "seo.h1_multiple", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "h1_claimant" },
     { "id": "seo.heading_renumbered", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "authored_and_published_level" },
     { "id": "seo.heading_before_title", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "heading_text", "detail": "published_level" },
-    { "id": "a11y.image_alt_missing", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "image_id", "detail": "none" },
     { "id": "a11y.link_text_empty", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["validate", "edit"], "subject": "link_target", "detail": "none" },
-    { "id": "seo.title_long", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit"], "subject": "none", "detail": "character_count" },
-    { "id": "seo.description_missing", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit"], "subject": "none", "detail": "none" },
-    { "id": "seo.description_long", "severity": "warning", "scope": "document", "runsAt": ["edit"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.title_missing", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "none" },
+    { "id": "seo.title_short", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.title_long", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.description_missing", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "none" },
+    { "id": "seo.description_short", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.description_long", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "character_count" },
+    { "id": "seo.description_matches_title", "severity": "warning", "scope": "document", "runsAt": ["validate", "edit", "deploy", "health"], "subject": "none", "detail": "none" },
     { "id": "seo.social_image_fallback", "severity": "warning", "scope": "document", "appliesTo": ["free_form"], "runsAt": ["edit"], "subject": "none", "detail": "social_image_source" }
   ]
 }

package/src/typed-pages.js

@@ -1,6 +1,8 @@
 import { FREE_FORM_TEMPLATE_VERSION, TEMPLATE_TYPE_FREE_FORM } from "./api.js";
 import { isVideoEmbedId } from "./content/video-embed-url.js";
 import { SiteAuthoringError } from "./errors.js";
+import { isImageDescriptionMode } from "./content/image-description-validation.js";
+import { stripImageDescriptionHydration } from "./content/image-description-document.js";
 import { requireDescriptionLength } from "./page-metadata.js";
 
 /**
@@ -323,7 +325,7 @@ const RECIPE_KEYS = [
   "cookingMethod",
 ];
 const ALBUM_KEYS = ["introductionBody", "images", "seamless", "borderWidth", "place"];
-const ALBUM_IMAGE_KEYS = ["imageId", "caption", "width", "height"];
+const ALBUM_IMAGE_KEYS = ["imageId", "caption", "width", "height", "altText", "descriptionMode"];
 const ALBUM_MAXIMUM_BORDER_WIDTH = 20;
 const MAXIMUM_MINUTES = 100_000;
 const MAXIMUM_SERVINGS = 10_000;
@@ -372,12 +374,17 @@ const DATA_BUILDERS = Object.freeze({
       ["introductionBody", raw.introductionBody],
       [
         "images",
-        raw.images.map((image) => ({
-          imageId: image.imageId,
-          caption: image.caption ?? "",
-          width: image.width ?? 0,
-          height: image.height ?? 0,
-        })),
+        raw.images.map((image) => {
+          const authored = stripImageDescriptionHydration(image);
+          return definedEntries([
+            ["imageId", authored.imageId],
+            ["caption", authored.caption ?? ""],
+            ["width", authored.width ?? 0],
+            ["height", authored.height ?? 0],
+            ["altText", authored.altText],
+            ["descriptionMode", authored.descriptionMode],
+          ]);
+        }),
       ],
       ["seamless", raw.seamless],
       ["borderWidth", raw.borderWidth],
@@ -486,6 +493,14 @@ function canonicalSourceData(template, data, file) {
       requireKeys(image, ALBUM_IMAGE_KEYS, file, at);
       requireIdentifier(image.imageId, file, `${at}.imageId`);
       if (image.caption !== undefined) requireString(image.caption, file, `${at}.caption`);
+      if (!isImageDescriptionMode(image.descriptionMode)) {
+        throw fail(
+          "pages.document_shape",
+          `'${file}' ${at}.descriptionMode must be inherit, custom or decorative.`,
+          `${file}:${at}.descriptionMode`,
+        );
+      }
+      if (image.altText !== undefined && image.altText !== null) requireString(image.altText, file, `${at}.altText`);
       if (image.width !== undefined) requireCount(image.width, file, `${at}.width`, 100_000);
       if (image.height !== undefined) requireCount(image.height, file, `${at}.height`, 100_000);
     });
@@ -684,8 +699,9 @@ export function workspaceDocumentFromPage(page, listedTemplateType) {
   if (name === undefined) return undefined;
   const raw = template[PAGE_TEMPLATES[name].dataKey];
   if (!isPlainObject(raw)) return undefined;
-  if (name === TEMPLATE_FREE_FORM) return isPlainObject(raw.body) ? raw.body : undefined;
-  const data = PAGE_PROJECTIONS[name](raw);
+  const authored = stripImageDescriptionHydration(raw);
+  if (name === TEMPLATE_FREE_FORM) return isPlainObject(authored.body) ? authored.body : undefined;
+  const data = PAGE_PROJECTIONS[name](authored);
   if (data === undefined) return undefined;
   // A generated page's date and cover are not part of its source: a push leaves them as the site holds them.
   const generated = name === TEMPLATE_GENERATED || name === TEMPLATE_LEGAL;

package/src/verbs/deploy.js

@@ -1,3 +1,4 @@
+import { describeNavigationReadiness, isNavigationReady, reportNavigationReadiness } from "../navigation-readiness.js";
 import {
   DEPLOYMENT_ENVIRONMENT_PRODUCTION,
   DEPLOYMENT_ENVIRONMENT_STAGING,
@@ -154,6 +155,7 @@ function reportReadiness(readiness) {
   const blockers = boundedList(readiness.blockers, MAXIMUM_REPORTED_BLOCKERS);
   return {
     state: readiness.state,
+    navigationReadiness: reportNavigationReadiness(readiness.navigationReadiness),
     approvedPageCount: readiness.approvedPageCount,
     selectedPageCount: readiness.selectedPageCount,
     blockedPageCount: readiness.blockedPageCount,
@@ -350,6 +352,15 @@ export async function deploy(invocation) {
       // The estimate must recognize the request it is about to be followed by.
       ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
+    onProgress(describeNavigationReadiness(readiness.navigationReadiness));
+    if (!isNavigationReady(readiness.navigationReadiness)) {
+      const media = readiness.blockers.length ? ` This candidate also has ${readiness.blockers.length} media blocker(s).` : "";
+      throw new SiteAuthoringError(
+        "deploy.navigation_blocked",
+        describeNavigationReadiness(readiness.navigationReadiness) + media,
+        { field: "Navigation", status: readiness.navigationReadiness.state },
+      );
+    }
     if (readiness.blockers.length > 0) {
       throw new SiteAuthoringError(
         "deploy.media_blocked",

package/src/verbs/index.js

@@ -17,6 +17,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,
@@ -58,6 +61,7 @@ import { logout } from "./logout.js";
 import { marketingPull } from "./marketing-pull.js";
 import { marketingPush } from "./marketing-push.js";
 import { mediaUpload } from "./media-upload.js";
+import { mediaImagesDescribe, mediaImagesGet, mediaImagesList } from "./media-images.js";
 import { navPush } from "./nav-push.js";
 import { pagesDelete } from "./pages-delete.js";
 import { pagesMetaSet } from "./pages-meta-set.js";
@@ -118,6 +122,9 @@ import { whoami } from "./whoami.js";
  * ```
  * {
  *   fixturePath,   // validate: one offline authoring-fixture directory
+ *   imageId,       // media images get/describe: site-owned library image UUID
+ *   pageSize, pageToken, missingDescription, // media images list
+ *   imageDescription, clearDescription, expectedRevision, onlyIfMissing, // media images describe
  *   paths,         // media upload: files and/or directories to upload;
  *                  //   with none, the workspace's media/ directory is walked
  *   formKeys,      // forms validate / push: narrow to these form keys;
@@ -187,6 +194,9 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_MARKETING_PUSH]: marketingPush,
   [VERB_LINK_BUILD]: linkBuild,
   [VERB_MEDIA_UPLOAD]: mediaUpload,
+  [VERB_MEDIA_IMAGES_LIST]: mediaImagesList,
+  [VERB_MEDIA_IMAGES_GET]: mediaImagesGet,
+  [VERB_MEDIA_IMAGES_DESCRIBE]: mediaImagesDescribe,
   [VERB_APPROVE]: approve,
   [VERB_DEPLOY]: deploy,
   [VERB_PREVIEW_PAGE]: previewPage,

package/src/verbs/media-images.js

@@ -0,0 +1,67 @@
+import { getSiteImageDescription, listSiteImageDescriptions, updateSiteImageDescription, withRefusalGuidance } from "../api.js";
+import { VERB_MEDIA_IMAGES_DESCRIBE, VERB_MEDIA_IMAGES_GET, VERB_MEDIA_IMAGES_LIST } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import { imageDescriptionOptions, imageListOptions, requireImageId } from "../image-description-contract.js";
+import { serializeResult } from "../output.js";
+import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { ApiError } from "../transport.js";
+
+export async function mediaImagesList(invocation) {
+  const options = imageListOptions(invocation);
+  const { client, siteId, onProgress } = await openSession(invocation);
+  const images = await withRefusalGuidance(onProgress, VERB_MEDIA_IMAGES_LIST, () =>
+    listSiteImageDescriptions(client, siteId, options));
+  const result = successResult(VERB_MEDIA_IMAGES_LIST, siteId, {
+    images: { ...images, count: images.items.length, missingDescription: options.missingDescription },
+  });
+  try {
+    serializeResult(result);
+  } catch (error) {
+    if (!(error instanceof SiteAuthoringError) || error.code !== "output.too_large") throw error;
+    throw new SiteAuthoringError("media.image_page_too_large",
+      "This page exceeds the output bound. Repeat the same cursor with a smaller --page-size; no items were omitted.",
+      { field: "pageSize" });
+  }
+  onProgress(`${images.items.length} image(s) returned${images.nextPageToken ? "; use images.nextPageToken for the next page" : ""}.`);
+  return result;
+}
+
+export async function mediaImagesGet(invocation) {
+  const imageId = requireImageId(invocation.imageId);
+  const { client, siteId, onProgress } = await openSession(invocation);
+  const image = await withRefusalGuidance(onProgress, VERB_MEDIA_IMAGES_GET, () =>
+    getSiteImageDescription(client, siteId, imageId));
+  onProgress(`Read image ${image.imageId}, description revision ${image.descriptionRevision}.`);
+  return successResult(VERB_MEDIA_IMAGES_GET, siteId, { image });
+}
+
+export async function mediaImagesDescribe(invocation) {
+  const imageId = requireImageId(invocation.imageId);
+  const body = imageDescriptionOptions(invocation);
+  const session = await openSession(invocation);
+  warnIfExternalWritesPaused(session, VERB_MEDIA_IMAGES_DESCRIBE);
+  const { client, siteId, onProgress } = session;
+  const image = await withRefusalGuidance(onProgress, VERB_MEDIA_IMAGES_DESCRIBE, async () => {
+    try {
+      return await updateSiteImageDescription(client, siteId, imageId, body);
+    } catch (error) {
+      if (error instanceof ApiError && error.hasField("ExpectedRevision")) {
+        throw new SiteAuthoringError("media.image_description_conflict",
+          "The description changed. Read it with 'media images get', reconcile the text, and supply that revision.",
+          { field: "expectedRevision", status: error.status });
+      }
+      if (error instanceof ApiError && error.hasField("OnlyIfMissing")) {
+        throw new SiteAuthoringError("media.image_description_exists", "This image already has a default description; nothing changed.",
+          { field: "onlyIfMissing", status: error.status });
+      }
+      if (error instanceof ApiError && error.hasField("DefaultDescription")) {
+        throw new SiteAuthoringError("media.image_description_invalid",
+          error.descriptionFor("DefaultDescription") ?? "Taproot refused the default description.",
+          { field: "defaultDescription", status: error.status });
+      }
+      throw error;
+    }
+  });
+  onProgress(`Saved image ${image.imageId}, description revision ${image.descriptionRevision}. Deploy to update published usages.`);
+  return successResult(VERB_MEDIA_IMAGES_DESCRIBE, siteId, { image });
+}

package/src/verbs/pages-push.js

@@ -1548,7 +1548,8 @@ export async function planPages({
         pagePath,
         title: sentTitle,
         // Only the owner's own description is warned about for length: the derived one is not theirs to shorten.
-        ...(generated ? { declaredDescription: document_.data.customDescription } : {}),
+        declaredDescription: generated ? document_.data.customDescription : declaredDescription,
+        metadataDescriptionKnown: generated || typeof declaredDescription === "string",
         contentKey,
         unchanged,
         description: sentDescription,

package/src/verbs/status.js

@@ -1,3 +1,4 @@
+import { describeNavigationReadiness, reportNavigationReadiness } from "../navigation-readiness.js";
 import {
   getDeploySelection,
   getPublishingReadiness,
@@ -162,7 +163,7 @@ export async function status(invocation) {
     if (!presentationOnly) {
       onProgress("Reading image processing state.");
       ({ images, summary, truncated } = await listSiteImages(client, siteId));
-      onProgress("Reading site health.");
+      onProgress("Reading the stored deployment health report.");
       health = await getSiteHealth(client, siteId);
     }
     const reportedFindings = boundedList(health.findings, MAXIMUM_HEALTH_FINDINGS);
@@ -184,10 +185,14 @@ export async function status(invocation) {
     const reportedDeployments = boundedList(deployments, MAXIMUM_DEPLOYMENTS);
     const blockers = boundedList(readiness.blockers, MAXIMUM_BLOCKERS);
 
+    onProgress(describeNavigationReadiness(readiness.navigationReadiness));
+    const assessed = ["complete", "incomplete"].includes(health.status) && Boolean(health.deploymentId);
     if (!presentationOnly) {
-      onProgress(
-        `Site health: ${health.errorCount} problem(s) and ${health.warningCount} warning(s) on ${health.pageCount} page(s).`,
-      );
+      onProgress(assessed
+        ? `Site health (${health.environment}, checked ${health.checkedAt}): ${health.errorCount} problem(s) and ${health.warningCount} warning(s). Unpublished changes are outside this report.`
+        : health.status === "not_checked"
+        ? "Site health: not checked yet. Deploy the site to create a report."
+        : "Site health: no complete supported deployment assessment is available.");
     }
 
     return successResult(VERB_STATUS, siteId, {
@@ -196,6 +201,7 @@ export async function status(invocation) {
       ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
       readiness: {
         state: readiness.state,
+        navigationReadiness: reportNavigationReadiness(readiness.navigationReadiness),
         approvedPageCount: readiness.approvedPageCount,
         blockedPageCount: readiness.blockedPageCount,
         hasCandidateChanges: readiness.hasCandidateChanges,
@@ -227,12 +233,20 @@ export async function status(invocation) {
         ...(truncated ? { listTruncated: true } : {}),
       },
       siteHealth: presentationOnly ? { covered: false, reason: DOCS_SITE_NOT_COVERED_NOTE } : {
-        covered: true,
+        covered: assessed,
+        status: health.status ?? "unknown",
+        ...(assessed ? {
+        deploymentId: health.deploymentId, outputReleaseId: health.outputReleaseId,
+        inputHash: health.inputHash, checkedAt: health.checkedAt, ruleVersion: health.ruleVersion,
+        coverage: health.coverage, assessedPages: health.assessedPageCount, environment: health.environment,
+        unpublishedChangesAssessed: false,
         errors: health.errorCount,
         warnings: health.warningCount,
         pages: health.pageCount,
         findings: reportedFindings.items,
+        imageFindings: health.images,
         ...(reportedFindings.truncated || health.truncated ? { findingsTruncated: true } : {}),
+        } : { reason: health.status === "not_checked" ? "Not checked yet; deploy the site to create a report." : "A complete supported deployment assessment is unavailable." }),
       },
     });
   });