@bendyline/squisq 1.4.1 → 1.5.1

package/src/markdown/sanitize.ts

@@ -0,0 +1,318 @@
+import type { HtmlElement, HtmlNode } from './types.js';
+
+export type HtmlPolicy = 'strip' | 'sanitize' | 'trusted';
+
+export type UrlKind = 'link' | 'media';
+
+const SAFE_LINK_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
+const SAFE_MEDIA_SCHEMES = new Set(['http', 'https', 'blob']);
+
+/** Schemes that can execute script — never allowed, even via extraLinkSchemes. */
+const NEVER_ALLOWED_SCHEMES = new Set(['javascript', 'vbscript', 'data']);
+
+export interface SanitizeUrlOptions {
+  /**
+   * Extra lowercase schemes allowed for `kind: 'link'` — the host-app escape
+   * hatch for custom link protocols it intercepts itself (e.g. an app-internal
+   * navigation scheme). Executable schemes are refused regardless.
+   */
+  extraLinkSchemes?: readonly string[];
+}
+
+const SAFE_DATA_MEDIA_RE =
+  /^data:(?:image\/(?!svg\+xml)[a-z0-9.+-]+|audio\/[a-z0-9.+-]+|video\/[a-z0-9.+-]+);/i;
+
+const SAFE_TAGS = new Set([
+  'a',
+  'abbr',
+  'b',
+  'blockquote',
+  'br',
+  'caption',
+  'cite',
+  'code',
+  'col',
+  'colgroup',
+  'data',
+  'dd',
+  'del',
+  'details',
+  'dfn',
+  'div',
+  'dl',
+  'dt',
+  'em',
+  'figcaption',
+  'figure',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'hr',
+  'i',
+  'img',
+  'kbd',
+  'li',
+  'mark',
+  'ol',
+  'p',
+  'pre',
+  'q',
+  's',
+  'samp',
+  'small',
+  'source',
+  'span',
+  'strong',
+  'sub',
+  'summary',
+  'sup',
+  'table',
+  'tbody',
+  'td',
+  'tfoot',
+  'th',
+  'thead',
+  'time',
+  'tr',
+  'track',
+  'u',
+  'ul',
+  'var',
+  'video',
+  'audio',
+]);
+
+const DROP_WITH_CONTENT_TAGS = new Set([
+  'base',
+  'button',
+  'embed',
+  'form',
+  'iframe',
+  'input',
+  'link',
+  'meta',
+  'object',
+  'option',
+  'script',
+  'select',
+  'style',
+  'svg',
+  'template',
+  'textarea',
+]);
+
+const GLOBAL_ATTRS = new Set(['class', 'id', 'title', 'role']);
+
+const TAG_ATTRS: Record<string, Set<string>> = {
+  a: new Set(['href', 'target', 'rel']),
+  audio: new Set(['src', 'controls', 'preload', 'muted', 'loop']),
+  col: new Set(['span', 'width']),
+  colgroup: new Set(['span']),
+  data: new Set(['value']),
+  img: new Set(['src', 'alt', 'width', 'height', 'loading', 'decoding']),
+  li: new Set(['value']),
+  ol: new Set(['start', 'type']),
+  q: new Set(['cite']),
+  source: new Set(['src', 'type', 'media']),
+  td: new Set(['colspan', 'rowspan', 'align']),
+  th: new Set(['colspan', 'rowspan', 'align', 'scope']),
+  time: new Set(['datetime']),
+  track: new Set(['src', 'kind', 'label', 'srclang', 'default']),
+  video: new Set([
+    'src',
+    'poster',
+    'width',
+    'height',
+    'controls',
+    'preload',
+    'muted',
+    'loop',
+    'playsinline',
+  ]),
+};
+
+const SAFE_ATTR_NAME_RE = /^[a-z][a-z0-9:_.-]*$/;
+const SAFE_OL_TYPES = new Set(['1', 'a', 'A', 'i', 'I']);
+const SAFE_PRELOAD_VALUES = new Set(['none', 'metadata', 'auto']);
+const SAFE_TRACK_KINDS = new Set(['subtitles', 'captions', 'descriptions', 'chapters', 'metadata']);
+
+/**
+ * Sanitize a URL for a rendered link or media attribute.
+ *
+ * Relative URLs are allowed. Absolute URLs are restricted to schemes that
+ * cannot execute script in a document context. Media URLs additionally allow
+ * `blob:` and image/audio/video `data:` URLs because Squisq uses both for
+ * browser-local media previews and self-contained exports.
+ */
+export function sanitizeUrl(
+  url: string | null | undefined,
+  kind: UrlKind = 'link',
+  options?: SanitizeUrlOptions,
+): string | null {
+  if (typeof url !== 'string') return null;
+
+  const trimmed = url.trim();
+  if (!trimmed) return null;
+
+  const compact = stripUrlSchemeNoise(trimmed);
+  const colon = compact.indexOf(':');
+  const firstPathChar = firstIndexOfAny(compact, ['/', '?', '#']);
+  const hasScheme = colon >= 0 && (firstPathChar < 0 || colon < firstPathChar);
+
+  if (!hasScheme) return trimmed;
+
+  const scheme = compact.slice(0, colon).toLowerCase();
+  if (kind === 'media') {
+    if (scheme === 'data') return SAFE_DATA_MEDIA_RE.test(compact) ? trimmed : null;
+    return SAFE_MEDIA_SCHEMES.has(scheme) ? trimmed : null;
+  }
+
+  if (SAFE_LINK_SCHEMES.has(scheme)) return trimmed;
+  if (options?.extraLinkSchemes?.includes(scheme) && !NEVER_ALLOWED_SCHEMES.has(scheme)) {
+    return trimmed;
+  }
+  return null;
+}
+
+/**
+ * Return a sanitized copy of an HtmlNode tree. The original parsed tree is left
+ * untouched so markdown stringify can still preserve source fidelity.
+ */
+export function sanitizeHtmlNodes(nodes: HtmlNode[]): HtmlNode[] {
+  const out: HtmlNode[] = [];
+  for (const node of nodes) {
+    out.push(...sanitizeHtmlNode(node));
+  }
+  return out;
+}
+
+function sanitizeHtmlNode(node: HtmlNode): HtmlNode[] {
+  switch (node.type) {
+    case 'htmlText':
+      return [node];
+    case 'htmlComment':
+      return [];
+    case 'htmlElement':
+      return sanitizeHtmlElement(node);
+  }
+}
+
+function sanitizeHtmlElement(node: HtmlElement): HtmlNode[] {
+  const tag = node.tagName.toLowerCase();
+
+  if (DROP_WITH_CONTENT_TAGS.has(tag)) return [];
+
+  const children = sanitizeHtmlNodes(node.children);
+  if (!SAFE_TAGS.has(tag)) return children;
+
+  return [
+    {
+      type: 'htmlElement',
+      tagName: tag,
+      attributes: sanitizeAttrs(tag, node.attributes),
+      children,
+      selfClosing: node.selfClosing,
+    },
+  ];
+}
+
+function sanitizeAttrs(tag: string, attrs: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [rawName, rawValue] of Object.entries(attrs)) {
+    const name = rawName.toLowerCase();
+    if (!isAllowedAttr(tag, name)) continue;
+
+    const value = String(rawValue);
+    const safeValue = sanitizeAttrValue(tag, name, value);
+    if (safeValue === null) continue;
+    out[name] = safeValue;
+  }
+  if (tag === 'a' && out.target === '_blank') {
+    out.rel = ensureRelTokens(out.rel, ['noopener', 'noreferrer']);
+  }
+  return out;
+}
+
+function isAllowedAttr(tag: string, name: string): boolean {
+  if (!SAFE_ATTR_NAME_RE.test(name)) return false;
+  if (name.startsWith('on')) return false;
+  if (name.startsWith('aria-') || name.startsWith('data-')) return true;
+  if (GLOBAL_ATTRS.has(name)) return true;
+  return TAG_ATTRS[tag]?.has(name) ?? false;
+}
+
+function sanitizeAttrValue(tag: string, name: string, value: string): string | null {
+  if (name === 'href') return sanitizeUrl(value, 'link');
+  if (name === 'src' || name === 'poster') return sanitizeUrl(value, 'media');
+  if (
+    (name === 'width' ||
+      name === 'height' ||
+      name === 'span' ||
+      name === 'colspan' ||
+      name === 'rowspan' ||
+      name === 'value') &&
+    !isNonNegativeInteger(value)
+  ) {
+    return null;
+  }
+  if (name === 'start' && !isInteger(value)) return null;
+  if (name === 'type' && tag === 'ol' && !SAFE_OL_TYPES.has(value)) return null;
+  if (name === 'preload' && !SAFE_PRELOAD_VALUES.has(value)) return null;
+  if (name === 'kind' && tag === 'track' && !SAFE_TRACK_KINDS.has(value)) return null;
+  if (name === 'align' && value !== 'left' && value !== 'right' && value !== 'center') return null;
+  if (name === 'target')
+    return value === '_blank' || value === '_self' || value === '_parent' || value === '_top'
+      ? value
+      : null;
+  if (name === 'rel') return sanitizeRel(value);
+  return value;
+}
+
+function sanitizeRel(value: string): string {
+  return relTokens(value).join(' ');
+}
+
+function ensureRelTokens(value: string | undefined, required: string[]): string {
+  const tokens = new Set(value ? relTokens(value) : []);
+  for (const token of required) tokens.add(token);
+  return Array.from(tokens).join(' ');
+}
+
+function relTokens(value: string): string[] {
+  const tokens = value
+    .split(/\s+/)
+    .map((token) => token.trim().toLowerCase())
+    .filter(Boolean)
+    .filter((token) => /^[a-z0-9_-]+$/.test(token));
+  return Array.from(new Set(tokens));
+}
+
+function isInteger(value: string): boolean {
+  return /^-?\d+$/.test(value.trim());
+}
+
+function isNonNegativeInteger(value: string): boolean {
+  return /^\d+$/.test(value.trim());
+}
+
+function firstIndexOfAny(value: string, needles: string[]): number {
+  let result = -1;
+  for (const needle of needles) {
+    const index = value.indexOf(needle);
+    if (index >= 0 && (result < 0 || index < result)) result = index;
+  }
+  return result;
+}
+
+function stripUrlSchemeNoise(value: string): string {
+  let out = '';
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code <= 0x20 || code === 0x7f || char.trim() === '') continue;
+    out += char;
+  }
+  return out;
+}

package/src/markdown/stringify.ts

@@ -12,10 +12,65 @@ import remarkMath from 'remark-math';
 import remarkDirective from 'remark-directive';
 import type { MarkdownDocument, StringifyOptions } from './types.js';
 import { toMdast } from './convert.js';
+import { formatBlockScalar } from './utils.js';
 
 // Cache the default processor (all extensions, default formatting) to avoid rebuilding on every call.
 let defaultProcessor: any;
 
+// ============================================
+// Annotation-span unescaping
+// ============================================
+
+// Quoted runs as they appear in remark-stringify output. Backslashes inside
+// the span are doubled by remark (a literal `\` before punctuation becomes
+// `\\`), so `\\.` covers both authored escapes and remark's own.
+const DQ_RUN = `"(?:[^"\\\\]|\\\\.)*"`;
+const SQ_RUN = `'(?:[^'\\\\]|\\\\.)*'`;
+
+/**
+ * A `{[…]}` template-annotation (or inline-icon) span as it appears in
+ * remark output: `{\[inner]}`, where `inner` may contain backslash escapes
+ * and quoted runs (which may themselves contain `]`).
+ */
+const ESCAPED_TEMPLATE_SPAN_RE = new RegExp(
+  `\\{\\\\\\[((?:${DQ_RUN}|${SQ_RUN}|\\\\.|[^\\]\\\\])+)\\]\\}`,
+  'g',
+);
+
+/** A heading line (annotations are only emitted trailing on headings). */
+const HEADING_LINE_RE = /^#{1,6} .*$/gm;
+
+/**
+ * The trailing Pandoc `{…}` span on a heading line, possibly followed by an
+ * already-unescaped `{[…]}` template span (canonical emit order).
+ */
+const TRAILING_ESCAPED_PANDOC_SPAN_RE = new RegExp(
+  `\\{(?!\\\\?\\[)((?:${DQ_RUN}|${SQ_RUN}|\\\\.|[^}\\\\])*)\\}(?=\\s*(?:\\{\\[.*)?$)`,
+);
+
+/**
+ * Backslash+punctuation pairs that are safe to unescape inside an
+ * annotation span: the bare character re-parses as literal text in
+ * trailing-heading position, so removing the backslash is purely
+ * cosmetic and round-trips.
+ *
+ * Deliberately EXCLUDED (left escaped in the emitted markdown): emphasis
+ * and other inline-construct openers (`*`, `_`, `` ` ``, `~`, `<`, `>`,
+ * `&`, `!`, `|`, `^`). Unescaping those could make remark-parse split the
+ * heading's text run into inline nodes on reparse, which would hide the
+ * annotation from the extractor. remark-parse resolves the surviving
+ * `\X` escapes back to bare characters, so values still round-trip —
+ * the escapes are a cosmetic cost only.
+ *
+ * Pairs are consumed left to right, so an authored `\"` that remark
+ * doubled to `\\"` correctly comes back as `\"`.
+ */
+const UNESCAPE_PUNCT_RE = /\\([\\[\]:#.,+=/?;@%$(){}'"-])/g;
+
+function unescapeMarkdownPunct(text: string): string {
+  return text.replace(UNESCAPE_PUNCT_RE, '$1');
+}
+
 /**
  * Serialize a MarkdownDocument back to a markdown string.
  *
@@ -106,15 +161,50 @@ export function stringifyMarkdown(doc: MarkdownDocument, options?: StringifyOpti
   // Stringify mdast → markdown string
   const result = processor.stringify(mdastTree) as string;
 
-  // remark-stringify escapes `[` in text nodes (to prevent link syntax),
-  // which turns `{[template]}` into `{\[template]}`. Unescape our annotation syntax.
-  const cleaned = result.replace(/\{\\\[([^\]]+)\]\}/g, '{[$1]}');
+  // remark-stringify backslash-escapes markdown-significant characters in
+  // text nodes (`[` to prevent link syntax, `:` for directives, `*`/`_` for
+  // emphasis, a literal `\` before punctuation, …). Our annotations are
+  // injected as plain text, so their interiors come back escaped. Undo that
+  // inside `{[…]}` template-annotation spans: removing one backslash from
+  // each backslash+punctuation pair (left to right) exactly inverts
+  // remark's escaping — including restoring an authored `\"` that remark
+  // doubled to `\\"`. The span regex understands quoted values, so a
+  // quoted `]` doesn't terminate the span.
+  let cleaned = result.replace(
+    ESCAPED_TEMPLATE_SPAN_RE,
+    (_m, inner: string) => `{[${unescapeMarkdownPunct(inner)}]}`,
+  );
+
+  // Same treatment for the trailing Pandoc `{…}` attribute block on heading
+  // lines (canonical emit order is Pandoc block then template annotation,
+  // so the span sits at end-of-line or just before a `{[…]}` span).
+  cleaned = cleaned.replace(HEADING_LINE_RE, (line) =>
+    line.replace(
+      TRAILING_ESCAPED_PANDOC_SPAN_RE,
+      (_m, inner: string) => `{${unescapeMarkdownPunct(inner)}}`,
+    ),
+  );
+
+  // remark-directive escapes `:` in text (since `:name` would round-trip as
+  // a text directive). Inside any other Pandoc-style `{…}` brace span, `:`
+  // is purely a value separator (e.g. `connectsTo=foo:flow`), so unescape
+  // it to keep round-trips lossless. The negative lookahead skips `{[…]}`
+  // template annotations — those are handled above.
+  cleaned = cleaned.replace(/\{(?!\\?\[)[^}]*\}/g, (match) => match.replace(/\\:/g, ':'));
 
   // Prepend YAML frontmatter if present
   if (doc.frontmatter && Object.keys(doc.frontmatter).length > 0) {
-    const yamlLines = Object.entries(doc.frontmatter).map(
-      ([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`,
-    );
+    const yamlLines = Object.entries(doc.frontmatter).map(([k, v]) => {
+      if (typeof v === 'string') {
+        // Multi-line strings emit as a YAML literal block scalar, matching
+        // `formatFrontmatterValue` / `setFrontmatterValues` so both paths
+        // agree; single-line strings stay verbatim as before.
+        return /[\r\n]/.test(v)
+          ? `${k}: ${formatBlockScalar(v.replace(/\r\n?/g, '\n'))}`
+          : `${k}: ${v}`;
+      }
+      return `${k}: ${JSON.stringify(v)}`;
+    });
     return `---\n${yamlLines.join('\n')}\n---\n\n${cleaned}`;
   }
 

package/src/markdown/types.ts

@@ -126,6 +126,65 @@ export interface HeadingTemplateAnnotation {
   params?: Record<string, string>;
 }
 
+/**
+ * A directed connection from one block to another, parsed from a heading
+ * attribute `connectsTo=target1,target2:type,target3`. Mirrors the schema
+ * `BlockConnection` type — duplicated here so this module stays
+ * dependency-free from the doc schema.
+ */
+export interface BlockConnection {
+  /** Target block id. */
+  target: string;
+  /** Optional connection type/label (e.g., "flow", "requires"). */
+  type?: string;
+}
+
+/**
+ * Pandoc-style heading attribute block, parsed from `{#id .class key=value}`
+ * appearing at the end of a heading line (alongside, or instead of, the
+ * squisq-native `{[templateName …]}` block).
+ *
+ * @example
+ * ```markdown
+ * ## Architecture {#arch x=600 y=300 connectsTo=foo:flow,bar:requires}
+ * ```
+ * →
+ * ```ts
+ * {
+ *   id: 'arch',
+ *   params: { x: '600', y: '300', connectsTo: 'foo:flow,bar:requires' },
+ *   blockMeta: {
+ *     x: 600,
+ *     y: 300,
+ *     connectsTo: [{ target: 'foo', type: 'flow' }, { target: 'bar', type: 'requires' }],
+ *   },
+ * }
+ * ```
+ *
+ * `params` carries the raw pre-coercion strings (lossless for round-tripping),
+ * while `blockMeta` carries the typed values for known keys. Unknown keys flow
+ * to `metadata`.
+ */
+export interface HeadingAttributes {
+  /** Block id from `#identifier` (overrides slug-from-heading). */
+  id?: string;
+  /** Class tokens from `.classname` (reserved for downstream use). */
+  classes?: string[];
+  /** All key=value attributes as raw strings (lossless source for serialization). */
+  params?: Record<string, string>;
+  /** Typed values for known block-meta keys (coerced from `params`). */
+  blockMeta?: {
+    x?: number;
+    y?: number;
+    startTime?: number;
+    duration?: number;
+    connectsTo?: BlockConnection[];
+    transition?: import('../schemas/Transitions.js').Transition;
+  };
+  /** Subset of `params` whose keys are NOT in the known-key registry. */
+  metadata?: Record<string, string>;
+}
+
 /**
  * ATX or setext heading (# Heading).
  */
@@ -142,6 +201,13 @@ export interface MarkdownHeading extends MarkdownNodeBase {
    * stringification, so it round-trips transparently.
    */
   templateAnnotation?: HeadingTemplateAnnotation;
+  /**
+   * Pandoc-style heading attributes parsed from trailing `{#id .class key=value}`
+   * syntax. Independent from `templateAnnotation` — both may appear on the
+   * same heading in either order. Stripped from `children` during parsing
+   * and re-injected during stringification.
+   */
+  attributes?: HeadingAttributes;
 }
 
 /**

package/src/markdown/utils.ts

@@ -5,7 +5,8 @@
  * All functions are pure and operate on the JSON node interfaces.
  */
 
-import type { MarkdownNode, MarkdownDocument } from './types.js';
+import type { MarkdownNode, MarkdownDocument, HtmlNode } from './types.js';
+import { parseHtmlToNodes } from './htmlParse.js';
 
 /**
  * Get the children of any markdown node, if it has children.
@@ -123,8 +124,10 @@ export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
   if (!yaml || !yaml.trim()) return null;
 
   const result: Record<string, unknown> = {};
+  const lines = yaml.split('\n');
 
-  for (const line of yaml.split('\n')) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith('#')) continue;
 
@@ -134,6 +137,45 @@ export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
     const key = trimmed.slice(0, colonIdx).trim();
     let value: string | boolean | number = trimmed.slice(colonIdx + 1).trim();
 
+    // YAML literal block scalar: `key: |` or `key: |-`. Subsequent lines
+    // that are more-indented than the key belong to the scalar; they are
+    // dedented by their common leading indent and joined with `\n`. A line
+    // at the key's indent (or less) ends the scalar. Both `|` and `|-`
+    // yield the joined string here (`|-` without a trailing newline); we do
+    // not model `|`'s trailing-newline / `+`/`-` chomping nuances beyond
+    // stripping trailing blank lines.
+    if (value === '|' || value === '|-') {
+      const keyIndent = line.length - line.trimStart().length;
+      const blockLines: string[] = [];
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        const bl = lines[j];
+        if (bl.trim() === '') {
+          blockLines.push('');
+          continue;
+        }
+        const indent = bl.length - bl.trimStart().length;
+        if (indent <= keyIndent) break; // dedent ends the scalar
+        blockLines.push(bl);
+      }
+      i = j - 1; // resume the outer walk at the terminating line
+
+      // Drop trailing blank lines captured inside the scalar.
+      while (blockLines.length > 0 && blockLines[blockLines.length - 1] === '') {
+        blockLines.pop();
+      }
+
+      // Dedent by the common leading whitespace of the non-blank lines.
+      let commonIndent = Infinity;
+      for (const bl of blockLines) {
+        if (bl === '') continue;
+        commonIndent = Math.min(commonIndent, bl.length - bl.trimStart().length);
+      }
+      if (!isFinite(commonIndent)) commonIndent = 0;
+      result[key] = blockLines.map((bl) => (bl === '' ? '' : bl.slice(commonIndent))).join('\n');
+      continue;
+    }
+
     // Remove surrounding quotes
     if (
       (value.startsWith('"') && value.endsWith('"')) ||
@@ -157,11 +199,37 @@ export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/**
+ * Format a multi-line string as a YAML literal block scalar body, i.e.
+ * `|-` followed by each source line indented two spaces. Paired with
+ * {@link parseFrontmatter}'s block-scalar reader so multi-line frontmatter
+ * values (e.g. pretty-printed JSON payloads) round-trip. Blank lines stay
+ * blank (no trailing whitespace) so the output diffs cleanly.
+ */
+export function formatBlockScalar(value: string): string {
+  const body = value
+    .split('\n')
+    .map((line) => (line === '' ? '' : `  ${line}`))
+    .join('\n');
+  return `|-\n${body}`;
+}
+
 const FRONTMATTER_BLOCK_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n)?/;
 
 /** Quote a frontmatter scalar so it round-trips cleanly through `parseFrontmatter`. */
 function formatFrontmatterValue(value: string | number | boolean): string {
   if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  // Multi-line strings can't live on one line — emit a YAML literal block
+  // scalar (`|-`) that `parseFrontmatter` reads back. This carries pretty-
+  // printed JSON payloads (opt-in custom templates/themes). Single-line
+  // values keep their exact historical output below.
+  if (/[\r\n]/.test(value)) return formatBlockScalar(value.replace(/\r\n?/g, '\n'));
+  // A single-line JSON object/array literal round-trips verbatim through
+  // the line-based `parseFrontmatter` (no leading quote to strip, no
+  // newline to split on), so write it unquoted to keep it human-readable
+  // — matching how `stringifyMarkdown` emits string values. Used by the
+  // compact custom-layouts payload.
+  if (/^[{[]/.test(value) && !/[\r\n]/.test(value)) return value;
   // Quote when needed: leading/trailing whitespace, leading punctuation that
   // could trigger YAML modes, or values that look like reserved literals.
   const needsQuote =
@@ -326,3 +394,44 @@ export function readFrontmatterThemeId(
   }
   return undefined;
 }
+
+/**
+ * Project an inline-HTML string (as stored on `TextLayer.content.html`) down
+ * to plain text — the value mirrored into `content.text` for plain consumers
+ * (PDF/markdown export, search, accessibility) and the SVG `<text>` fallback.
+ *
+ * `<br>` and block-level tags (`p`, `div`, `h1`–`h6`, `li`, `blockquote`,
+ * `pre`) become line breaks so multi-line rich content reads sensibly. Entity
+ * decoding is handled by {@link parseHtmlToNodes} (parse5-backed), so this is
+ * more correct than a regex tag-stripper.
+ */
+export function plainTextFromInlineHtml(html: string): string {
+  const BLOCK = new Set([
+    'p',
+    'div',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'li',
+    'blockquote',
+    'pre',
+  ]);
+  const walk = (nodes: HtmlNode[]): string =>
+    nodes
+      .map((n) => {
+        if (n.type === 'htmlText') return n.value;
+        if (n.type !== 'htmlElement') return '';
+        const tag = n.tagName.toLowerCase();
+        if (tag === 'br') return '\n';
+        const inner = walk(n.children);
+        return BLOCK.has(tag) ? `${inner}\n` : inner;
+      })
+      .join('');
+  return walk(parseHtmlToNodes(html))
+    .replace(/\u00A0/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}