@taprootio/site-authoring 0.31.0 → 0.32.0

package/README.md

@@ -972,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.31.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.8.0",
+    "@taprootio/espalier": "6.9.0",
     "mediabunny": "1.61.1"
   },
   "scripts": {

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,31 @@
 {
   "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.",

package/src/content/components.js

@@ -708,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(
@@ -911,7 +917,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       "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: [
@@ -950,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.",
@@ -995,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: [
@@ -1071,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 {
@@ -1079,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)}.` };

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,5 @@
 {
-  "version": 15,
+  "version": 16,
 
   "imageDescription": {
     "fields": {
@@ -317,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

@@ -469,8 +469,19 @@ export function normalizeFreeFormSectionDecoration(
     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") {
@@ -514,7 +525,13 @@ export function normalizeFreeFormSectionDecoration(
   };
   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));
 }

package/src/content/tiptap-prosemirror.ts

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

package/src/presentation-reference.js

@@ -520,6 +520,14 @@ export function getAppearanceReference() {
       + "so full-bleed designs usually pair headerWidth 'wide' with headerLayout 'centered-menu', which keeps the "
       + "brand left, the buttons right, and the navigation centered. validate prints a hint, never a failure, when a "
       + "root-band page ships with a contained header.",
+    blockSpacingContract:
+      "Blocks on a page space themselves: text, tables and components all sit one gap apart, and the gap follows the "
+      + "site's text size. blockSpacing scales it for the whole site in both color schemes: 'standard' keeps the gap "
+      + "equal to the text spacing, 'compact' is three quarters of it and 'roomy' is one and a half times it. "
+      + "A heading's top margin scales the same way. The last text block in a padded section gets the gap as extra "
+      + "room before the section ends, and an image banner stays flush with its neighbors. A spacer block adds its "
+      + "own height to the gap, so review spacers placed by hand. A site shows the change after its next whole-site "
+      + "render.",
     menuContract:
       "navDrawerStyle 'full-screen' (the published default) opens the mobile menu over the whole viewport with the "
       + "brand centered above large centered items and navDrawerTransition choosing how it appears (fade, slide-down, "
@@ -841,6 +849,7 @@ export function formatPresentationReference(reference) {
       + "\nLogo contrast: " + reference.logoContrastContract
       + "\nFavicon: " + reference.faviconContract
       + "\nHeader width: " + reference.headerWidthContract
+      + "\nBlock spacing: " + reference.blockSpacingContract
       + "\nMobile menu and menu font: " + reference.menuContract
       + "\nFooter: " + reference.footerBoundary
       + "\nFooter content guard: " + reference.footerContentGuard + "\n\nAtomic change set (one transaction):\n"

package/src/reference-help.js

@@ -95,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 50;
+export const REFERENCE_VERSION = 51;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -695,7 +695,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "PAGE uses resourceId from .taproot-site-manifest.json, never pageId or path.",
       "EXTERNAL_URL uses externalUrl; GROUP_HEADER has no target; every kind may carry children.",
       "externalUrl is an absolute credential-free http/https URL, or a mailto:/tel: contact URL such as "
-      + "tel:+15555550123, published exactly as authored.",
+      + "tel:+15555550123, published exactly as authored. An http or https address on another host opens in a new tab, "
+      + "and the link says so to a screen reader.",
     ]),
     example: Object.freeze({
       siteId: "<site-uuid>",
@@ -1409,6 +1410,8 @@ function decorationReference() {
     }\n## Rooted in warmth\n\nMove with confidence.\n:::`,
     maskGuidance:
       "Use a transparent PNG or WebP whose alpha channel contains only the mark. The active section context supplies the tint in both schemes.",
+    sizeGuidance:
+      "Set inlineSizePercent to size the art by the section's width, or blockSizePercent to size it by the section's height. The two cannot be combined.",
     opaqueWarning:
       "An opaque rectangle uses its whole alpha channel and will render as a tinted rectangle, not as a cut-out mark.",
   });
@@ -1453,7 +1456,7 @@ function inlineFactsReference() {
       + "mix labelled and standalone facts. An empty string is rejected, so omitting a label stays explicit. "
       + "Unicode spaces, tabs, and LF/CRLF line breaks are allowed; other C0/C1 controls, U+2028/U+2029, U+FEFF, and literal <br> tags are rejected. The label follows the value in reading order and is outside its link.",
     urlPolicy:
-      "Optional safe HTTP(S), mailto, tel, non-protocol-relative root, fragment, query, or relative URL. Empty/whitespace-only values, other schemes, backslashes, and ASCII controls are rejected; tel: remains a native link. Contact URLs require a body and refuse tel:// and mailto:// authority forms or control characters, consistently with navigation and footer links.",
+      "Optional safe HTTP(S), mailto, tel, non-protocol-relative root, fragment, query, or relative URL. Empty/whitespace-only values, other schemes, backslashes, and ASCII controls are rejected; tel: remains a native link. Contact URLs require a body and refuse tel:// and mailto:// authority forms or control characters, consistently with navigation and footer links. An absolute http(s) address on another site opens in a new tab with nothing to set; the site's own addresses and all other values keep the same tab.",
     markdown: Object.freeze({
       fence: INLINE_FACTS_DEFINITION.markdown.fence,
       body: INLINE_FACTS_DEFINITION.markdown.body,
@@ -1819,10 +1822,10 @@ const FREE_FORM_REFERENCE = Object.freeze({
         + "choice is per link, internal links included.",
       markdownRule:
         'Write {rel="…" target="…"} directly after the link\'s closing parenthesis: either attribute alone or both, '
-        + 'each double-quoted once. rel is space-separated; target="_blank" opens a new tab.',
+        + 'each double-quoted once. rel is space-separated; an external web address opens in a new tab on its own, target="_blank" opens a new tab for any link, and target="_self" keeps a link in the same tab.',
       pmJson:
         'In .pm.json, a link mark carries attrs.rel (a space-separated string, or null) and attrs.target ("_blank" '
-        + 'opens a new tab and publishes with noopener noreferrer added, "_self" or null keeps the same tab).',
+        + 'opens a new tab and publishes with noopener noreferrer added, "_self" keeps the same tab, and null leaves it to the default: an absolute http(s) link to another site opens in a new tab, and any other link keeps the same tab).',
       refusals:
         `Any other rel token, opener included, is refused (${CONTENT_ERROR_CODES.linkRel}); so is another target `
         + `(${CONTENT_ERROR_CODES.linkTarget}). The editor's old default, "noopener noreferrer nofollow", reads as no choice.`,
@@ -2039,9 +2042,15 @@ function formatRegistryField(field, indent = "  ") {
     : `; ${field.minScalars} through ${field.maxScalars} Unicode scalar values${
       field.nonWhitespace ? "; non-whitespace" : ""
     }`;
+  // TR01329: a field with no default key is absent until an author sets it.
+  const requirement = field.required
+    ? "required"
+    : Object.hasOwn(field, "default")
+    ? `default ${JSON.stringify(field.default)}`
+    : "optional; no default";
   const line = `${indent}${field.name.padEnd(Math.max(1, 20 - indent.length))} ${type}${
     field.nullable ? " | null" : ""
-  }; ${field.required ? "required" : `default ${JSON.stringify(field.default)}`}${bounds}${itemBounds}${scalarBounds}`;
+  }; ${requirement}${bounds}${itemBounds}${scalarBounds}`;
   return [line, ...(field.fields ?? []).map((child) => formatRegistryField(child, `${indent}  `))].join("\n");
 }
 
@@ -2128,7 +2137,7 @@ export function formatReferenceResult(result) {
       }\n  delivery URLs         ${page.sections.decoration.deliveryUrlPolicy}\n\nTint mapping:\n${
         Object.entries(page.sections.decoration.tintTokens).map(([name, token]) => `  ${name.padEnd(20)} ${token}`)
           .join("\n")
-      }\n\nTransparent-mask example:\n${page.sections.decoration.markdownExample}\n\nMask guidance: ${page.sections.decoration.maskGuidance}\nWarning: ${page.sections.decoration.opaqueWarning}\n\nRoot defaults and placement:\n${
+      }\n\nTransparent-mask example:\n${page.sections.decoration.markdownExample}\n\nMask guidance: ${page.sections.decoration.maskGuidance}\nSize guidance: ${page.sections.decoration.sizeGuidance}\nWarning: ${page.sections.decoration.opaqueWarning}\n\nRoot defaults and placement:\n${
         page.sections.placementMatrix.map(formatPlacement).join("\n")
       }\n\nSemantic tables:\n  placement             document root or directly inside a top-level section; wide/full-well measure\n  rows                  exactly ${page.tables.structure.headerRows} header row, then ${page.tables.limits.dataRows.min} through ${page.tables.limits.dataRows.max} data rows\n  columns               ${page.tables.limits.columns.min} through ${page.tables.limits.columns.max}; delimiter and every row must match the header width\n  caption               optional non-empty plain text; maximum ${page.tables.limits.captionScalars.max} Unicode scalar values; syntax ${page.tables.markdown.captionSyntax}\n  caption guidance      ${page.tables.captionGuidance}\n  cells                 exactly ${page.tables.structure.paragraphChildrenPerCell} paragraph; headers need non-whitespace text; data cells may be empty; maximum ${page.tables.limits.cellTextScalars.max} text scalars\n  inline                ${
         page.tables.structure.inlineNodes.join(", ")

package/src/setting-reference.js

@@ -83,6 +83,15 @@ const TAPROOT_STYLES_ENTRIES = {
     "The color scheme a first-time visitor sees: light, dark, or system to follow the visitor's device.",
     "The starting scheme of every published page. A visitor who uses the theme toggle keeps their own choice.",
   ),
+  blockSpacing: entry(
+    `${BRAND} > Block spacing`,
+    "The space between blocks on every page: compact, standard or roomy. Standard keeps the gap equal to the text "
+      + "spacing; compact scales it to three quarters and roomy to one and a half times. Spacer blocks add their "
+      + "height on top.",
+    "Both color schemes, on every published page. A site shows the change after its next whole-site render, which "
+      + "happens when any settings group or navigation is selected for a stage or deploy. Pages copied forward from "
+      + "an earlier deploy keep their old spacing until then.",
+  ),
   lightLogoId: entry(
     `${BRAND} > Logo`,
     "The site-owned image used as the brand logo in the light scheme.",

package/src/settings-catalog.js

@@ -58,6 +58,7 @@ export const SETTINGS_GROUPS = Object.freeze([
       { name: "darkTheme", wireType: "theme" },
       ...stringFields(
         "defaultScheme",
+        "blockSpacing",
         "lightLogoId",
         "lightLogoUrl",
         "darkLogoId",