@taprootio/site-authoring 0.14.0 → 0.15.0

package/src/content/components.js

@@ -258,6 +258,10 @@ const IMAGE_BANNER = Object.freeze({
   image: image(),
   altText: str(),
   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).
+  supportingText: boundedStr(280),
+  action: Object.freeze({ ...HERO_ACTION, nullable: true }),
   fontSize: enumOf("large", "standard", "small"),
   focus: shape({
     x: num({ minimum: 0, maximum: 1 }),
@@ -268,7 +272,20 @@ const IMAGE_BANNER = Object.freeze({
   // `ratio` keeps the wide/compact shape, capped at the viewport space below
   // the site header; `viewport` fills exactly that space (TR00413).
   heightMode: enumOf("ratio", "viewport"),
-  contentPosition: enumOf("bottom-start", "bottom", "bottom-end", "center", "top-start", "top", "top-end"),
+  contentPosition: enumOf(
+    "bottom-start",
+    "bottom",
+    "bottom-end",
+    "center",
+    "top-start",
+    "top",
+    "top-end",
+    "middle-start",
+    "middle-end",
+  ),
+  // Below the compact width the copy stays over the image, or moves into a
+  // band under it when the narrow crop has no quiet region.
+  compactPlacement: enumOf("overlay", "below"),
   contentGutter: enumOf("frame", "page"),
   followingSpacing: enumOf("standard", "compact"),
   scrim: enumOf("auto", "none", "flat", "top", "bottom", "left", "right", "radial"),
@@ -574,12 +591,15 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       image: null,
       altText: "",
       overlayText: "",
+      supportingText: "",
+      action: null,
       fontSize: "large",
       focus: { x: 0.5, y: 0.5 },
       ratio: "3/1",
       compactRatio: "3/2",
       heightMode: "ratio",
       contentPosition: "center",
+      compactPlacement: "overlay",
       contentGutter: "frame",
       followingSpacing: "standard",
       scrim: "auto",
@@ -597,8 +617,10 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       "For a full-bleed photograph with text aligned to the surrounding page well, set contentGutter to page. followingSpacing: compact reduces the top padding of an immediately following section so a bottom banner heading reads with its supporting paragraph. Use a banner-only contentPadding: none section followed by a standard text section; keep their theme contexts consistent. Defaults preserve frame-edge text and standard section spacing.",
       "scrimEdge: flush finishes a directional scrim at full strength where it meets the page, so a full-bleed banner dissolves into the band below instead of ending at a visible line. It requires the arrangement above: a banner-only contentPadding: none section immediately followed by a section in the same theme context. It is inert when scrim is none, flat, or radial, and it stops being seamless when bannerScheme pins a polarity the page scheme does not share, because the scrim ink is then a derived color rather than the adjoining band's own. Default none; add it deliberately, per banner.",
       "Compose around the actual photograph: identify the meaningful subject and a quiet area for copy. Do not cover faces, product details, or high-detail edges. A focal point controls cropping, not text placement; inspect wide and compact crops separately. Keep the subject's face, ears, and other identifying details inside the compact frame, including at both ends of parallax travel. Adjust focus toward the subject rather than reusing a generic center; reduce motion or choose a roomier crop if preserving the subject requires it.",
-      "Use contentPosition to place copy in that quiet area, not automatically in the center. Keep one dominant message and nearby supporting copy/actions; if the photo has no safe text area, use a split hero or a separate text section instead of forcing an overlay.",
-      "Use the rule of thirds as a composition guide: consider the subject near one third and a compact text group in quiet space on the opposite side. Golden-ratio proportions are optional alternatives, not a proven engagement formula. Neither guide overrides legibility, the actual subject, or the compact crop. Current contentPosition values are edge/center anchors, not exact third or golden-ratio coordinates; do not invent unsupported positioning properties.",
+      "Use contentPosition to place copy in that quiet area, not automatically in the center: top, middle and bottom rows, each at start, center or end (middle-start and middle-end sit at mid-height against an edge; start and end mirror for right-to-left text). Keep one dominant message; if the photo has no safe text area, use a split hero or a separate text section instead of forcing an overlay.",
+      "The copy is a stack: overlayText is the headline, supportingText one optional supporting sentence (280 characters at most) set in the lead type, and action at most one link ({ label, url } with a safe URL, or null). The stack keeps its own spacing and a bounded line length, so long copy does not run the width of a wide banner, and the link is a real keyboard-reachable link with a visible focus ring. A headline alone lays out as before.",
+      "compactPlacement: below moves the copy into a band under the image at compact widths, on the banner scheme's own surface, for a crop that keeps its subject but loses the quiet region the copy sat on. Default overlay keeps the copy over the image. The banner grows instead of clipping when enlarged text or long labels need the room, past the height left below the site header if it must, and returns to its shape once the copy fits.",
+      "Use the rule of thirds as a composition guide: consider the subject near one third and a compact text group in quiet space on the opposite side. Golden-ratio proportions are optional alternatives, not a proven engagement formula. Neither guide overrides legibility, the actual subject, or the compact crop. contentPosition values are edge, middle and center anchors, not exact third or golden-ratio coordinates; do not invent unsupported positioning properties.",
       "Check contrast behind the actual letters at both motion endpoints and both themes: WCAG AA requires 4.5:1 for ordinary text and 3:1 for qualifying large text. A text shadow alone is not a contrast guarantee. Keep text and actions stationary; recheck at mobile widths and enlarged text.",
       "Prefer parallax-subtle or parallax when motion is useful: motion follows the reader's scrolling and stops when they stop. Infinite ambient loops are an explicit art-direction choice, not the default recommendation.",
       "imageMotion is optional and defaults to none. slow-zoom is a cinematic 18% zoom over 6 seconds, alternating; drift-start and drift-end travel horizontally over 8 seconds with a 14% safety crop.",
@@ -610,9 +632,12 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       image: null,
       altText: "",
       overlayText: "Train together",
+      supportingText: "Small classes, every morning, for every level.",
+      action: { label: "See the schedule", url: "/classes" },
       focus: { x: 0.5, y: 0.35 },
       heightMode: "ratio",
-      contentPosition: "bottom-start",
+      contentPosition: "middle-start",
+      compactPlacement: "below",
       scrim: "bottom",
       scrimStrength: "medium",
       texture: "paper",
@@ -681,6 +706,35 @@ export const COMPONENT_SHAPES = Object.freeze(Object.fromEntries(
   Object.entries(COMPONENT_DEFINITIONS).map(([type, definition]) => [type, definition.fields]),
 ));
 
+/**
+ * Replaces each image field in parsed component data with
+ * `mapImage(value, path)`, following the component's field table. Markdown
+ * authoring turns media paths into stored image records this way, and help
+ * builds its Markdown examples the other way (TR01187). A value of the wrong
+ * shape is passed through for validation to report.
+ */
+export function mapComponentImages(componentType, data, mapImage) {
+  const fields = COMPONENT_SHAPES[componentType];
+  return fields !== undefined && isPlainObject(data) ? mapImageFields(fields, data, "", mapImage) : data;
+}
+
+function mapImageFields(fields, value, path, mapImage) {
+  const mapped = { ...value };
+  for (const [name, spec] of Object.entries(fields)) {
+    if (Object.hasOwn(value, name)) mapped[name] = mapImageValue(spec, value[name], `${path}/${name}`, mapImage);
+  }
+  return mapped;
+}
+
+function mapImageValue(spec, value, path, mapImage) {
+  if (spec.kind === "image") return mapImage(value, path);
+  if (spec.kind === "object" && isPlainObject(value)) return mapImageFields(spec.fields, value, path, mapImage);
+  if (spec.kind === "array" && Array.isArray(value)) {
+    return value.map((item, index) => mapImageValue(spec.item, item, `${path}/${index}`, mapImage));
+  }
+  return value;
+}
+
 export function getComponentDefinition(componentType) {
   return typeof componentType === "string" && Object.hasOwn(COMPONENT_DEFINITIONS, componentType)
     ? COMPONENT_DEFINITIONS[componentType]
@@ -749,8 +803,12 @@ function referenceSchema(spec) {
     case "image":
       return {
         type: ["object", "null"],
+        // What a Markdown component fence takes instead (TR01187).
+        markdownType: ["string", "null"],
         description:
-          "null, or a media-upload result. Keep imageId, src, and urls keys so the server can rewrite delivery URLs.",
+          "In Markdown, a media path recorded by media upload (such as \"media/photo.webp\"), 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.",
         additionalProperties: false,
         properties: referenceProperties(COMPONENT_IMAGE_FIELDS),
       };
@@ -805,7 +863,7 @@ function describe(spec) {
     case "object":
       return "an object";
     case "image":
-      return "an image object or null";
+      return "a media path in Markdown, an image object in .pm.json, or null";
     case "uuid":
       return "a canonical lowercase UUID";
     case "safe-url":

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

@@ -18,6 +18,16 @@ function deepFreeze(value) {
 
 export const FREE_FORM_SECTION_REGISTRY = deepFreeze(registry);
 
+/**
+ * An image converted from a Markdown media path carries `"src": ""` and
+ * `"urls": []`, like body and component images: the API fills both from the
+ * image id at read time (TR01187). Only that exact pair is unfilled; any other
+ * empty value is still refused.
+ */
+function isUnfilledDelivery(image) {
+  return image.src === "" && Array.isArray(image.urls) && image.urls.length === 0;
+}
+
 function decorationDeliveryUrlIsSafe(value) {
   if (typeof value !== "string" || value === "" || /[\u0000-\u0020\u007f]/u.test(value) || value.includes("\\")) {
     return false;
@@ -70,10 +80,11 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
   if (Object.hasOwn(value, "imageId") && !isUuid(value.imageId)) {
     reject(`${path}/imageId`, CODES.attrInvalid, `${label} imageId must be a canonical lowercase UUID.`);
   }
+  const unfilled = isUnfilledDelivery(value);
   if (Object.hasOwn(value, "src")) {
     if (typeof value.src !== "string") {
       reject(`${path}/src`, CODES.attrInvalid, `${label} src must be a string.`);
-    } else if (!decorationDeliveryUrlIsSafe(value.src)) {
+    } else if (!unfilled && !decorationDeliveryUrlIsSafe(value.src)) {
       reject(
         `${path}/src`,
         value.src === "" ? CODES.imageKeys : CODES.attrInvalid,
@@ -88,7 +99,7 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
     if (!Array.isArray(value.urls)) {
       reject(`${path}/urls`, CODES.attrInvalid, `${label} urls must be an array.`);
     } else {
-      if (value.urls.length < definition.urls.minItems || value.urls.length > definition.urls.maxItems) {
+      if (!unfilled && (value.urls.length < definition.urls.minItems || value.urls.length > definition.urls.maxItems)) {
         reject(
           `${path}/urls`,
           CODES.attrInvalid,
@@ -138,6 +149,7 @@ function normalizeProcessedSectionImage(value, definition, path, label, report)
       }
       if (
         definition.srcMustMatchUrls
+        && !unfilled
         && typeof value.src === "string"
         && !value.urls.some((option) => isPlainObject(option) && option.url === value.src)
       ) {
@@ -354,10 +366,11 @@ export function normalizeFreeFormSectionDecoration(
       report(`${imagePath}/imageId`, CODES.attrInvalid, "Section decoration imageId must be a canonical lowercase UUID.");
     }
 
+    const unfilled = isUnfilledDelivery(image);
     if (Object.hasOwn(image, "src")) {
       if (typeof image.src !== "string") {
         report(`${imagePath}/src`, CODES.attrInvalid, "Section decoration image src must be a string.");
-      } else if (!decorationDeliveryUrlIsSafe(image.src)) {
+      } else if (!unfilled && !decorationDeliveryUrlIsSafe(image.src)) {
         report(
           `${imagePath}/src`,
           image.src === "" ? CODES.imageKeys : CODES.attrInvalid,
@@ -372,7 +385,10 @@ export function normalizeFreeFormSectionDecoration(
       if (!Array.isArray(image.urls)) {
         report(`${imagePath}/urls`, CODES.attrInvalid, "Section decoration image urls must be an array.");
       } else {
-        if (image.urls.length < imageDefinition.urls.minItems || image.urls.length > imageDefinition.urls.maxItems) {
+        if (
+          !unfilled
+          && (image.urls.length < imageDefinition.urls.minItems || image.urls.length > imageDefinition.urls.maxItems)
+        ) {
           report(
             `${imagePath}/urls`,
             CODES.attrInvalid,
@@ -421,6 +437,7 @@ export function normalizeFreeFormSectionDecoration(
         }
         if (
           imageDefinition.srcMustMatchUrls
+          && !unfilled
           && typeof image.src === "string"
           && !image.urls.some((option) => isPlainObject(option) && option.url === image.src)
         ) {

package/src/content/markdown.js

@@ -3,6 +3,7 @@ import {
   canonicalizeComponentData,
   expandComponentAuthoringShorthand,
   isComponentType,
+  mapComponentImages,
   validateComponentBlock,
 } from "./components.js";
 import {
@@ -20,6 +21,8 @@ import {
   isPlainObject,
   isSafeUrl,
   isUuid,
+  LINK_REL_TOKENS,
+  LINK_TARGETS,
   MARK_TYPES,
 } from "./vocabulary.js";
 
@@ -595,7 +598,7 @@ function consumeTable(lines, prelude, context) {
 // Top-level section containers
 // ---------------------------------------------------------------------------
 
-function sectionHeaderAttrs(text, line) {
+async function sectionHeaderAttrs(text, line, markdownContext) {
   const match = SECTION_HEADER_RE.exec(text);
   if (!match) {
     throw fail(
@@ -674,6 +677,21 @@ function sectionHeaderAttrs(text, line) {
     }
   }
 
+  for (const [owner, field] of [["decoration", "image"], ["background", "image"], ["background", "portraitImage"]]) {
+    if (isPlainObject(parsed[owner]) && Object.hasOwn(parsed[owner], field)) {
+      parsed[owner] = {
+        ...parsed[owner],
+        [field]: await authoredImageField(
+          parsed[owner][field],
+          `/${owner}/${field}`,
+          markdownContext,
+          line,
+          "section header",
+        ),
+      };
+    }
+  }
+
   const normalizedDecoration = normalizeFreeFormSectionDecoration(
     parsed.decoration,
     "/attrs/decoration",
@@ -709,7 +727,7 @@ function fenceClosing(delimiter) {
 
 async function consumeSection(lines, start, headerText, context, depth) {
   const line = lines[start];
-  const attrs = sectionHeaderAttrs(headerText, line);
+  const attrs = await sectionHeaderAttrs(headerText, line, context);
   const body = [];
   let index = start + 1;
   let activeFence;
@@ -773,7 +791,7 @@ function stripClosingHashes(title) {
 // Fenced blocks: code, components, and inline facts
 // ---------------------------------------------------------------------------
 
-function consumeFence(lines, start, fence, context) {
+async function consumeFence(lines, start, fence, context) {
   const [, indent, delimiter, rawInfo] = fence;
   const info = rawInfo.trim();
   const line = lines[start];
@@ -801,7 +819,10 @@ function consumeFence(lines, start, fence, context) {
   }
 
   if (info.startsWith("component:")) {
-    return { node: componentNode(info.slice("component:".length).trim(), body.join("\n"), line), next: index };
+    return {
+      node: await componentNode(info.slice("component:".length).trim(), body.join("\n"), line, context),
+      next: index,
+    };
   }
   if (info === INLINE_FACTS_CONTRACT.markdown.fence) {
     if (context.blockPlacement !== "root" && context.blockPlacement !== "section") {
@@ -865,7 +886,7 @@ function stripIndent(text, columns) {
   return text.slice(index);
 }
 
-function componentNode(componentType, body, line) {
+async function componentNode(componentType, body, line, context) {
   if (!isComponentType(componentType)) {
     throw fail(
       CODES.componentUnknown,
@@ -879,7 +900,22 @@ function componentNode(componentType, body, line) {
   if (expanded.error !== undefined) {
     throw fail(CODES.componentData, "component block", expanded.error, line.number);
   }
-  const source = expanded.source;
+  let source = expanded.source;
+  const parsed = parseJsonOrUndefined(source);
+  if (parsed !== undefined) {
+    const imageFields = [];
+    mapComponentImages(componentType, parsed, (value, path) => {
+      imageFields.push([path, value]);
+      return value;
+    });
+    if (imageFields.length > 0) {
+      const resolved = new Map();
+      for (const [path, value] of imageFields) {
+        resolved.set(path, await authoredImageField(value, path, context, line, "component block"));
+      }
+      source = JSON.stringify(mapComponentImages(componentType, parsed, (_value, path) => resolved.get(path)));
+    }
+  }
   const errors = validateComponentBlock(componentType, source, "");
   if (errors.length > 0) {
     throw fail(errors[0].code, "component block", errors[0].message, line.number);
@@ -1476,12 +1512,71 @@ function parseLink(text, index, scan, lineNumber, marks) {
     );
   }
 
+  const options = parseLinkAttributes(text, destinationEnd + 1, lineNumber);
+  const attrs = { href: destination, ...options?.attrs };
   const inner = text.slice(index + 1, textEnd);
-  const nodes = parseInline(inner, scan, lineNumber, [...marks, { type: "link", attrs: { href: destination } }]);
+  const nodes = parseInline(inner, scan, lineNumber, [...marks, { type: "link", attrs }]);
   if (nodes.length === 0) {
     throw fail(CODES.markdownLink, "link", "A link must have text.", lineNumber);
   }
-  return { nodes, end: destinationEnd + 1 };
+  return { nodes, end: options ? options.end : destinationEnd + 1 };
+}
+
+/**
+ * The optional `{rel="sponsored nofollow" target="_blank"}` right after a
+ * link's destination (TR01190), either attribute alone or both in any order.
+ * Braces that start `{rel=` or `{target=` are attributes and must be well
+ * formed; any other brace after a link stays literal text.
+ */
+function parseLinkAttributes(text, from, lineNumber) {
+  const rest = text.slice(from);
+  if (!/^\{\s*(?:rel|target)\s*=/u.test(rest)) return undefined;
+  const match = /^\{((?:\s*(?:rel|target)="[^"\\{}]*")+)\s*\}/u.exec(rest);
+  const pairs = match ? [...match[1].matchAll(/(rel|target)="([^"]*)"/gu)] : [];
+  const names = pairs.map((pair) => pair[1]);
+  if (!match || new Set(names).size !== names.length) {
+    throw fail(
+      CODES.markdownLink,
+      "link attributes",
+      'Write a link\'s attributes right after it as {rel="nofollow" target="_blank"}: each at most once, '
+        + "double-quoted. Escape a literal brace as \\{.",
+      lineNumber,
+    );
+  }
+  const attrs = {};
+  for (const [, name, value] of pairs) {
+    if (name === "target") {
+      const target = value.trim().toLowerCase();
+      if (!LINK_TARGETS.includes(target)) {
+        throw fail(
+          CODES.linkTarget,
+          "link target",
+          `A link's target is "_blank" (open in a new tab) or "_self"; "${value}" is not one.`,
+          lineNumber,
+        );
+      }
+      attrs.target = target;
+      continue;
+    }
+    const tokens = value.trim().toLowerCase().split(/\s+/u).filter(Boolean);
+    const unknown = tokens.filter((token) => !LINK_REL_TOKENS.includes(token));
+    if (tokens.length === 0 || unknown.length > 0) {
+      throw fail(
+        CODES.linkRel,
+        "link rel",
+        `A link's rel takes space-separated link types from ${LINK_REL_TOKENS.join(", ")}; ${
+          unknown.length
+            ? `${unknown.map((token) => `"${token}"`).join(", ")} ${unknown.length === 1 ? "is" : "are"} not one`
+            : "this one is empty"
+        }.`,
+        lineNumber,
+      );
+    }
+    // Vocabulary order, so a written rel can never read as the editor's old
+    // default ("noopener noreferrer nofollow"), which means no choice.
+    attrs.rel = LINK_REL_TOKENS.filter((token) => tokens.includes(token)).join(" ");
+  }
+  return { attrs, end: from + match[0].length };
 }
 
 // The same unbounded scan as `findLinkTextEnd`, and quadratic for the same
@@ -1515,19 +1610,34 @@ function unescapePunctuation(text) {
 }
 
 /**
- * Builds a `taprootImage` node from `![alt](reference)`.
- *
- * The node **always** carries `"src": ""` and `"urls": []`, whatever the
- * resolver reported for delivery URLs.
- * `PageImageDeliveryRewriter.ReplaceUrlFields` rewrites `src`/`url`/`urls`
- * only where the key already exists, filling them from the site's signed
- * delivery URLs at read time — so the key must be there and its value must not
- * be a URL this CLI invented. An image node missing the keys is rewritten into
- * nothing and renders blank; one carrying a hand-built URL renders a link the
- * site cannot sign.
+ * Builds a `taprootImage` node from `![alt](reference)`. Like every Markdown
+ * image it carries `"src": ""` and `"urls": []`; see `resolveAuthoredImage`.
  */
 async function imageNode(alt, reference, context, line) {
-  const source = unescapePunctuation(reference);
+  const resolved = await resolveAuthoredImage(unescapePunctuation(reference), context, line);
+  const attrs = {
+    imageId: resolved.imageId,
+    src: "",
+    urls: [],
+    alt: unescapePunctuation(alt) || resolved.alt,
+  };
+  if (resolved.width !== undefined) attrs.width = resolved.width;
+  if (resolved.height !== undefined) attrs.height = resolved.height;
+  return { type: "taprootImage", attrs };
+}
+
+/**
+ * The one way Markdown turns a media path into an image: body images,
+ * component image fields and section images all resolve here (TR01187).
+ *
+ * The record always carries `"src": ""` and `"urls": []`, whatever the
+ * resolver reported for delivery URLs. `PageImageDeliveryRewriter` fills them
+ * from the image id at read time, but only where the keys already exist, so
+ * they must be present and must not hold a URL this CLI invented: an image
+ * missing the keys renders blank, and a hand-built URL is one the site cannot
+ * sign. Width and height are left out when the media record does not know them.
+ */
+async function resolveAuthoredImage(source, context, line, field) {
   if (source.length > CONTENT_LIMITS.imageReferenceLength) {
     throw fail(CODES.markdownImage, "image", "The image reference is too long.", line.number);
   }
@@ -1541,7 +1651,9 @@ async function imageNode(alt, reference, context, line) {
     throw fail(
       CODES.markdownImage,
       "image",
-      `The image '${identifier(source)}' could not be resolved. Upload it with 'media upload' first.`,
+      `The image '${identifier(source)}'${field ? ` at ${field}` : ""} could not be resolved. `
+        + "Record it in .taproot-site-media.json: 'media upload' does that in a workspace, and a fixture lists it "
+        + "in its own copy.",
       line.number,
       error,
     );
@@ -1554,16 +1666,39 @@ async function imageNode(alt, reference, context, line) {
       line.number,
     );
   }
-
-  const attrs = {
+  const dimension = (value) => (Number.isSafeInteger(value) && value > 0 ? value : undefined);
+  const width = dimension(resolved.width);
+  const height = dimension(resolved.height);
+  return {
     imageId: resolved.imageId,
     src: "",
     urls: [],
-    alt: unescapePunctuation(alt) || (typeof resolved.alt === "string" ? resolved.alt : ""),
+    ...(width === undefined ? {} : { width }),
+    ...(height === undefined ? {} : { height }),
+    alt: typeof resolved.alt === "string" ? resolved.alt : "",
   };
-  if (Number.isInteger(resolved.width) && resolved.width > 0) attrs.width = resolved.width;
-  if (Number.isInteger(resolved.height) && resolved.height > 0) attrs.height = resolved.height;
-  return { type: "taprootImage", attrs };
+}
+
+/** A component or section image field in Markdown: a media path, or null. */
+async function authoredImageField(value, path, context, line, label) {
+  if (value === null) return null;
+  if (typeof value !== "string" || value === "") {
+    throw fail(
+      CODES.markdownImage,
+      label,
+      `${path} takes a media path such as "media/photo.webp", or null. Markdown does not accept the upload record.`,
+      line.number,
+    );
+  }
+  return await resolveAuthoredImage(value, context, line, path);
+}
+
+function parseJsonOrUndefined(source) {
+  try {
+    return JSON.parse(source);
+  } catch {
+    return undefined;
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/content/tiptap-prosemirror.ts

@@ -367,14 +367,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,
-          rel: "noopener noreferrer nofollow",
-        },
-        html,
-      );
+      return renderElement("a", { href, ...linkRelAttributes(mark.attrs) }, html);
     }
     default:
       return html;
@@ -1377,6 +1370,71 @@ function serializeAttributes(attrs: Record<string, string | number | boolean | n
   return serialized.length ? ` ${serialized.join(" ")}` : "";
 }
 
+/**
+ * The rel tokens a link may carry (TR01190): every HTML link type valid on
+ * `<a>` except `opener`, which hands a new tab a handle on the page.
+ */
+export const LINK_REL_TOKENS = [
+  "nofollow",
+  "sponsored",
+  "ugc",
+  "me",
+  "noopener",
+  "noreferrer",
+  "external",
+  "author",
+  "license",
+  "tag",
+  "bookmark",
+  "help",
+  "prev",
+  "next",
+  "privacy-policy",
+  "terms-of-service",
+] as const;
+/** The targets a link may carry; only `_blank` changes what renders. */
+export const LINK_TARGETS = ["_blank", "_self"] as const;
+/**
+ * The editor stored this rel, with `target="_blank"`, on every link before
+ * authors could choose, so a mark carrying it records no choice of either.
+ */
+export const LEGACY_EDITOR_LINK_REL = "noopener noreferrer nofollow";
+
+/**
+ * An author's chosen tokens as a stored rel. Those three tokens in the old
+ * default's order would read as no choice, so they are stored in vocabulary
+ * order instead.
+ */
+export function spellLinkRel(tokens: readonly string[]): string {
+  const rel = tokens.join(" ");
+  return rel === LEGACY_EDITOR_LINK_REL
+    ? LINK_REL_TOKENS.filter((token) => tokens.includes(token)).join(" ")
+    : rel;
+}
+
+/** A stored rel as tokens, or undefined when it is the editor's old default (no choice). */
+export function chosenLinkRelTokens(rel: unknown): string[] | undefined {
+  const tokens = stringAttr(rel)?.trim().toLowerCase().split(/\s+/u).filter(Boolean) ?? [];
+  return tokens.join(" ") === LEGACY_EDITOR_LINK_REL ? undefined : tokens;
+}
+
+/**
+ * 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.
+ */
+export function linkRelAttributes(attrs: Record<string, unknown> | undefined): { rel?: string; target?: string } {
+  const stored = chosenLinkRelTokens(attrs?.rel);
+  if (!stored) return {};
+  const newTab = stringAttr(attrs?.target)?.trim().toLowerCase() === "_blank";
+  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" } : {}) };
+}
+
 function isSafeUrl(url: string): boolean {
   if (/[\x00-\x1f\x7f\\]/u.test(url)) return false;
   const cleaned = url.trim();

package/src/content/validate-document.js

@@ -18,6 +18,8 @@ import {
   isPlainObject,
   isSafeUrl,
   isUuid,
+  LINK_REL_TOKENS,
+  LINK_TARGETS,
   MARK_TYPE_SET,
   NODE_TYPE_SET,
   normalizeCssLengthOverride,
@@ -485,12 +487,34 @@ const MARK_RULES = Object.freeze({
       { required: true, code: CODES.linkHref, missingCode: CODES.linkHref },
     ),
     // `@tiptap/extension-link` declares these four alongside `href`, and
-    // `Mark.toJSON` emits every declared attribute — so every link the editor
-    // has ever written carries all five, and refusing any of them would refuse
-    // an ordinary pull/push round trip. The renderer ignores them and writes
-    // its own `rel`.
-    target: optionalString(),
-    rel: optionalString(),
+    // `Mark.toJSON` emits every declared attribute, so every link the editor
+    // has ever written carries all five. The renderer publishes `rel` and
+    // `target="_blank"` from closed lists (TR01190), so those two are held to
+    // them; it ignores `class` and `title`. The editor's old default rel,
+    // "noopener noreferrer nofollow", is within the list and renders as no
+    // choice.
+    target: spec(
+      (value) => {
+        if (isAbsent(value) || (typeof value === "string" && value.trim() === "")) return null;
+        return typeof value === "string" && LINK_TARGETS.includes(value.trim().toLowerCase())
+          ? null
+          : `"_blank" (open in a new tab), "_self", or absent`;
+      },
+      { code: CODES.linkTarget },
+    ),
+    rel: spec(
+      (value) => {
+        if (isAbsent(value)) return null;
+        if (typeof value !== "string") return "a string of space-separated link types";
+        const unknown = value.trim().toLowerCase().split(/\s+/u)
+          .filter((token) => token && !LINK_REL_TOKENS.includes(token));
+        if (unknown.length === 0) return null;
+        return `space-separated link types from ${LINK_REL_TOKENS.join(", ")}; ${
+          unknown.map((token) => `"${token}"`).join(", ")
+        } ${unknown.length === 1 ? "is" : "are"} not one`;
+      },
+      { code: CODES.linkRel },
+    ),
     class: optionalString(),
     title: optionalString(),
   }),