@taprootio/site-authoring 0.30.0 → 0.32.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
 
@@ -916,6 +972,25 @@ targets are refused (`content.link_rel`, `content.link_target`). The editor's
 old default, `noopener noreferrer nofollow`, reads as no choice. See
 `taproot-site help page free-form`.
 
+### External links open in a new tab in 0.32.0
+
+A link to another site opens in a new tab with nothing to set. On the next
+render of a page, every absolute `http:` or `https:` address whose host is not
+one of the site's own hosts publishes `target="_blank"` with `noopener
+noreferrer` added after any `rel` tokens the link already carries. This covers
+link marks in page text and tables, and component links: feature-grid,
+image-row, card-grid, product-grid, hero-section, cta, image-banner and
+social-links, plus the footer and header navigation. Each of these links also
+says "(opens in a new tab)" to a screen reader, with no change on screen.
+`mailto:`, `tel:`, relative paths, fragments,
+queries and the site's own addresses stay in the same tab. A subdomain of the
+site is another host, so it opens in a new tab; `www.` is ignored. To keep a
+link mark in the same tab, write `target="_self"` after it in Markdown or set
+`attrs.target` to `"_self"` in `.pm.json`. Component links have no setting for
+this. Existing pages change when a publish renders the whole site, such as a
+settings or navigation change; pages an incremental publish copies forward keep
+their old links until then.
+
 ### What changed between releases
 
 Taproot accepts only the latest CLI, so an upgrade can be forced at any time.

package/examples/riverbend-wellness/settings/taproot-styles.json

@@ -524,6 +524,7 @@
       "viewportMin": 320
     },
     "defaultScheme": "system",
+    "blockSpacing": "standard",
     "lightLogoId": "a0000000-0000-4000-8000-0000000000a0",
     "darkLogoId": "a0000000-0000-4000-8000-0000000000a1",
     "lightCanvasImageId": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.30.0",
+  "version": "0.32.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.9.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/appearance-contract.js

@@ -1,3 +1,4 @@
+import { BLOCK_SPACINGS, DEFAULT_BLOCK_SPACING } from "./block-flow.js";
 import { hasControlCharacter, isCanonicalUuid, SiteAuthoringError } from "./errors.js";
 import {
   SETTINGS_TYPE_BRAND,
@@ -26,6 +27,16 @@ export const APPEARANCE_SCALAR_FIELDS = Object.freeze([
     values: Object.freeze(["system", "light", "dark"]),
     default: "light",
   }),
+  // The names come from the synced block-flow rules, so a spacing the page
+  // has no scale for can never pass validation (TR01328).
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+    name: "blockSpacing",
+    path: "taproot-styles.blockSpacing",
+    type: "enum",
+    values: Object.freeze(Object.keys(BLOCK_SPACINGS)),
+    default: DEFAULT_BLOCK_SPACING,
+  }),
   ...["lightLogoId", "darkLogoId", "lightCanvasImageId", "darkCanvasImageId"].map((name) =>
     Object.freeze({
       settingsType: SETTINGS_TYPE_TAPROOT_STYLES,

package/src/block-flow.js

@@ -0,0 +1,117 @@
+// Generated from shared/block-flow.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * The one owner of how page blocks space themselves (TR01328): the three
+ * site-wide spacing choices and the stylesheet that turns them into margins.
+ *
+ * Text used to get its space from a browser default and components got none.
+ * Now every direct child of a flow container takes one gap, a token that
+ * follows the site's text size and the chosen spacing. The published page
+ * shell inlines `BLOCK_FLOW_CSS` in its core section and the editor's page
+ * preview, which has no shell, applies the same string, so both agree.
+ *
+ * The generator and the site-authoring CLI cannot import a repo-root file, so
+ * `node scripts/sync-field-validation.mjs` writes their copies; edit only this
+ * file and re-run it. The editor imports it by relative path.
+ */
+/** The scale each choice puts on the gap and on a heading's top margin. */
+export const BLOCK_SPACINGS = {
+    compact: 0.75,
+    standard: 1,
+    roomy: 1.5,
+};
+/** What a site that never chose gets; it is also the value the page leaves unwritten. */
+export const DEFAULT_BLOCK_SPACING = "standard";
+// A flow container holds a page's blocks as direct children. This is the
+// shell's older list with `.taproot-free-form` swapped for the section
+// content: the free-form element's own children are sections and root bands,
+// which must not gain a margin.
+const FLOW_CONTAINERS = [
+    "[data-section-content]",
+    "[slot=\"body\"]",
+    "[slot=\"introduction\"]",
+    ".recipe-story",
+    ".taproot-legal__body",
+].join(", ");
+// The end room needs only the text elements whose bottom margin is 0; the
+// unpadded edge leaves text, lists and rules alone, as they are today.
+const TEXT_AND_LISTS = "p, h1, h2, h3, h4, h5, h6, figure, blockquote, dl, ul, ol, pre, hr";
+const TEXT_WITHOUT_END_MARGIN = "p, h1, h2, h3, h4, h5, h6, figure, blockquote, dl";
+const SCALE_MAPPING = Object.entries(BLOCK_SPACINGS)
+    .map(([name, scale]) => `[data-block-spacing="${name}"] {\n  --taproot-block-scale: ${scale};\n}`)
+    .join("\n");
+/**
+ * The block flow rules, compact enough to inline in every page. No CSS comments
+ * ship, so each rule's reason is here:
+ *
+ * - The gap is a token, not em, so a heading and a paragraph resolve the same
+ *   length and it stays fluid on phones. The 1em fallback holds the browser's
+ *   text margin when the runtime never ran and set `--esp-type-normal`.
+ * - The block rule and its text reset have zero specificity (`:where()`), so any
+ *   rule a component, a banner or an author writes for its own margin wins with
+ *   no ordering fight. The reset repeats `esp-reset.css` because the page preview
+ *   has no reset.
+ * - Components load lazily and an undefined element is inline, where a vertical
+ *   margin does nothing, so the listed hosts match their `:host` from first paint.
+ *   Add every new lazily loaded component host to that list.
+ * - A heading's top margin scales with the setting. At (0,1,0) it beats Espalier's
+ *   root heading rule and loses to the banner resets, in any section order.
+ * - A spacer adds its height to the gap instead of a second margin.
+ * - The last text block of a padded section gets room, so a section closes as it
+ *   opens. The descendant combinator reaches past a surface's `esp-box`.
+ * - An unpadded section's first and last component stay flush. Text, lists, rules
+ *   and anything with a margin rule of its own keep what they have.
+ * - Banners stay flush with their neighbors. Those rules live here, not in the
+ *   banner section, because the page preview has no shell.
+ */
+export const BLOCK_FLOW_CSS = `
+:where(${FLOW_CONTAINERS}) {
+  --taproot-block-gap: calc(var(--esp-type-normal, 1em) * var(--taproot-block-scale, 1));
+}
+${SCALE_MAPPING}
+:where(${FLOW_CONTAINERS}) > * {
+  margin-block: var(--taproot-block-gap);
+}
+:where(${FLOW_CONTAINERS}) > :where(p, h1, h2, h3, h4, figure, blockquote, dl) {
+  margin-block-end: 0;
+}
+taproot-hero,
+taproot-cta,
+taproot-testimonial,
+taproot-feature-grid,
+taproot-latest-posts,
+taproot-card-grid,
+taproot-product-grid {
+  display: block;
+}
+:is(${FLOW_CONTAINERS}) > :where(h1, h2, h3, h4, h5) {
+  margin-block-start: calc(var(--esp-size-small-to-normal, 0.83em) * var(--taproot-block-scale, 1));
+}
+:where(${FLOW_CONTAINERS}) > taproot-spacer {
+  margin-block: 0;
+}
+esp-section[data-content-padding="standard"] [data-section-content] > :is(${TEXT_WITHOUT_END_MARGIN}):last-child {
+  margin-block-end: var(--taproot-block-gap);
+}
+:where(esp-section[data-content-padding="none"] [data-section-content]) > :where(:first-child:not(${TEXT_AND_LISTS})) {
+  margin-block-start: 0;
+}
+:where(esp-section[data-content-padding="none"] [data-section-content]) > :where(:last-child:not(${TEXT_AND_LISTS})) {
+  margin-block-end: 0;
+}
+:is(${FLOW_CONTAINERS}) taproot-image-banner {
+  margin: 0;
+}
+:is(${FLOW_CONTAINERS}) esp-image[banner] {
+  margin: 0;
+}
+:is(${FLOW_CONTAINERS}) *:has(+ taproot-image-banner) {
+  margin-block-end: 0;
+}
+:is(${FLOW_CONTAINERS}) taproot-image-banner + * {
+  margin-block-start: 0;
+}
+[data-taproot-section][data-following-spacing="compact"] > [data-section-content] > :first-child,
+[data-taproot-section][data-following-spacing="compact"] > esp-box > [data-section-content] > :first-child {
+  margin-block-start: 0;
+}
+`.trim();

package/src/changelog.json

@@ -1,5 +1,50 @@
 {
   "entries": [
+    {
+      "version": "0.32.0",
+      "note": "Links to other sites open in a new tab on published pages with nothing to set; target=\"_self\" keeps a link mark in the same tab; page blocks get real default spacing with a site-wide setting.",
+      "behavior": [
+        "An absolute http or https link to a host other than the site's own now publishes target=\"_blank\" and rel with noopener noreferrer added, with nothing to set. This covers link marks in page text and tables, inline facts, and the links of feature-grid, image-row, card-grid, product-grid, hero-section, cta, image-banner and social-links components, and the footer. mailto and tel links, relative paths, fragments, queries and the site's own addresses (including www.) stay in the same tab; a subdomain counts as another host. Component links have no setting to keep them in the tab.",
+        "A link mark keeps its own choice: target=\"_blank\" opens a new tab for any link, and target=\"_self\" keeps even an external link in the same tab. In Markdown write {target=\"_self\"} after the link; in .pm.json set attrs.target to \"_self\". A mark with a null target, or with the editor's old default rel, follows the default. See help page free-form.",
+        "Header navigation follows the same rule: an item or linked group with an http or https address on another host opens in a new tab. mailto and tel items, page items and the site's own addresses stay in the same tab.",
+        "A link that opens a new tab now says \"(opens in a new tab)\" to a screen reader, with no change on screen. This covers component links, link marks, navigation and the footer.",
+        "Help for component links and the image-row and product-grid notes no longer say links open in the same tab.",
+        "Existing pages change at the site's next whole-site render, such as a settings or navigation change. Pages an incremental publish copies forward keep their old links until then.",
+        "Page blocks get real default spacing. Text, tables and every component sit one gap apart, where components used to have no space from the text before them; the last text block of a padded section gets the same gap as room before the section ends; a heading's top margin scales with it. Banners stay flush with their neighbors.",
+        "New required setting blockSpacing in settings/taproot-styles.json (Brand & style > Block spacing): compact, standard or roomy scales the gap to 0.75, 1 or 1.5 times, in both color schemes. Standard keeps text where it is today.",
+        "spacer blocks add their height to the new gap instead of replacing it, so review hand-placed spacers and remove the ones that only worked around tight spacing.",
+        "blockSpacing is required on theme push like every other appearance field. A workspace pulled before this version does not hold it: run pull again before theme push, or add \"blockSpacing\": \"standard\" to settings/taproot-styles.json.",
+        "A site shows the new spacing after its next whole-site render, such as a settings or navigation change. Pages an incremental publish copies forward keep their old spacing until then.",
+        "A section decoration can be sized by height. Set blockSizePercent (an integer from 10 to 200) for \"auto N%\" in place of inlineSizePercent; the two cannot be combined, and neither set keeps the width default of 40. See help page free-form.",
+        "The help reference version is 51."
+      ],
+      "help": [
+        "page",
+        "components",
+        "component",
+        "settings",
+        "appearance"
+      ]
+    },
+    {
+      "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.",