@jarenjs/view 0.34.0

package/src/helpers/index.js

@@ -0,0 +1,35 @@
+//@ts-check
+/**
+ * @file `@jarenjs/view/helpers` — the shared, view-layer helper kernel:
+ * SVG vnode builders over `h()`, the URL policies that guard what may
+ * reach an `href`/`src`, the prefix-driven theme resolver that
+ * SVG-emitting components (`@jarenjs/calc`, `@jarenjs/mermaid`, …) build
+ * on, and the memoized `view()` projection pair the component layers
+ * share. Import the whole barrel (`@jarenjs/view/helpers`) or a single
+ * module (`@jarenjs/view/helpers/svg`, `@jarenjs/view/helpers/url`,
+ * `@jarenjs/view/helpers/theme`).
+ */
+
+export { sanitizeHref, sanitizeUrl, encodeUrlAttribute } from './url.js';
+
+export {
+  num,
+  coord,
+  polarPoint,
+  anchorForAngle,
+  svgRoot,
+  group,
+  rect,
+  circle,
+  line,
+  path,
+  polyline,
+  polygon,
+  textAt,
+  textLines,
+  polylinePath,
+} from './svg.js';
+
+export { resolveTheme } from './theme.js';
+export { measureText, textWidth } from './metrics.js';
+export { createProjectionMemo } from './memo.js';

package/src/helpers/memo.js

@@ -0,0 +1,61 @@
+//@ts-check
+/**
+ * @file The memo pair a visual component's `view()` projection is built
+ * on: an LRU-memoized `compile(source)` and a reference-stable
+ * `view(sourceOrDoc)` that accepts either a source string or an
+ * already-parsed document. Reference stability is the point — an
+ * unchanged input returns the identical vnode, so the patcher sees it
+ * in O(1) (the O(change) contract).
+ */
+
+import { createBoundedCache } from '@jarenjs/core/cache';
+
+/**
+ * @typedef {object} ProjectionMemo
+ * @property {(source: string) => any} compile memoized compile
+ * @property {(sourceOrDoc: any) => any} view memoized vnode projection:
+ *   a string compiles through the source memo; `null`/`undefined`
+ *   project to `null`; any other value is treated as a parsed document
+ *   and memoized by reference.
+ */
+
+/**
+ * Create the memoized compile + view projection for a source-compiling
+ * component. The source memo is a string-keyed LRU (Map re-insertion
+ * order as recency); the document memo is a WeakMap keyed on the parsed
+ * document's identity, so documents held in app state stay cached for
+ * exactly as long as the state holds them.
+ *
+ * @param {object} spec
+ * @param {(source: string) => any} spec.compile compile a source string
+ * @param {(compiled: any) => any} spec.toVnode project a compiled result
+ * @param {(doc: object) => any} spec.docToVnode project a parsed document
+ * @param {number} [spec.memoLimit] LRU size of the source memo (default 32)
+ * @returns {ProjectionMemo}
+ */
+export function createProjectionMemo({ compile, toVnode, docToVnode, memoLimit = 32 }) {
+  /** Source-string memo (the shared bounded LRU, `@jarenjs/core/cache`). */
+  const bySource = createBoundedCache(memoLimit);
+  /** Parsed-document memo (reference-keyed). */
+  /** @type {WeakMap<object, any>} */
+  const byDoc = new WeakMap();
+
+  /** @type {(source: string) => any} */
+  const memoCompile = (source) => bySource.getOrCreate(source, compile);
+
+  /** @type {(sourceOrDoc: any) => any} */
+  const view = (sourceOrDoc) => {
+    if (typeof sourceOrDoc === 'string') {
+      return toVnode(memoCompile(sourceOrDoc));
+    }
+    if (sourceOrDoc === null || sourceOrDoc === undefined) return null;
+    let vnode = byDoc.get(sourceOrDoc);
+    if (vnode === undefined) {
+      vnode = docToVnode(sourceOrDoc);
+      byDoc.set(sourceOrDoc, vnode);
+    }
+    return vnode;
+  };
+
+  return { compile: memoCompile, view };
+}

package/src/helpers/metrics.js

@@ -0,0 +1,116 @@
+//@ts-check
+/**
+ * @file Headless text metrics (design decision: no `getBBox`, no DOM).
+ *
+ * `measureText` estimates a string's rendered box from a precomputed
+ * per-codepoint advance-width table for a default sans-serif at unit em.
+ * It is deliberately an **approximation** — pixel parity with a browser
+ * font is a non-goal. The table is a module constant (`Float32Array`),
+ * the hot loop allocates nothing, and unmapped codepoints fall back to
+ * an average advance. Shared by the SVG-emitting components
+ * (`@jarenjs/mermaid` layout, `@jarenjs/charts` legends and axes).
+ */
+
+/** Average advance (em) for codepoints outside the ASCII table. */
+const FALLBACK_ADVANCE = 0.55;
+/** Line-height multiple of the font size. */
+const LINE_HEIGHT = 1.2;
+
+/**
+ * ASCII printable advances (em) for a Helvetica-like sans-serif,
+ * indexed by `code - 32`. Compact, good enough for box sizing.
+ */
+const ADVANCE = buildAdvanceTable();
+
+/**
+ * @returns {Float32Array}
+ */
+function buildAdvanceTable() {
+  const t = new Float32Array(95);
+  t.fill(0.556);
+  const set = (chars, w) => {
+    for (const ch of chars) t[ch.charCodeAt(0) - 32] = w;
+  };
+  set(' ', 0.278);
+  set('!', 0.278);
+  set('"', 0.355);
+  set("'", 0.191);
+  set('(', 0.333); set(')', 0.333);
+  set('*', 0.389);
+  set('+', 0.584);
+  set(',', 0.278); set('.', 0.278);
+  set('-', 0.333);
+  set('/', 0.278);
+  set('0123456789', 0.556);
+  set(':', 0.278); set(';', 0.278);
+  set('<', 0.584); set('=', 0.584); set('>', 0.584);
+  set('?', 0.556);
+  set('@', 1.015);
+  set('ABDEHKNPRSUVXYZ', 0.667);
+  set('C', 0.722); set('G', 0.722); set('O', 0.778); set('Q', 0.778);
+  set('D', 0.722);
+  set('M', 0.833); set('W', 0.944);
+  set('I', 0.278); set('J', 0.5); set('L', 0.556); set('F', 0.611); set('T', 0.611);
+  set('[', 0.278); set(']', 0.278);
+  set('\\', 0.278);
+  set('^', 0.469);
+  set('_', 0.556);
+  set('`', 0.333);
+  set('abcdeghnopqu', 0.556);
+  set('f', 0.278); set('i', 0.222); set('j', 0.222); set('l', 0.222); set('t', 0.278);
+  set('k', 0.5); set('r', 0.333); set('s', 0.5);
+  set('m', 0.833); set('w', 0.722);
+  set('v', 0.5); set('x', 0.5); set('y', 0.5); set('z', 0.5);
+  set('{', 0.334); set('}', 0.334); set('|', 0.26);
+  set('~', 0.584);
+  return t;
+}
+
+/**
+ * Advance (em) of a single codepoint.
+ * @param {number} code
+ * @returns {number}
+ */
+function advanceOf(code) {
+  if (code >= 32 && code < 127) return ADVANCE[code - 32];
+  return FALLBACK_ADVANCE;
+}
+
+/**
+ * Measure a (possibly multi-line) string's box.
+ * @param {string} str
+ * @param {number} fontSize px
+ * @param {number} [weight] 400 normal, 700 bold (bold widens ~4%)
+ * @returns {{ width: number, height: number, lines: string[] }}
+ */
+export function measureText(str, fontSize, weight = 400) {
+  const boldFactor = weight >= 700 ? 1.04 : 1;
+  const lines = str.length === 0 ? [''] : str.split('\n');
+  let maxWidth = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let w = 0;
+    for (let c = 0; c < line.length; c++) w += advanceOf(line.charCodeAt(c));
+    w *= fontSize * boldFactor;
+    if (w > maxWidth) maxWidth = w;
+  }
+  return {
+    width: maxWidth,
+    height: lines.length * fontSize * LINE_HEIGHT,
+    lines,
+  };
+}
+
+/**
+ * The single-line advance width (em × fontSize).
+ * @param {string} str
+ * @param {number} fontSize
+ * @param {number} [weight]
+ * @returns {number}
+ */
+export function textWidth(str, fontSize, weight = 400) {
+  const boldFactor = weight >= 700 ? 1.04 : 1;
+  let w = 0;
+  for (let c = 0; c < str.length; c++) w += advanceOf(str.charCodeAt(c));
+  return w * fontSize * boldFactor;
+}

package/src/helpers/svg.js

@@ -0,0 +1,233 @@
+//@ts-check
+/**
+ * @file Shared SVG vnode builders over the view `h()` constructor — the
+ * single home for the small helper set that `@jarenjs/calc` and
+ * `@jarenjs/mermaid` (and any future SVG-emitting component) draw from.
+ *
+ * Every helper returns a tagged-array vnode; nothing here touches the DOM.
+ * The root is `['svg', {viewBox,…}, …]` so the view patcher namespaces the
+ * whole subtree (VIEW-FORMAT §5.4) and the serializer escapes text. These
+ * builders are geometry-defensive: coordinates flow through `num` so a
+ * NaN/±Inf never reaches the emitted string.
+ */
+
+import { Float64 } from '@jarenjs/core/math';
+import { h } from '../vnode.js';
+
+/**
+ * Clamp a value to a finite number (defends the geometry against
+ * NaN/±Inf).
+ * @param {number} n
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+export function num(n, fallback = 0) {
+  return Number.isFinite(n) ? n : fallback;
+}
+
+/**
+ * Quantize a coordinate to two decimals — the precision SVG geometry is
+ * emitted at, which keeps path data short and makes repeated renders of the
+ * same shape produce identical strings. Non-finite input passes straight
+ * through, so pair this with `num` wherever the value reaches an attribute.
+ * @param {number} v
+ * @returns {number}
+ */
+export function coord(v) {
+  return Float64.roundTo(v, 2);
+}
+
+/**
+ * The point at distance `r` from `(cx, cy)` along `angle` (radians,
+ * 0 = east, y growing downward — SVG screen orientation). Raw
+ * coordinates: quantization (`coord`/`num`) stays at the call site so a
+ * caller's emitted bytes are its own choice.
+ * @param {number} cx
+ * @param {number} cy
+ * @param {number} r
+ * @param {number} angle
+ * @returns {{ x: number, y: number }}
+ */
+export function polarPoint(cx, cy, r, angle) {
+  return { x: cx + r * Math.cos(angle), y: cy + r * Math.sin(angle) };
+}
+
+/**
+ * The `text-anchor` for a label placed radially outward at `angle`
+ * (radians, 0 = east, y growing downward). Labels near the left or right
+ * of the circle read away from it (`end`/`start`); the deadband around
+ * ±90° keeps top and bottom labels centred rather than flipping anchor on
+ * a hair's difference in angle.
+ * @param {number} angle
+ * @returns {'start'|'end'|'middle'}
+ */
+export function anchorForAngle(angle) {
+  const c = Math.cos(angle);
+  return c > 0.3 ? 'start' : c < -0.3 ? 'end' : 'middle';
+}
+
+/**
+ * The root `<svg>`. The caller supplies the `class` string; theme tokens
+ * become CSS custom properties on the element (via `theme.cssVars`) so the
+ * stylesheet can re-theme without a re-render, and `theme.tokens.fontFamily`
+ * is written as the base font.
+ * @param {string} className the root element's `class`
+ * @param {number} width
+ * @param {number} height
+ * @param {{ cssVars: Record<string,string>, tokens: Record<string,string> }} theme
+ * `max-width: 100%` is written inline so a standalone SVG never overflows its
+ * container. It is inline because the theme variables are, and that means it
+ * outranks any stylesheet — so a caller whose content must NOT be scaled down
+ * (a diagram, where shrinking scales the text below legibility) has to opt out
+ * here rather than in CSS.
+ * @param {any[]} children
+ * @param {string} [key]
+ * @param {{ fit?: boolean, fontFamily?: string }} [options] `fit: false` omits
+ *   the inline `max-width`, leaving the element at its natural size for a
+ *   scrolling frame; `fontFamily` overrides the theme's base font for a root
+ *   whose type is part of its meaning (an error box quotes source, so it sets
+ *   monospace) — it must be written here because the theme variables are
+ *   inline, and an inline font outranks any stylesheet rule
+ * @returns {any}
+ */
+export function svgRoot(className, width, height, theme, children, key, options = {}) {
+  const style = { ...theme.cssVars, 'font-family': options.fontFamily ?? theme.tokens.fontFamily };
+  if (options.fit !== false) style['max-width'] = '100%';
+  const props = {
+    class: className,
+    role: 'img',
+    xmlns: 'http://www.w3.org/2000/svg',
+    viewBox: `0 0 ${num(width, 1)} ${num(height, 1)}`,
+    width: num(width, 1),
+    height: num(height, 1),
+    style,
+  };
+  if (key !== undefined) props.key = key;
+  return ['svg', props, ...children];
+}
+
+/**
+ * A `<g>` group.
+ * @param {Record<string,any>} props
+ * @param {any[]} children
+ * @returns {any}
+ */
+export function group(props, children) {
+  return ['g', props, ...children];
+}
+
+/**
+ * A `<rect>` (optionally rounded via props).
+ * @param {number} x @param {number} y @param {number} w @param {number} height
+ * @param {Record<string,any>} props
+ * @returns {any}
+ */
+export function rect(x, y, w, height, props) {
+  return h('rect', { x: num(x), y: num(y), width: num(w), height: num(height), ...props });
+}
+
+/**
+ * A `<circle>`.
+ * @param {number} cx @param {number} cy @param {number} r
+ * @param {Record<string,any>} props
+ * @returns {any}
+ */
+export function circle(cx, cy, r, props) {
+  return h('circle', { cx: num(cx), cy: num(cy), r: num(r), ...props });
+}
+
+/**
+ * A `<line>`.
+ * @param {number} x1 @param {number} y1 @param {number} x2 @param {number} y2
+ * @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export function line(x1, y1, x2, y2, props) {
+  return h('line', { x1: num(x1), y1: num(y1), x2: num(x2), y2: num(y2), ...props });
+}
+
+/**
+ * A `<path>` from a `d` string.
+ * @param {string} d @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export function path(d, props) {
+  return h('path', { d, ...props });
+}
+
+/**
+ * A `<polyline>` from `{x,y}` points (open; defaults to no fill).
+ * @param {{x:number,y:number}[]} points @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export function polyline(points, props) {
+  const p = points.map((pt) => `${num(pt.x)},${num(pt.y)}`).join(' ');
+  return h('polyline', { points: p, fill: 'none', ...props });
+}
+
+/**
+ * A `<polygon>` from `{x,y}` points (closed).
+ * @param {{x:number,y:number}[]} points @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export function polygon(points, props) {
+  const p = points.map((pt) => `${num(pt.x)},${num(pt.y)}`).join(' ');
+  return h('polygon', { points: p, ...props });
+}
+
+/**
+ * A single-line `<text>` anchored at (x,y). `str` is coerced with
+ * `String()` so numeric labels emit as text.
+ * @param {number} x @param {number} y @param {any} str @param {number} fontSize
+ * @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export function textAt(x, y, str, fontSize, props = {}) {
+  return h('text', { x: num(x), y: num(y), 'font-size': fontSize, ...props }, String(str));
+}
+
+/**
+ * A `<text>` block, one `<tspan>` per line, vertically centered on `cy`.
+ * @param {number} cx @param {number} cy
+ * @param {string[]} lines
+ * @param {number} fontSize
+ * @param {Record<string,any>} [props]
+ * @returns {any}
+ */
+export function textLines(cx, cy, lines, fontSize, props = {}) {
+  const total = lines.length;
+  const lineH = fontSize * 1.2;
+  const startY = cy - ((total - 1) * lineH) / 2;
+  const children = lines.map((ln, i) => h('tspan', {
+    x: num(cx),
+    y: num(startY + i * lineH),
+    'text-anchor': 'middle',
+    'dominant-baseline': 'central',
+  }, ln));
+  return h('text', {
+    'font-size': fontSize,
+    'text-anchor': 'middle',
+    ...props,
+  }, ...children);
+}
+
+/**
+ * Build an SVG path `d` from a list of `{x,y}` points, breaking the line
+ * on `null` entries (discontinuities / out-of-range samples). Returns
+ * `''` when there is nothing to draw.
+ * @param {Array<{x:number,y:number}|null>} points
+ * @returns {string}
+ */
+export function polylinePath(points) {
+  let d = '';
+  let pen = false;
+  for (const pt of points) {
+    if (pt === null || !Number.isFinite(pt.x) || !Number.isFinite(pt.y)) {
+      pen = false;
+      continue;
+    }
+    d += (pen ? 'L' : 'M') + num(pt.x) + ' ' + num(pt.y) + ' ';
+    pen = true;
+  }
+  return d.trim();
+}

package/src/helpers/theme.js

@@ -0,0 +1,75 @@
+//@ts-check
+/**
+ * @file Shared theme-resolution mechanics for SVG-emitting components.
+ *
+ * `resolveTheme` is the prefix-driven kernel behind each component's
+ * `createTheme`: it resolves a theme name (or an overrides object) into a
+ * flat token table of concrete values *and* a matching set of
+ * `--<prefix>-*` CSS custom properties. Components keep their own token
+ * tables and pass their CSS-variable prefix; the resolution logic lives
+ * here once. Theme tokens are a view concern, so this is view/helpers, not
+ * core — but the pure `kebabCase` transform it uses is core's.
+ */
+
+import { kebabCase } from '@jarenjs/core/string';
+
+/**
+ * Resolve a theme against a component's token tables.
+ *
+ * `nameOrOverrides` is either a theme name (falling back to `default` when
+ * unknown) or an overrides object; an overrides object may name a base via
+ * its `theme` property. The returned `cssVars` stamp every token as
+ * `--<prefix>-<kebab-case-key>`.
+ *
+ * An overrides object may also carry a reserved `vars` key: a map of token
+ * key → **host** custom-property name (e.g. `{ nodeFill: '--accent-soft' }`).
+ * Linked tokens keep their concrete value in `tokens` (so presentation
+ * attributes stay standalone-valid) but stamp their cssVar as
+ * `var(<host-property>, <concrete>)` — the stamped SVG then follows the
+ * host's tokens (light/dark and all) live, with the concrete color as the
+ * fallback outside any host. `vars` never leaks into `tokens`.
+ *
+ * @param {Record<string, Record<string, string>>} themes the component's
+ *   named token tables (must include a `default`)
+ * @param {string} prefix the CSS-variable prefix (e.g. `mm`, `calc`),
+ *   without the leading `--`
+ * The name `'host'` is reserved: it selects the component's own host-var
+ * map wholesale, which is how a consumer asks for "theme me from the page"
+ * without knowing which tokens are linkable. It resolves to
+ * `{ vars: hostVars }`, so a component that passes no `hostVars` simply has
+ * no `'host'` theme and falls back to `default` like any other unknown name.
+ *
+ * @param {string | Record<string, any>} [nameOrOverrides]
+ * @param {Record<string, string>} [hostVars] the component's token key →
+ *   host custom-property map, used when `nameOrOverrides` is `'host'`
+ * @returns {{ name: string, tokens: Record<string, string>, cssVars: Record<string, string> }}
+ */
+export function resolveTheme(themes, prefix, nameOrOverrides = 'default', hostVars = undefined) {
+  let name = 'default';
+  let base = themes.default;
+  let overrides = {};
+  let vars = null;
+  if (nameOrOverrides === 'host' && hostVars) nameOrOverrides = { vars: hostVars };
+  if (typeof nameOrOverrides === 'string') {
+    name = themes[nameOrOverrides] ? nameOrOverrides : 'default';
+    base = themes[name];
+  }
+  else if (nameOrOverrides && typeof nameOrOverrides === 'object') {
+    if (typeof nameOrOverrides.theme === 'string' && themes[nameOrOverrides.theme]) {
+      name = nameOrOverrides.theme;
+      base = themes[name];
+    }
+    overrides = nameOrOverrides;
+    if (overrides.vars && typeof overrides.vars === 'object') vars = overrides.vars;
+  }
+  const tokens = { ...base, ...overrides };
+  delete tokens.vars;
+  const cssVars = {};
+  for (const key of Object.keys(tokens)) {
+    const linked = vars !== null && typeof vars[key] === 'string' ? vars[key] : null;
+    cssVars['--' + prefix + '-' + kebabCase(key)] = linked !== null
+      ? 'var(' + linked + ', ' + tokens[key] + ')'
+      : tokens[key];
+  }
+  return { name, tokens, cssVars };
+}

package/src/helpers/url.js

@@ -0,0 +1,154 @@
+//@ts-check
+/**
+ * @file URL safety policies for values written into vnode attributes.
+ *
+ * A URL that reaches an `href`/`src` can execute script (`javascript:`,
+ * `vbscript:`) or smuggle a whole document into the page's origin
+ * (`data:text/html`), so every producer that turns *authored* text into a
+ * vnode must filter it. This module is the one home for that decision.
+ *
+ * There are deliberately **two** policies, because the safe answer depends
+ * on where the URL came from, and picking the wrong one is the trap this
+ * file exists to prevent:
+ *
+ * - {@link sanitizeHref} is an **allow-list**: only the listed schemes and
+ *   anchor/absolute/dot-relative forms survive. Use it for URLs from a
+ *   constrained producer that is expected to emit fully-formed links — a
+ *   Mermaid `click` directive, say. It rejects a bare relative reference
+ *   like `image.png`, which is correct there and wrong for prose.
+ * - {@link sanitizeUrl} is a **deny-list**: it rejects the schemes that can
+ *   execute or impersonate a document and passes everything else,
+ *   including scheme-less relative references. Use it for URLs authored in
+ *   ordinary content — Markdown link destinations and image sources — where
+ *   `docs/guide.md` and `image.png` must keep working.
+ *
+ * Both return the trimmed URL or `null`; a `null` means the caller should
+ * drop the attribute rather than emit an unsafe one.
+ */
+
+/** URL forms permitted on a link `href` by the allow-list policy. */
+const RE_SAFE_URL = /^(https?:|mailto:|#|\/|\.)/i;
+
+/** Schemes that can execute script or carry a document of their own. */
+const UNSAFE_SCHEMES = new Set(['javascript', 'vbscript', 'data', 'file']);
+
+/**
+ * The `data:` payloads an `<img>` legitimately wants. Raster only —
+ * `image/svg+xml` is excluded because an SVG document can carry script,
+ * and the contexts that make it inert are not ours to assume.
+ */
+const RE_SAFE_DATA_IMAGE = /^data:image\/(?:gif|png|jpe?g|webp|avif)[;,]/i;
+
+/** Everything RFC 3986 does not allow inside a scheme name. */
+const RE_NOT_SCHEME_CHAR = /[^a-z0-9+.-]/gi;
+
+/**
+ * The scheme a browser will act on, or `''` when the URL is relative.
+ *
+ * Characters that cannot occur in a scheme are dropped rather than treated
+ * as a mismatch, because a browser drops the whitespace and control
+ * characters inside one before resolving the URL: a tab in the middle of
+ * `java<TAB>script:` does not stop it navigating as `javascript:`, so a
+ * literal comparison would wave it through. A `/` before the colon does
+ * keep the URL relative — it is dropped too, but so is the rest of the
+ * path, and what remains no longer spells a dangerous scheme.
+ *
+ * @param {string} url a trimmed URL
+ * @returns {string} the lower-cased scheme, without its colon
+ */
+function schemeOf(url) {
+  const colon = url.indexOf(':');
+  if (colon < 0) return '';
+  return url.slice(0, colon).replace(RE_NOT_SCHEME_CHAR, '').toLowerCase();
+}
+
+/**
+ * Reject `javascript:`/`data:` and other non-http(s) URLs, returning the
+ * trimmed URL when it is safe or `null` otherwise. An **allow-list**: a
+ * scheme-less relative reference (`image.png`) is rejected too, so reach
+ * for {@link sanitizeUrl} when relative references must survive.
+ *
+ * @param {any} url
+ * @returns {string|null}
+ */
+export function sanitizeHref(url) {
+  if (typeof url !== 'string') return null;
+  const trimmed = url.trim();
+  return RE_SAFE_URL.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * Reject only the URL schemes that can execute script or stand in for a
+ * document — `javascript:`, `vbscript:`, `file:` and `data:` other than a
+ * raster image — and pass everything else through, including scheme-less
+ * relative references. The **deny-list** policy for authored content.
+ *
+ * The scheme is read with {@link schemeOf}, which is deliberately not a
+ * literal prefix test — see there for why an embedded tab or NUL does not
+ * get a URL past this.
+ *
+ * @param {any} url
+ * @returns {string|null} the trimmed URL, or `null` when it must be dropped
+ */
+export function sanitizeUrl(url) {
+  if (typeof url !== 'string') return null;
+  const trimmed = url.trim();
+  if (!UNSAFE_SCHEMES.has(schemeOf(trimmed))) return trimmed;
+  return RE_SAFE_DATA_IMAGE.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * Characters a URL attribute may carry literally: the RFC 3986 reserved
+ * and unreserved sets. Everything else is percent-encoded, byte by byte,
+ * from its UTF-8 encoding.
+ */
+const URL_LITERAL = new Uint8Array(128);
+for (const ch of "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789;/?:@&=+$,-_.!~*'()#")
+  URL_LITERAL[ch.charCodeAt(0)] = 1;
+
+/** An already-encoded octet: `%` followed by two hex digits. */
+const RE_PCT_OCTET = /^%[0-9A-Fa-f]{2}/;
+
+/**
+ * Percent-encode a URL for a `href`/`src` attribute.
+ *
+ * Authored text is not a URL: a Markdown destination may hold spaces,
+ * backslashes, backticks or any non-ASCII character, and writing those
+ * into an attribute produces a link a browser resolves differently than
+ * the author wrote — or not at all. This maps them to their UTF-8
+ * percent-encoding while leaving the reserved characters that carry URL
+ * *structure* (`/?:@&=+$,#`) alone.
+ *
+ * An existing `%XX` is passed through rather than re-encoded to `%25XX`,
+ * so a destination an author already encoded survives a round trip; a
+ * lone `%` that does not begin an octet is encoded. Sanitizing and
+ * encoding are separate steps on purpose — encode what
+ * {@link sanitizeUrl} returned, never the other way around, or an
+ * unsafe scheme could hide behind an escape.
+ *
+ * @param {string} url a URL that has already passed a sanitizer
+ * @returns {string} the attribute-ready URL
+ */
+export function encodeUrlAttribute(url) {
+  let out = '';
+  for (let i = 0; i < url.length; i++) {
+    const code = url.charCodeAt(i);
+    if (code < 128 && URL_LITERAL[code] === 1) {
+      out += url[i];
+      continue;
+    }
+    if (code === 0x25 /* % */ && RE_PCT_OCTET.test(url.slice(i, i + 3))) {
+      out += url.slice(i, i + 3);
+      i += 2;
+      continue;
+    }
+    // one code POINT: a surrogate pair is one UTF-8 sequence, and
+    // encoding its halves separately would emit two invalid ones
+    const point = url.codePointAt(i);
+    const char = String.fromCodePoint(/** @type {number} */ (point));
+    i += char.length - 1;
+    for (const byte of new TextEncoder().encode(char))
+      out += '%' + byte.toString(16).toUpperCase().padStart(2, '0');
+  }
+  return out;
+}