@jarenjs/view 0.34.0

package/src/html.js

@@ -0,0 +1,197 @@
+//@ts-check
+/**
+ * @file Server-side rendering: vnode JSON → HTML string.
+ *
+ * No DOM, no state — a pure fold over the vnode tree, usable anywhere
+ * (Node, workers, edge runtimes). `on` bindings and `key`s are renderer
+ * instructions and produce no markup; hydration is a client-side
+ * re-render into the same container (see docs/VIEW-FORMAT.md §6). A
+ * `jaren-widget` vnode serializes its host element around the widget's
+ * declarative `ssr` fallback (§7) — still pure, no widget is mounted.
+ */
+
+import {
+  isTextNode,
+  isElementNode,
+  propsOf,
+  childrenOf,
+  WIDGET_TAG,
+} from './vnode.js';
+import { styleToString } from './dom.js';
+import { createSafePolicy } from './safe.js';
+
+/** Void elements per the HTML standard: no children, no end tag. */
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+/** Props that never serialize to markup. */
+const SKIP_PROPS = new Set(['key', 'on', 'memo']);
+
+/** Widget-vnode props that configure the widget, not the host element. */
+const WIDGET_SKIP_PROPS = new Set(['key', 'on', 'memo', 'name', 'props', 'tag']);
+
+/**
+ * Escape text content: `&`, `<`, `>`.
+ * @param {string} text
+ * @returns {string}
+ */
+export function escapeText(text) {
+  return text.replace(/[&<>]/g, (ch) => (
+    ch === '&' ? '&amp;' : ch === '<' ? '&lt;' : '&gt;'
+  ));
+}
+
+/**
+ * Escape a double-quoted attribute value: `&`, `"`.
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeAttribute(value) {
+  return value.replace(/[&"]/g, (ch) => (ch === '&' ? '&amp;' : '&quot;'));
+}
+
+/**
+ * Serialize a props object to an attribute string over a skip set.
+ *
+ * The attribute NAME is trusted here: in the default (trusted) mode it comes
+ * from a source-authored stylesheet, so it is emitted as written. Under a
+ * safe `policy` it is not trusted — the policy rejects an injection-shaped
+ * name and sanitizes a URL value, which is what stops `{ 'x onfocus': … }`
+ * from breaking out of the attribute list. The policy is the same object the
+ * DOM renderer uses, so the two strip an attack identically.
+ * @param {Record<string, any>} props
+ * @param {Set<string>} skip
+ * @param {import('./safe.js').SafePolicy | null} policy
+ * @returns {string}
+ */
+function serializeProps(props, skip, policy, onUnsafe) {
+  let out = '';
+  for (const name in props) {
+    if (skip.has(name)) continue;
+    let attr = name;
+    let value = props[name];
+    if (policy !== null) {
+      const decided = policy.prop(attr, value);
+      // Omit a rejected NAME or a cleared VALUE. Omission — not an empty
+      // attribute — is what the DOM renderer's `removeAttribute` also does in
+      // safe mode, so the two outputs match.
+      if (decided === null || decided.value === null) {
+        if (onUnsafe !== null) onUnsafe({ kind: 'prop', name });
+        continue;
+      }
+      attr = decided.name;
+      value = decided.value;
+    }
+    if (value == null || value === false) continue;
+    if (attr === 'style' && typeof value === 'object') {
+      value = styleToString(value);
+      if (value === '') continue;
+    }
+    out += value === true
+      ? ' ' + attr
+      : ' ' + attr + '="' + escapeAttribute(String(value)) + '"';
+  }
+  return out;
+}
+
+/**
+ * @typedef {Object} RenderToStringOptions
+ * @property {Record<string, { ssr?: (props: any) => any }>} [widgets] -
+ *   Registered widget definitions by name: a `jaren-widget` vnode
+ *   serializes its host element around the widget's `ssr(props)` vnode
+ *   when the widget is registered and has one, else empty
+ *   (VIEW-FORMAT §7).
+ * @property {boolean} [safe=false] - Serialize under the SAFE policy
+ *   ({@link createSafePolicy}): treat the vnode as untrusted. Disallowed
+ *   tags, scripting-sink and inline `on*` properties, injection-shaped tag
+ *   and attribute names, and unsafe URLs are stripped, and widget vnodes are
+ *   dropped. This is the SAME policy {@link createDomRenderer} applies, so a
+ *   document renders to the same safe markup on the server as on the client.
+ * @property {(info: { kind: 'tag' | 'prop' | 'event' | 'widget', name: string }) => void}
+ *   [onUnsafe] - In safe mode, called for everything stripped: a `tag`, a
+ *   `prop`, an `on` binding (`event`) or a `widget`.
+ */
+
+/**
+ * Render a vnode JSON document to an HTML string.
+ *
+ * @example
+ * renderToString(['p', { class: 'note' }, 'a < b'])
+ * // -> '<p class="note">a &lt; b</p>'
+ *
+ * @param {any} vnode
+ * @param {RenderToStringOptions} [options]
+ * @returns {string}
+ */
+export function renderToString(vnode, options = {}) {
+  const policy = options.safe ? createSafePolicy() : null;
+  const onUnsafe = typeof options.onUnsafe === 'function' ? options.onUnsafe : null;
+  return renderNode(vnode, options.widgets, policy, onUnsafe);
+}
+
+/**
+ * The recursive fold. The policy (or null) and the report sink are carried
+ * rather than rebuilt per node, so a `safe: true` document constructs one
+ * policy for the whole tree.
+ * @param {any} vnode
+ * @param {Record<string, { ssr?: (props: any) => any }> | undefined} widgets
+ * @param {import('./safe.js').SafePolicy | null} policy
+ * @param {((info: { kind: string, name: string }) => void) | null} onUnsafe
+ * @returns {string}
+ */
+function renderNode(vnode, widgets, policy, onUnsafe) {
+  if (isTextNode(vnode)) {
+    return escapeText(String(vnode));
+  }
+  if (!isElementNode(vnode)) {
+    return '';
+  }
+  const tag = vnode[0];
+  const props = propsOf(vnode);
+  if (tag === WIDGET_TAG) {
+    // A widget is arbitrary imperative JS. In safe mode an untrusted document
+    // must not mount one, so it drops to nothing — the same nothing the DOM
+    // renderer produces for a widget in safe mode.
+    if (policy !== null) {
+      if (onUnsafe !== null) onUnsafe({ kind: 'widget', name: String(props.name ?? '') });
+      return '';
+    }
+    const hostTag = typeof props.tag === 'string' && props.tag !== '' ? props.tag : 'div';
+    const def = widgets !== undefined && typeof props.name === 'string'
+      && Object.hasOwn(widgets, props.name) ? widgets[props.name] : undefined;
+    // one read: acquisition and invocation are one boundary here too —
+    // renderToString is pure and offers no isolation, so a hostile
+    // `ssr` accessor propagates to the caller exactly like a throwing
+    // `ssr()` (the documented behavior for both)
+    const ssr = def !== undefined ? def.ssr : undefined;
+    const inner = ssr !== undefined
+      ? renderNode(ssr.call(def, props.props ?? null), widgets, policy, onUnsafe)
+      : '';
+    return '<' + hostTag + serializeProps(props, WIDGET_SKIP_PROPS, policy, onUnsafe) + '>'
+      + inner + '</' + hostTag + '>';
+  }
+  // Safe mode: a disallowed or injection-shaped tag drops to the empty
+  // string, matching the DOM renderer's empty text node.
+  if (policy !== null && policy.tag(tag) === null) {
+    if (onUnsafe !== null) onUnsafe({ kind: 'tag', name: String(tag) });
+    return '';
+  }
+  // Report a stripped `on` binding for observability parity with the DOM
+  // renderer — SSR never emits `on`, but a host still wants to know an
+  // untrusted document tried to bind an action.
+  if (policy !== null && onUnsafe !== null && props.on !== undefined) {
+    onUnsafe({ kind: 'event', name: 'on' });
+  }
+  let out = '<' + tag + serializeProps(props, SKIP_PROPS, policy, onUnsafe);
+  if (VOID_ELEMENTS.has(tag)) {
+    return out + '>';
+  }
+  out += '>';
+  const children = childrenOf(vnode);
+  for (let i = 0; i < children.length; i++) {
+    out += renderNode(children[i], widgets, policy, onUnsafe);
+  }
+  return out + '</' + tag + '>';
+}

package/src/index.js

@@ -0,0 +1,34 @@
+//@ts-check
+/**
+ * @file @jarenjs/view — the vnode JSON contract, the keyed DOM patcher
+ * and the SSR string renderer. See README.md and docs/VIEW-FORMAT.md.
+ */
+
+export {
+  EMPTY_PROPS,
+  WIDGET_TAG,
+  h,
+  isTextNode,
+  isElementNode,
+  isSkippedNode,
+  isSameNode,
+  isWidgetNode,
+  propsOf,
+  keyOf,
+  childrenOf,
+} from './vnode.js';
+
+export {
+  createDomRenderer,
+  styleToString,
+} from './dom.js';
+
+export {
+  renderToString,
+  escapeText,
+  escapeAttribute,
+} from './html.js';
+
+export {
+  createSafePolicy,
+} from './safe.js';

package/src/safe.js

@@ -0,0 +1,278 @@
+//@ts-check
+/**
+ * @file The safe render policy: one decision surface for untrusted vnodes,
+ * shared by the DOM renderer and the SSR serializer so the two can never
+ * disagree about what is safe.
+ *
+ * **Why this exists.** A vnode is plain JSON, and the published grammar
+ * ([`jaren-vnode.schema.json`](../schemas/jaren-vnode.schema.json)) proves a
+ * document is a well-formed *interface* — it does not prove the document is
+ * *safe to render*. The default (trusted) renderer writes any DOM property a
+ * node has, including `innerHTML` and inline `on*` handlers, and the SSR
+ * serializer trusts the tag and attribute *names* it is given. For a
+ * source-authored view that is exactly right — it is the equivalent of
+ * writing the DOM by hand. For a view that arrives from somewhere you do not
+ * control — a tenant, a remote service, a language model — it is not: a
+ * schema-valid document can still carry `['div', { innerHTML: '<img
+ * onerror=…>' }]` or a tag spelled `div><script>`.
+ *
+ * Schema validation is a structural gate, not a sanitizer. This module is the
+ * sanitizer. Pass `{ safe: true }` to {@link createDomRenderer} or
+ * {@link renderToString} and every element flows through the decisions here:
+ *
+ *  - **Tags** must be on an allow-list of known-inert HTML and SVG elements.
+ *    `script`, `iframe`, `object`, `style`, `link`, `foreignObject` and the
+ *    rest are dropped, and so is any tag whose *name* is not a bare
+ *    identifier — which is what closes structural injection through the tag
+ *    (`'div><img src=x onerror=alert(1)'`).
+ *  - **Property names** must be bare identifiers too (closing attribute-name
+ *    injection like `'x onfocus'`), must not begin with `on` (no inline
+ *    handlers), and must not be a known scripting sink (`innerHTML`,
+ *    `outerHTML`, `srcdoc`, …).
+ *  - **URL attributes** (`href`, `src`, `action`, …) are filtered through the
+ *    deny-list {@link sanitizeUrl}, so `javascript:` and a document-carrying
+ *    `data:` are dropped while ordinary links survive.
+ *  - **Inline `style`** is dropped when it carries the classic CSS vectors
+ *    (`expression(`, or a `url()` with a script scheme).
+ *  - **Event bindings** (`on`) are dropped: an untrusted document must not be
+ *    able to bind the host's application actions. Safe-mode views are
+ *    display-oriented by construction.
+ *
+ * The policy is a set of pure decisions. The DOM renderer and the SSR
+ * serializer call the *same* functions, which is what guarantees the client
+ * and the server neutralize an attack identically.
+ */
+
+import { sanitizeUrl } from './helpers/url.js';
+
+/** A tag or property name that is a bare identifier: a letter, then letters,
+ * digits or hyphens. No spaces, `>`, `=`, `/`, colons or quotes — the
+ * characters every structural-injection payload needs. */
+const RE_SAFE_NAME = /^[A-Za-z][A-Za-z0-9-]*$/;
+
+/**
+ * The HTML elements a user interface legitimately renders. An allow-list, not
+ * a deny-list, because a deny-list silently admits the next dangerous element
+ * a browser adds. Document structure (`html`, `head`, `body`, `title`),
+ * script and style carriers (`script`, `style`, `link`, `meta`, `base`,
+ * `noscript`, `template`), and document-embedding elements (`iframe`,
+ * `object`, `embed`, `frame`, `frameset`, `portal`) are all absent by design.
+ */
+const SAFE_HTML_TAGS = new Set([
+  // sectioning & grouping
+  'main', 'section', 'article', 'aside', 'nav', 'header', 'footer', 'hgroup',
+  'address', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'div', 'p', 'hr', 'pre', 'blockquote', 'ol', 'ul', 'li', 'dl', 'dt', 'dd',
+  'figure', 'figcaption', 'menu',
+  // text-level
+  'a', 'span', 'strong', 'em', 'b', 'i', 'u', 's', 'small', 'mark', 'abbr',
+  'cite', 'q', 'code', 'kbd', 'samp', 'var', 'sub', 'sup', 'time', 'data',
+  'wbr', 'br', 'bdi', 'bdo', 'ruby', 'rt', 'rp', 'dfn', 'ins', 'del',
+  // tables
+  'table', 'caption', 'colgroup', 'col', 'thead', 'tbody', 'tfoot',
+  'tr', 'td', 'th',
+  // forms
+  'form', 'label', 'input', 'button', 'select', 'option', 'optgroup',
+  'textarea', 'fieldset', 'legend', 'datalist', 'output', 'progress', 'meter',
+  // media & embedded (URL-bearing attributes are sanitized separately)
+  'img', 'picture', 'source', 'audio', 'video', 'track', 'canvas',
+  // interactive
+  'details', 'summary', 'dialog',
+]);
+
+/**
+ * The SVG drawing subset. `foreignObject` is excluded — it re-enters HTML and
+ * would reopen every vector above — and so are `script` and the event-bearing
+ * SMIL elements.
+ */
+const SAFE_SVG_TAGS = new Set([
+  'svg', 'g', 'defs', 'symbol', 'use', 'marker', 'mask', 'clipPath', 'pattern',
+  'path', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon',
+  'text', 'tspan', 'textPath', 'image',
+  'linearGradient', 'radialGradient', 'stop',
+  'title', 'desc',
+]);
+
+/** Property names denied outright: the sinks that PARSE their value as HTML.
+ * `textContent`/`innerText` are deliberately absent — they set text, which a
+ * browser escapes, so they are not injection vectors. Compared
+ * case-insensitively. */
+const DANGEROUS_PROPS = new Set([
+  'innerhtml', 'outerhtml', 'insertadjacenthtml',
+  'dangerouslysetinnerhtml', 'srcdoc',
+]);
+
+/** Attributes whose value is a single URL, filtered through the deny-list
+ * sanitizer. Compared case-insensitively. */
+const URL_ATTRS = new Set([
+  'href', 'src', 'action', 'formaction', 'poster', 'background',
+  'cite', 'longdesc', 'data',
+]);
+
+/** Attributes whose value is a URL *list*: `srcset` is comma-separated
+ * `url descriptor` candidates, `ping` is a whitespace-separated URL list.
+ * Running the whole string through a single-URL check would miss an unsafe
+ * candidate after the first, so each is parsed and every URL is sanitized. */
+const URL_LIST_ATTRS = new Set(['srcset', 'ping']);
+
+/** Inline-style values that carry a CSS execution vector. */
+const RE_DANGEROUS_STYLE = /expression\s*\(|url\s*\(\s*['"]?\s*(?:javascript|vbscript|data):/i;
+
+/** A CSS property name a safe style object may carry: a plain identifier or a
+ * `--custom-property`. A key with `:`, `;`, `(` or whitespace is not a
+ * property name — it is a declaration smuggled through the key, which is how
+ * `styleToString` concatenation turns `{ 'x:url(javascript:…)': 'y' }` into a
+ * live rule. */
+const RE_SAFE_STYLE_KEY = /^(?:--[A-Za-z0-9-]+|[A-Za-z][A-Za-z0-9-]*)$/;
+
+/**
+ * @typedef {Object} SafePolicy
+ * @property {(tag: string) => string | null} tag - The tag to render, or
+ *   `null` to drop the element and its subtree.
+ * @property {(name: string, value: any) => { name: string, value: any } | null}
+ *   prop - The name/value to write, `{ name, value: null }` to clear an
+ *   existing attribute (a sanitized-away URL, a dangerous style), or `null` to
+ *   drop the property entirely (a rejected name).
+ * @property {boolean} dropsEvents - Whether `on` bindings are stripped (always
+ *   true for the default policy; the renderers read this to skip the `on`
+ *   path in safe mode).
+ */
+
+/**
+ * Build the default safe policy. Stateless and cheap; a renderer builds one
+ * per `safe: true` and hands the *same* object to every element it renders.
+ *
+ * The policy is a set of **pure decisions** — it neither writes nor reports.
+ * The renderer owns `onUnsafe` and reports at the point it acts on a
+ * rejection, which is what lets it report the strips a policy never sees (an
+ * `on` binding, a widget) with one contract.
+ * @returns {SafePolicy}
+ */
+export function createSafePolicy() {
+  return {
+    dropsEvents: true,
+
+    tag(tag) {
+      if (typeof tag === 'string' && RE_SAFE_NAME.test(tag)
+        && (SAFE_HTML_TAGS.has(tag) || SAFE_SVG_TAGS.has(tag))) {
+        return tag;
+      }
+      return null;
+    },
+
+    prop(name, value) {
+      const lower = name.toLowerCase();
+      // A name that is not a bare identifier is structural injection, whatever
+      // it spells: reject before it can reach a serializer or a DOM property.
+      // `is` is a bare identifier but a capability escape: it upgrades an
+      // element to a registered customized built-in when the markup is
+      // PARSED (an untrusted document's safe SSR would run a host-registered
+      // constructor), so it is denied outright.
+      if (!RE_SAFE_NAME.test(name) || lower.startsWith('on')
+        || lower === 'is' || DANGEROUS_PROPS.has(lower)) {
+        return null;
+      }
+      if (URL_ATTRS.has(lower)) {
+        const safe = sanitizeUrl(value);
+        // Keep the (safe) name but clear the value when the URL is unsafe: a
+        // patch from a good URL to a bad one must remove the old attribute.
+        return { name, value: safe };
+      }
+      if (URL_LIST_ATTRS.has(lower)) {
+        return { name, value: sanitizeUrlList(value, lower === 'srcset') };
+      }
+      if (lower === 'style') {
+        return { name, value: safeStyle(value) };
+      }
+      return { name, value };
+    },
+  };
+}
+
+/**
+ * Sanitize a URL-list attribute. Every candidate's URL is checked; a single
+ * unsafe candidate drops the whole attribute, because a browser would still
+ * act on the safe ones around it and the intent is already hostile.
+ * @param {any} value
+ * @param {boolean} isSrcset - `srcset` (a candidate list) vs `ping`
+ *   (whitespace-separated URLs)
+ * @returns {string | null}
+ */
+function sanitizeUrlList(value, isSrcset) {
+  if (typeof value !== 'string') return null;
+  if (!isSrcset) {
+    const urls = value.split(/\s+/).filter((u) => u !== '');
+    for (const url of urls) if (sanitizeUrl(url) === null) return null;
+    return urls.length > 0 ? urls.join(' ') : null;
+  }
+  const candidates = parseSrcset(value);
+  if (candidates === null) return null;
+  const out = [];
+  for (const { url, descriptor } of candidates) {
+    if (sanitizeUrl(url) === null) return null;
+    out.push(descriptor === '' ? url : `${url} ${descriptor}`);
+  }
+  return out.length > 0 ? out.join(', ') : null;
+}
+
+/**
+ * Parse an `srcset` into `{ url, descriptor }` candidates. A candidate's URL
+ * runs up to the next ASCII whitespace, so a comma INSIDE a URL — a `data:`
+ * image is full of them — stays part of the URL rather than splitting it,
+ * which the naive comma-split got wrong. Follows the shape of the HTML srcset
+ * algorithm closely enough to validate every URL; the descriptor is opaque to
+ * a safety check.
+ * @param {string} s
+ * @returns {Array<{ url: string, descriptor: string }> | null}
+ */
+function parseSrcset(s) {
+  const isWs = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\f' || c === '\r';
+  const out = [];
+  let i = 0;
+  while (i < s.length) {
+    while (i < s.length && (isWs(s[i]) || s[i] === ',')) i++;
+    if (i >= s.length) break;
+    let url = '';
+    while (i < s.length && !isWs(s[i])) { url += s[i]; i++; }
+    // trailing commas on the URL are candidate separators, not part of it.
+    let hadTrailingComma = false;
+    while (url.endsWith(',')) { url = url.slice(0, -1); hadTrailingComma = true; }
+    let descriptor = '';
+    if (!hadTrailingComma) {
+      while (i < s.length && isWs(s[i])) i++;
+      while (i < s.length && s[i] !== ',') { descriptor += s[i]; i++; }
+      if (i < s.length) i++; // consume the separating comma
+    }
+    if (url !== '') out.push({ url, descriptor: descriptor.trim() });
+  }
+  return out.length > 0 ? out : null;
+}
+
+/**
+ * The safe form of an inline-style value: `null` when it carries a CSS
+ * execution vector or an injection-shaped property name, otherwise the value
+ * unchanged (a string, or an object the renderer will serialize). Both the
+ * KEYS and the values are checked — a payload smuggled through an object key
+ * survives `styleToString`'s concatenation otherwise.
+ * @param {any} value
+ * @returns {any}
+ */
+function safeStyle(value) {
+  if (typeof value === 'string') {
+    return RE_DANGEROUS_STYLE.test(value) ? null : value;
+  }
+  if (value !== null && typeof value === 'object') {
+    for (const key in value) {
+      if (!RE_SAFE_STYLE_KEY.test(key) || RE_DANGEROUS_STYLE.test(key)) return null;
+      const v = value[key];
+      if (typeof v === 'string' && RE_DANGEROUS_STYLE.test(v)) return null;
+    }
+    return value;
+  }
+  return value;
+}
+
+export {
+  SAFE_HTML_TAGS, SAFE_SVG_TAGS, DANGEROUS_PROPS,
+  URL_ATTRS, URL_LIST_ATTRS, RE_SAFE_NAME,
+};

package/src/vnode.js

@@ -0,0 +1,170 @@
+//@ts-check
+/**
+ * @file The Jaren vnode contract — the JSON vocabulary for user interfaces.
+ *
+ * A vnode is a plain JSON value, designed to be the *output* of a JSLT
+ * stylesheet (`@jarenjs/json/jslt`) the way HTML is the output of XSLT:
+ *
+ *  - text:    a `string` or a `number` (rendered as `String(value)`)
+ *  - element: an array whose first item is a string tag:
+ *             `[tag, props?, ...children]`
+ *  - list:    an array whose first item is NOT a string — spliced into the
+ *             parent's children in place (the natural shape of a JSLT
+ *             `[{ "$apply": ... }]` body)
+ *  - skipped: `null`, `undefined`, `true` and `false` render nothing
+ *             (so `{"$if": ...}` bodies compose without wrappers)
+ *
+ * The second item of an element is its props object when it is a plain
+ * object; otherwise it is the first child. Recognized special props:
+ *
+ *  - `key`   — reconciliation identity for keyed children (never rendered)
+ *  - `on`    — `{ [eventType]: binding }`; the binding is opaque JSON handed
+ *              to the renderer's `onEvent` hook (in `@jarenjs/app`: an
+ *              action name or `{ "action": name, "with": payload }`)
+ *  - `style` — a CSS string or an object of declarations
+ *
+ * Everything in this module is allocation-light and does no validation
+ * beyond shape dispatch: the vnode grammar is published as JSON Schema in
+ * `schemas/jaren-vnode.schema.json` for validating untrusted documents.
+ */
+
+import { isJsonObject } from '@jarenjs/core/object';
+
+/** Frozen empty props object shared by all prop-less elements. */
+export const EMPTY_PROPS = Object.freeze({});
+
+/**
+ * The reserved widget tag (VIEW-FORMAT §7). A valid custom-element name,
+ * so a renderer that predates the widget vocabulary degrades to an inert,
+ * harmless element — and the dash makes collision with real HTML tags
+ * impossible. (`$widget` is impossible: in query/JSLT rule bodies a
+ * string leaf starting with `$` is a path expression.)
+ */
+export const WIDGET_TAG = 'jaren-widget';
+
+/**
+ * A vnode JSON value.
+ * @typedef {string | number | boolean | null | undefined | VNodeElement | VNodeJson[]} VNodeJson
+ */
+/**
+ * An element vnode: `[tag, props?, ...children]`.
+ * @typedef {Array<any>} VNodeElement
+ */
+
+/**
+ * Is this vnode a text node (string or finite number)?
+ * @param {any} vnode
+ * @returns {vnode is string | number}
+ */
+export function isTextNode(vnode) {
+  const t = typeof vnode;
+  return t === 'string' || t === 'number';
+}
+
+/**
+ * Is this vnode an element (`[tag, ...]` with a string tag)?
+ * @param {any} vnode
+ * @returns {vnode is VNodeElement}
+ */
+export function isElementNode(vnode) {
+  return Array.isArray(vnode) && typeof vnode[0] === 'string';
+}
+
+/**
+ * Is this value skipped by the renderer (`null`/`undefined`/booleans)?
+ * @param {any} vnode
+ * @returns {boolean}
+ */
+export function isSkippedNode(vnode) {
+  return vnode == null || vnode === true || vnode === false;
+}
+
+/**
+ * Is this vnode a widget node (`["jaren-widget", props]`, VIEW-FORMAT §7)?
+ * @param {any} vnode
+ * @returns {vnode is VNodeElement}
+ */
+export function isWidgetNode(vnode) {
+  return Array.isArray(vnode) && vnode[0] === WIDGET_TAG;
+}
+
+/**
+ * The props of an element vnode; `EMPTY_PROPS` when it has none.
+ * @param {VNodeElement} vnode
+ * @returns {Record<string, any>}
+ */
+export function propsOf(vnode) {
+  const second = vnode.length > 1 ? vnode[1] : undefined;
+  return isJsonObject(second) ? second : EMPTY_PROPS;
+}
+
+/**
+ * The reconciliation key of an element vnode, or `undefined`.
+ * @param {any} vnode
+ * @returns {string | number | undefined}
+ */
+export function keyOf(vnode) {
+  return isElementNode(vnode) ? propsOf(vnode).key : undefined;
+}
+
+/**
+ * The renderable children of an element vnode as a flat array: nested
+ * lists are spliced in place, skipped values are dropped.
+ * @param {VNodeElement} vnode
+ * @returns {VNodeJson[]}
+ */
+export function childrenOf(vnode) {
+  const start = vnode.length > 1 && isJsonObject(vnode[1]) ? 2 : 1;
+  /** @type {VNodeJson[]} */
+  const out = [];
+  for (let i = start; i < vnode.length; i++) {
+    appendChild(out, vnode[i]);
+  }
+  return out;
+}
+
+/**
+ * Append one child value to `out`, splicing lists and dropping skipped
+ * values.
+ * @param {VNodeJson[]} out
+ * @param {any} child
+ */
+function appendChild(out, child) {
+  if (isSkippedNode(child)) return;
+  if (Array.isArray(child) && typeof child[0] !== 'string') {
+    for (let i = 0; i < child.length; i++) appendChild(out, child[i]);
+    return;
+  }
+  out.push(child);
+}
+
+/**
+ * Convenience element constructor for JavaScript-side views and tests —
+ * produces the same JSON an authored stylesheet would.
+ *
+ * @example
+ * h('li', { key: 7, class: 'todo' }, 'Buy milk')
+ * // -> ['li', { key: 7, class: 'todo' }, 'Buy milk']
+ *
+ * @param {string} tag
+ * @param {Record<string, any>} [props]
+ * @param {...any} children
+ * @returns {VNodeElement}
+ */
+export function h(tag, props, ...children) {
+  return [tag, props ?? EMPTY_PROPS, ...children];
+}
+
+/**
+ * Two vnodes are "the same node" for reconciliation when a patch in place
+ * is possible: both text, or elements with equal tag and equal key.
+ * @param {VNodeJson} a
+ * @param {VNodeJson} b
+ * @returns {boolean}
+ */
+export function isSameNode(a, b) {
+  if (isTextNode(a)) return isTextNode(b);
+  if (isTextNode(b)) return false;
+  return /** @type {VNodeElement} */ (a)[0] === /** @type {VNodeElement} */ (b)[0]
+    && keyOf(a) === keyOf(b);
+}