@taprootio/site-authoring 0.30.0 → 0.32.0

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,
@@ -702,7 +708,13 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     "Spacer",
     "Intentional vertical separation with an optional decorative divider.",
     { height: "medium", showDivider: false, dividerStyle: "solid", dividerWidth: 1 },
-    ["Do not use spacing alone to communicate document structure; keep headings and landmarks semantic."],
+    [
+      "Do not use spacing alone to communicate document structure; keep headings and landmarks semantic.",
+      "Blocks already sit one gap apart, set by the site's blockSpacing (help settings). A spacer adds its height to "
+      + "that gap: after text the gap is the spacer's height plus one gap, and between two components it is one gap, "
+      + "the height, and one gap. Review spacers placed to work around tight spacing, and remove ones that are no "
+      + "longer needed.",
+    ],
     { height: "large", showDivider: true, dividerStyle: "solid", dividerWidth: 1 },
   ),
   "latest-posts": component(
@@ -902,10 +914,10 @@ 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.",
+      "A link to another site opens in a new tab with nothing to set. The site's own addresses, relative paths, mailto: and tel: links open in the same tab.",
     ],
     {
       items: [
@@ -944,7 +956,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     [
       "A button's visible text is its accessible name, and the product's title heads the same list item, so \"Buy now\" on every card reads with its product. Say what the button does, such as \"Buy now\" or \"Book a trial\".",
       PRODUCT_GRID_BUTTON_TEXT_NOTE,
-      "buttonText and buttonUrl go together: text without an address and an address without text are both refused. Links open in the same tab, as card-grid and feature-grid links do.",
+      "buttonText and buttonUrl go together: text without an address and an address without text are both refused. A button to another site opens in a new tab with nothing to set. The site's own addresses, relative paths, mailto: and tel: links open in the same tab.",
       "price is free text (\"From $30\", \"Free\"); priceNote is shown beside it and refused without a price.",
       "An image is optional and cropped to 16:9. Its alt may be blank when the title already says what the picture shows; in Markdown the alt comes from the media manifest entry.",
       "highlighted draws a border of at least 2px (the borderWidth when that is larger) and the badge in the site's action color to mark one card, such as the most popular plan. The grid displays products only: no cart, payments or inventory.",
@@ -989,7 +1001,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     [
       "A link's text is its accessible name: the label if set, else the platform's name. With showLabels false the text is visually hidden and read by screen readers only, so the name is the same either way.",
       "Link only to accounts you control; each platform's brand rules apply to its mark. " + UNSUPPORTED_DOMAIN_NOTE,
-      "platform other is any website and needs a label, such as \"Book online\". A named platform's link carries rel=\"me\"; a Website link carries no rel.",
+      "platform other is any website and needs a label, such as \"Book online\". A link to another site opens in a new tab with nothing to set: a named platform's link publishes rel=\"me noopener noreferrer\", a Website link publishes rel=\"noopener noreferrer\", and a link to the site's own address stays in the same tab.",
     ],
     {
       items: [
@@ -1065,7 +1077,7 @@ function referenceSchema(spec) {
           type: "string",
           format: "https-url",
           maxLength: SOCIAL_LINK_URL_MAX_LENGTH,
-          description: `An ${HTTPS_URL_DESCRIPTION.slice(3)}. ${UNSUPPORTED_DOMAIN_NOTE}`,
+          description: `An ${HTTPS_URL_DESCRIPTION.slice(3)}. ${UNSUPPORTED_DOMAIN_NOTE} A link to another site opens in a new tab with nothing to set.`,
         };
       }
       return {
@@ -1073,7 +1085,7 @@ function referenceSchema(spec) {
         format: spec.allowEmpty === false ? "safe-url" : "safe-url-or-empty",
         description: `${
           spec.allowEmpty === false ? "An" : "Empty, or an"
-        } explicit HTTP(S), mailto, or tel URL; a root-relative path that does not begin with //; a fragment; a query; or a relative URL. Backslashes and ASCII control characters are rejected. Contact URLs require a non-empty body and refuse tel:// and mailto:// authority forms.`,
+        } explicit HTTP(S), mailto, or tel URL; a root-relative path that does not begin with //; a fragment; a query; or a relative URL. Backslashes and ASCII control characters are rejected. Contact URLs require a non-empty body and refuse tel:// and mailto:// authority forms. A web address on another site opens in a new tab with nothing to set; the site's own addresses, relative paths, fragments, queries, mailto and tel links do not.`,
       };
     case "css-length":
       return { type: "string", description: `Must be ${describe(spec)}.` };
@@ -1133,7 +1145,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 +1337,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 +1605,10 @@ export function canonicalizeComponentData(componentType, data) {
   const fields = isComponentType(componentType) ? COMPONENT_SHAPES[componentType] : undefined;
   if (!fields) throw new TypeError("canonicalizeComponentData requires a known component type.");
   if (!isPlainObject(data)) throw new TypeError("canonicalizeComponentData requires an object.");
+  const authored = stripImageDescriptionHydration(data);
   const ordered = {};
   for (const key of Object.keys(fields)) {
-    if (Object.hasOwn(data, key)) ordered[key] = orderValue(fields[key], data[key]);
+    if (Object.hasOwn(authored, key)) ordered[key] = orderValue(fields[key], authored[key]);
   }
   for (const key of Object.keys(data)) {
     if (!Object.hasOwn(fields, key)) throw new TypeError("canonicalizeComponentData requires validated data.");

package/src/content/external-link.js

@@ -0,0 +1,77 @@
+// Generated from shared/external-link.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * The one owner of which links open in a new tab (TR01327).
+ *
+ * A link opens in a new tab when its address is an absolute http or https URL
+ * whose host is not one of the site's own. Everything else (relative paths,
+ * fragments, mailto, tel, anything that does not parse) stays in the tab.
+ *
+ * It is pure and dependency-free. The generator, the editor and the
+ * site-authoring CLI cannot import this file across project roots, so
+ * `node scripts/sync-field-validation.mjs` writes their copies; edit only this
+ * file and re-run it.
+ */
+/** A host as the rule compares it: lowercase, with one leading `www.` dropped. */
+export function normalizeLinkHost(host) {
+    const lowered = (host ?? "").trim().toLowerCase();
+    return lowered.startsWith("www.") ? lowered.slice(4) : lowered;
+}
+/** The site's own hosts, normalized. Empty and missing hosts are left out. */
+export function siteLinkHosts(hosts) {
+    const set = new Set();
+    for (const host of hosts) {
+        const normalized = normalizeLinkHost(host);
+        if (normalized)
+            set.add(normalized);
+    }
+    return set;
+}
+/** True for an absolute http or https URL to a host outside the set. */
+export function isExternalLink(href, siteHosts) {
+    if (!href)
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(href.trim());
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return false;
+    return !siteHosts.has(normalizeLinkHost(parsed.hostname));
+}
+/** A rel with `noopener noreferrer` after its existing tokens, without duplicates. */
+export function relWithNewTabTokens(rel) {
+    const tokens = new Set((rel ?? "").split(/\s+/u).filter(Boolean));
+    tokens.add("noopener");
+    tokens.add("noreferrer");
+    return [...tokens].join(" ");
+}
+/**
+ * The `target` and `rel` attributes for a link that opens in a new tab, as
+ * markup with a leading space. The values are tokens, so nothing needs escaping.
+ */
+export function newTabAttributeMarkup(rel) {
+    return ` target="_blank" rel="${relWithNewTabTokens(rel)}"`;
+}
+/**
+ * What a screen reader hears after a link's name when it opens a new tab. These
+ * are the words Espalier appends to its own links, so a native anchor and an
+ * `esp-button` read alike. `generator/browser-tests/new-tab-cue.spec.ts` holds
+ * the two together.
+ */
+export const NEW_TAB_CUE_TEXT = " (opens in a new tab)";
+/**
+ * The cue for a native anchor, as its last child. Pagefind indexes raw HTML, so
+ * `data-pagefind-ignore` keeps the words out of search content and excerpts.
+ * Output without `NEW_TAB_CUE_CSS` would show the words, so only published pages
+ * may carry it.
+ */
+export const NEW_TAB_CUE_HTML = `<span class="sr-only" data-pagefind-ignore>${NEW_TAB_CUE_TEXT}</span>`;
+/** Hides the cue from sight only. The page shell and each shadow stylesheet with a cued anchor carry it. */
+export const NEW_TAB_CUE_CSS = ".sr-only{position:absolute;width:0.0625rem;height:0.0625rem;padding:0;margin:-0.0625rem;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}";
+/** Rendered HTML without its cues, for code that reads a link's text back. */
+export function withoutNewTabCue(html) {
+    return html.split(NEW_TAB_CUE_HTML).join("");
+}

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

@@ -1,5 +1,16 @@
 {
-  "version": 14,
+  "version": 16,
+
+  "imageDescription": {
+    "fields": {
+      "descriptionMode": { "kind": "mode", "storage": "persisted" },
+      "defaultDescription": { "kind": "text", "storage": "hydratedReadOnly" },
+      "descriptionRevision": { "kind": "revision", "storage": "hydratedReadOnly" }
+    },
+    "modes": ["inherit", "custom", "decorative"],
+    "maxDefaultDescriptionScalars": 1000,
+    "maxRevision": "9223372036854775807"
+  },
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -84,7 +95,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,
@@ -124,7 +138,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,
@@ -237,7 +254,10 @@
             "optionalKeys": [
               "width",
               "height",
-              "alt"
+              "alt",
+              "descriptionMode",
+              "defaultDescription",
+              "descriptionRevision"
             ],
             "urls": {
               "minItems": 1,
@@ -297,6 +317,12 @@
             "minimum": 10,
             "maximum": 100
           },
+          "blockSizePercent": {
+            "type": "integer",
+            "required": false,
+            "minimum": 10,
+            "maximum": 200
+          },
           "opacity": {
             "type": "number",
             "required": false,

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

@@ -1,4 +1,5 @@
 import registry from "./free-form-section-registry.json" with { type: "json" };
+import { imageDescriptionIssues, pickImageDescriptionFields } from "./image-description-validation.js";
 
 import {
   CONTENT_ERROR_CODES as CODES,
@@ -45,6 +46,12 @@ function decorationDeliveryUrlIsSafe(value) {
   }
 }
 
+function validateImageDescription(image, path, label, report) {
+  for (const issue of imageDescriptionIssues(image)) {
+    report(`${path}/${issue.field}`, CODES.attrInvalid, `${label} ${issue.field} must ${issue.expected}.`);
+  }
+}
+
 function normalizeProcessedSectionImage(value, definition, path, label, report) {
   let valid = true;
   const reject = (errorPath, code, message) => {
@@ -170,6 +177,7 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
     reject(`${path}/alt`, CODES.attrInvalid, `${label} alt must be a string.`);
   }
 
+  validateImageDescription(value, path, label, reject);
   if (!valid) return undefined;
   return Object.freeze({
     imageId: value.imageId,
@@ -182,6 +190,7 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
     ...(Object.hasOwn(value, "width") ? { width: value.width } : {}),
     ...(Object.hasOwn(value, "height") ? { height: value.height } : {}),
     ...(Object.hasOwn(value, "alt") ? { alt: value.alt } : {}),
+    ...pickImageDescriptionFields(value),
   });
 }
 
@@ -457,10 +466,22 @@ export function normalizeFreeFormSectionDecoration(
     if (Object.hasOwn(image, "alt") && typeof image.alt !== "string") {
       report(`${imagePath}/alt`, CODES.attrInvalid, "Section decoration image alt must be a string.");
     }
+    validateImageDescription(image, imagePath, "Section decoration image", report);
+  }
+
+  // TR01329: width and height sizes are exclusive, so one conflict replaces both range checks.
+  const sizeConflict = Object.hasOwn(value, "inlineSizePercent") && Object.hasOwn(value, "blockSizePercent");
+  if (sizeConflict) {
+    report(
+      `${path}/blockSizePercent`,
+      CODES.attrInvalid,
+      "Section decoration blockSizePercent cannot be combined with inlineSizePercent. Use only one of the two sizes.",
+    );
   }
 
   for (const [name, definition] of Object.entries(fields)) {
     if (name === "image" || !Object.hasOwn(value, name)) continue;
+    if (sizeConflict && (name === "inlineSizePercent" || name === "blockSizePercent")) continue;
     const fieldPath = `${path}/${name}`;
     const entry = value[name];
     if (definition.type === "enum") {
@@ -500,10 +521,17 @@ export function normalizeFreeFormSectionDecoration(
     ...(Object.hasOwn(image, "width") ? { width: image.width } : {}),
     ...(Object.hasOwn(image, "height") ? { height: image.height } : {}),
     ...(Object.hasOwn(image, "alt") ? { alt: image.alt } : {}),
+    ...pickImageDescriptionFields(image),
   };
   const normalized = { image: Object.freeze(normalizedImage) };
   for (const [name, definition] of Object.entries(fields)) {
-    if (name !== "image") normalized[name] = value[name] ?? definition.default;
+    if (name === "image") continue;
+    // A field with no default stays absent. The width default applies only without a height size.
+    const fallback = name === "inlineSizePercent" && Object.hasOwn(value, "blockSizePercent")
+      ? undefined
+      : definition.default;
+    const resolved = value[name] ?? fallback;
+    if (resolved !== undefined) normalized[name] = resolved;
   }
   return finish(Object.freeze(normalized));
 }