@marianmeres/safe-html 0.2.0

package/dist/trusted.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The brand. Trusted values carry `Symbol.for` keys, so JSON or database rows can never pass as
+ * trusted, and values stay recognized across duplicate copies of the package in one process.
+ */
+import type { Trusted, TrustedKind } from "./types.js";
+declare const VALUE: unique symbol;
+declare const NEUTRAL: unique symbol;
+/**
+ * The implementation. State lives in private fields behind getters, so a value is immutable
+ * without the cost of `Object.freeze` (there is no setter, and nothing outside this class can
+ * reach the fields). Exported for fast `instanceof` checks; values from another copy of the
+ * package are recognized through the `Symbol.for` keys instead.
+ */
+export declare class TrustedValue<K extends TrustedKind = TrustedKind> implements Trusted<K> {
+    #private;
+    constructor(kind: K, value: string, neutral: boolean);
+    get kind(): K;
+    get [VALUE](): string;
+    get [NEUTRAL](): boolean;
+    toString(): string;
+    toJSON(): string;
+    [Symbol.toPrimitive](): string;
+}
+/**
+ * Creates a trusted value. `neutral` (html only) marks markup that parses the same inside
+ * `<svg>`/`<math>` as in HTML (see scanner.ts).
+ */
+export declare function makeTrusted<K extends TrustedKind>(kind: K, value: string, neutral?: boolean): Trusted<K>;
+/** Is `v` a value produced by this package (optionally, of the given kind)? */
+export declare function isTrusted<K extends TrustedKind>(v: unknown, kind?: K): v is Trusted<K>;
+/** The string of a value already known to be trusted. */
+export declare function trustedString(v: Trusted): string;
+/** Whether trusted markup may be placed into SVG/MathML text. */
+export declare function isNeutral(v: Trusted): boolean;
+export {};

package/dist/trusted.js

@@ -0,0 +1,68 @@
+const BRAND = Symbol.for("@marianmeres/safe-html/brand");
+const VALUE = Symbol.for("@marianmeres/safe-html/value");
+const NEUTRAL = Symbol.for("@marianmeres/safe-html/neutral");
+/**
+ * The implementation. State lives in private fields behind getters, so a value is immutable
+ * without the cost of `Object.freeze` (there is no setter, and nothing outside this class can
+ * reach the fields). Exported for fast `instanceof` checks; values from another copy of the
+ * package are recognized through the `Symbol.for` keys instead.
+ */
+export class TrustedValue {
+    #kind;
+    #value;
+    #neutral;
+    constructor(kind, value, neutral) {
+        this.#kind = kind;
+        this.#value = value;
+        this.#neutral = neutral;
+    }
+    get kind() {
+        return this.#kind;
+    }
+    get [VALUE]() {
+        return this.#value;
+    }
+    get [NEUTRAL]() {
+        return this.#neutral;
+    }
+    toString() {
+        return this.#value;
+    }
+    toJSON() {
+        return this.#value;
+    }
+    [Symbol.toPrimitive]() {
+        return this.#value;
+    }
+}
+Object.defineProperty(TrustedValue.prototype, BRAND, { value: true });
+Object.freeze(TrustedValue.prototype);
+/**
+ * Creates a trusted value. `neutral` (html only) marks markup that parses the same inside
+ * `<svg>`/`<math>` as in HTML (see scanner.ts).
+ */
+export function makeTrusted(kind, value, neutral = false) {
+    return new TrustedValue(kind, value, neutral);
+}
+/** Is `v` a value produced by this package (optionally, of the given kind)? */
+export function isTrusted(v, kind) {
+    if (v instanceof TrustedValue)
+        return kind === undefined || v.kind === kind;
+    return (typeof v === "object" &&
+        v !== null &&
+        // deno-lint-ignore no-explicit-any
+        v[BRAND] === true &&
+        // deno-lint-ignore no-explicit-any
+        typeof v[VALUE] === "string" &&
+        (kind === undefined || v.kind === kind));
+}
+/** The string of a value already known to be trusted. */
+export function trustedString(v) {
+    // deno-lint-ignore no-explicit-any
+    return v[VALUE];
+}
+/** Whether trusted markup may be placed into SVG/MathML text. */
+export function isNeutral(v) {
+    // deno-lint-ignore no-explicit-any
+    return v[NEUTRAL] === true;
+}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared public types.
+ */
+/** The kinds of trusted value this package produces. */
+export type TrustedKind = "html" | "attrs" | "url" | "srcset" | "json" | "js" | "css" | "unsafe";
+/**
+ * An immutable, branded value produced by this package. `String(v)`, `v.toString()` and
+ * `JSON.stringify(v)` give its string.
+ */
+export interface Trusted<K extends TrustedKind = TrustedKind> {
+    /** Which helper produced the value; decides where it may be interpolated. */
+    readonly kind: K;
+    /** The string. */
+    toString(): string;
+    /** The string, so `JSON.stringify` serializes the value as a plain string. */
+    toJSON(): string;
+}
+/** Markup built by `html` or `join()`. */
+export type SafeHtml = Trusted<"html">;
+/** An attribute list built by `attrs()`. */
+export type SafeAttrs = Trusted<"attrs">;
+/** A scheme-vetted (not escaped) URL built by `url()`. */
+export type SafeUrl = Trusted<"url">;
+/** A vetted (not escaped) `srcset` value built by `srcset()`. */
+export type SafeSrcset = Trusted<"srcset">;
+/** What may be interpolated into `html`. Anything else is a type error and a runtime error. */
+export type Renderable = Trusted | string | number | bigint | boolean | null | undefined | readonly Renderable[];
+/** A value accepted by `attrs()`. */
+export type AttrValue = string | number | bigint | boolean | null | undefined | Trusted<"url" | "srcset" | "unsafe">;
+/** One `srcset` candidate. */
+export interface SrcsetCandidate {
+    /** Checked against the URL policy unless it is a `SafeUrl`. */
+    url: string | SafeUrl;
+    /** `"2x"`, `"1.5x"`, `"800w"`. Omitted means `1x`. */
+    descriptor?: string;
+}
+/**
+ * Where a slot sits in the template, as worked out from the static markup.
+ *
+ * - `text`: element content.
+ * - `rcdata`: content of `<title>` or `<textarea>` (text only, no markup).
+ * - `attr-list`: inside a start tag, where an attribute may begin.
+ * - `attr-value`: inside a quoted attribute value.
+ * - `url`: a URL attribute value that the slot starts.
+ * - `srcset`: a `srcset` / `imagesrcset` value.
+ * - `script`: `<script>` raw text.
+ * - `style`: `<style>` raw text.
+ */
+export type SlotContext = "text" | "rcdata" | "attr-list" | "attr-value" | "url" | "srcset" | "script" | "style";
+/** Passed to `HtmlOptions.onBlockedUrl`. */
+export interface BlockedUrlInfo {
+    /** The URL as given. */
+    url: string;
+    /** Lowercased tag name, when known. */
+    tag?: string;
+    /** Lowercased attribute name, when known. */
+    attribute?: string;
+}
+/** URL policy of a kit (see `createHtml`). */
+export interface HtmlOptions {
+    /**
+     * Allowed URL schemes, case-insensitive, without the colon.
+     * Default: `["http", "https", "mailto", "tel"]`.
+     */
+    urlSchemes?: readonly string[];
+    /** What a blocked URL renders as. Default: `"about:invalid#blocked"`. */
+    blockedUrl?: string;
+    /** Called once per blocked URL, e.g. to log a probe. May throw; that propagates. */
+    onBlockedUrl?: (info: BlockedUrlInfo) => void;
+}
+/** The URL-policy-bound part of the API. `createHtml()` returns one. */
+export interface HtmlKit {
+    /** The template tag. Every interpolated value is escaped for the place it appears. */
+    html(strings: TemplateStringsArray, ...values: Renderable[]): SafeHtml;
+    /** An attribute list for a slot in attribute-list position: `<button ${attrs({...})}>`. */
+    attrs(record: Readonly<Record<string, AttrValue>>): SafeAttrs;
+    /** Checks `value` against the scheme allowlist. `schemes` replaces the kit's list. */
+    url(value: string, options?: {
+        schemes?: readonly string[];
+    }): SafeUrl;
+    /** A `srcset` value. Blocked candidates are dropped. */
+    srcset(candidates: readonly SrcsetCandidate[]): SafeSrcset;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared public types.
+ */
+export {};

package/dist/url.d.ts

@@ -0,0 +1,30 @@
+/**
+ * URL policy: scheme allowlist. Blocked URLs are replaced, never thrown, so data can't make a
+ * render fail.
+ */
+import type { BlockedUrlInfo, HtmlOptions } from "./types.js";
+/** The default scheme allowlist. */
+export declare const DEFAULT_URL_SCHEMES: readonly string[];
+/** The default replacement for a blocked URL. */
+export declare const DEFAULT_BLOCKED_URL = "about:invalid#blocked";
+/** A kit's resolved URL policy. */
+export interface UrlPolicy {
+    readonly schemes: ReadonlySet<string>;
+    readonly blockedUrl: string;
+    readonly onBlockedUrl?: (info: BlockedUrlInfo) => void;
+}
+/** Leading C0 controls and space, which the URL parser strips. */
+export declare const LEADING_C0_SPACE: RegExp;
+/** Only C0 controls and space (stripped by the URL parser at either end). */
+export declare const ONLY_C0_SPACE: RegExp;
+/** Normalizes and validates a scheme list. Throws `TypeError` on a malformed entry (config). */
+export declare function normalizeSchemes(list: readonly string[]): ReadonlySet<string>;
+/** Resolves kit options into a policy. */
+export declare function createPolicy(options?: HtmlOptions): UrlPolicy;
+/** The lowercased scheme of `value` as a browser would parse it, or `null` if relative. */
+export declare function urlScheme(value: string): string | null;
+/**
+ * Returns `value` if relative or its scheme is allowed, otherwise `null` after reporting it.
+ * The result is not escaped.
+ */
+export declare function vetUrl(value: string, policy: UrlPolicy, tag?: string, attribute?: string, schemes?: ReadonlySet<string>): string | null;

package/dist/url.js

@@ -0,0 +1,93 @@
+/** The default scheme allowlist. */
+export const DEFAULT_URL_SCHEMES = Object.freeze([
+    "http",
+    "https",
+    "mailto",
+    "tel",
+]);
+/** The default replacement for a blocked URL. */
+export const DEFAULT_BLOCKED_URL = "about:invalid#blocked";
+const SCHEME_NAME = /^[a-z][a-z0-9+.-]*$/;
+/** Leading C0 controls and space, which the URL parser strips. */
+// deno-lint-ignore no-control-regex
+export const LEADING_C0_SPACE = /^[\x00-\x20]+/;
+/** Only C0 controls and space (stripped by the URL parser at either end). */
+// deno-lint-ignore no-control-regex
+export const ONLY_C0_SPACE = /^[\x00-\x20]*$/;
+/** Normalizes and validates a scheme list. Throws `TypeError` on a malformed entry (config). */
+export function normalizeSchemes(list) {
+    if (!Array.isArray(list)) {
+        throw new TypeError("urlSchemes must be an array of strings");
+    }
+    const out = new Set();
+    for (const entry of list) {
+        const s = typeof entry === "string"
+            ? entry.trim().toLowerCase().replace(/:$/, "")
+            : "";
+        if (!SCHEME_NAME.test(s)) {
+            throw new TypeError(`Invalid URL scheme in urlSchemes: ${JSON.stringify(entry)}`);
+        }
+        out.add(s);
+    }
+    return out;
+}
+/** Resolves kit options into a policy. */
+export function createPolicy(options = {}) {
+    const blockedUrl = options.blockedUrl ?? DEFAULT_BLOCKED_URL;
+    if (typeof blockedUrl !== "string") {
+        throw new TypeError("blockedUrl must be a string");
+    }
+    if (options.onBlockedUrl !== undefined && typeof options.onBlockedUrl !== "function") {
+        throw new TypeError("onBlockedUrl must be a function");
+    }
+    return Object.freeze({
+        schemes: normalizeSchemes(options.urlSchemes ?? DEFAULT_URL_SCHEMES),
+        blockedUrl,
+        onBlockedUrl: options.onBlockedUrl,
+    });
+}
+/** The lowercased scheme of `value` as a browser would parse it, or `null` if relative. */
+export function urlScheme(value) {
+    // the URL parser strips leading C0 controls and space, and removes tab/LF/CR anywhere;
+    // any other character ends the scheme
+    const n = value.length;
+    let i = 0;
+    while (i < n && value.charCodeAt(i) <= 0x20)
+        i++;
+    const start = i;
+    if (i >= n || !isAlpha(value.charCodeAt(i)))
+        return null;
+    let dirty = false;
+    for (i++; i < n; i++) {
+        const c = value.charCodeAt(i);
+        if (c === 58) { // ":"
+            const s = value.slice(start, i);
+            return (dirty ? s.replace(/[\t\n\r]/g, "") : s).toLowerCase();
+        }
+        if (c === 9 || c === 10 || c === 13)
+            dirty = true;
+        else if (!isAlpha(c) && !(c >= 48 && c <= 57) && c !== 43 && c !== 45 && c !== 46) {
+            return null; // not [A-Za-z0-9+.-]
+        }
+    }
+    return null;
+}
+const isAlpha = (c) => (c >= 65 && c <= 90) || (c >= 97 && c <= 122);
+/**
+ * Returns `value` if relative or its scheme is allowed, otherwise `null` after reporting it.
+ * The result is not escaped.
+ */
+export function vetUrl(value, policy, tag, attribute, schemes = policy.schemes) {
+    const scheme = urlScheme(value);
+    if (scheme === null || schemes.has(scheme))
+        return value;
+    if (policy.onBlockedUrl) {
+        const info = { url: value };
+        if (tag)
+            info.tag = tag;
+        if (attribute)
+            info.attribute = attribute;
+        policy.onBlockedUrl(info);
+    }
+    return null;
+}

package/docs/design.md

@@ -0,0 +1,346 @@
+# Design
+
+How `@marianmeres/safe-html` decides what is safe. This is the normative description of the
+implemented behavior; [API.md](../API.md) documents the functions.
+
+## 1. Model
+
+An `html` tagged template returns a trusted `SafeHtml`. Every interpolated value (a _slot_) is
+escaped for the place it appears. The place (the slot's _context_) is worked out from the
+template's **static strings only**, once per call site, and cached by template object. Slot
+positions that can never be made safe are rejected the first time the template renders,
+whatever the data.
+
+Two phases:
+
+1. **Analysis** (`src/scanner.ts`): a small model of the HTML tokenizer runs over the static
+   text and classifies every slot, or throws `HtmlTemplateError`. Depends on the template
+   only.
+2. **Rendering** (`src/render.ts`, `src/kit.ts`): each value is rendered under its slot's
+   context (§4), or `HtmlValueError` is thrown. Depends on the value's _type or trusted kind_,
+   never on the content of a string.
+
+## 2. Trust model
+
+- The static parts of a template are trusted: only code writes them, and `html` refuses
+  anything that is not a genuine (frozen) template object.
+- Interpolated values are untrusted unless they carry the package's brand: values made by
+  `html`, `join`, `attrs`, `url`, `srcset`, `jsonScript`, `scriptText`, `styleText` or
+  `unsafeRaw`.
+- The brand is a `Symbol.for(…)` key. JSON and database rows can't carry symbols, so parsed
+  or stored data can't pass as trusted. Code can forge a value, but code can call
+  `unsafeRaw()` anyway. `Symbol.for` keeps values recognized across duplicate copies of the
+  package in one process.
+- Trusted values are immutable: state lives in private class fields behind getters.
+
+**Guaranteed.** Given templates that pass analysis and no `unsafeRaw()`, no string value can:
+
+- create an element, attribute, comment or declaration;
+- close an element or attribute value that the template opened;
+- inject script through an event-handler attribute (those slots are rejected);
+- put a URL with a scheme outside the allowlist into a URL attribute (default: `http`,
+  `https`, `mailto`, `tel`), including through `srcset` or `attrs()`;
+- break out of `<script>`, `<style>`, `<title>` or `<textarea>` content;
+- change how SVG/MathML content parses.
+
+**Not guaranteed:**
+
+- CSS injection inside `style="…"` or `styleText()`. A value can't break out, but it can
+  restyle the page or load a `url(…)`. Build style values from validated tokens.
+- Semantic misuse: `<meta http-equiv="refresh" content="${x}">`, `<base href>` pointing at a
+  hostile `https:` host, open redirects, and `//host` protocol-relative URLs (relative, so
+  allowed).
+- Attributes that other code later treats as URLs or code: `data-src`, `data-href`, and
+  client-side frameworks that evaluate attributes or text (Alpine `x-*`, htmx `hx-on*`,
+  Vue/Angular template syntax in server-rendered markup). Don't interpolate data there.
+- DOM clobbering through data-controlled `id` or `name` values.
+- A slot inside a JavaScript string literal in a `<script>`. The scanner does not parse
+  JavaScript; `jsonScript()` output must be used as a whole JS expression.
+- URL component encoding: `href="/search?q=${q}"` is HTML-escaped, not
+  `encodeURIComponent`-ed. That is the caller's job.
+- Anything passed through `unsafeRaw()`.
+- Character encoding. Serve `content-type: text/html; charset=utf-8` and emit
+  `<meta charset="utf-8">`.
+
+## 3. Analysis
+
+The scan starts in text. A slot takes the context of the scanner state at that boundary; the
+scan then continues from the same state, because §4 guarantees no value can change it.
+
+### 3.1 States → contexts
+
+| Scanner state at the slot                                               | Example                                | Context              |
+| ----------------------------------------------------------------------- | -------------------------------------- | -------------------- |
+| Text content                                                            | `<p>${…}</p>`                          | `text`               |
+| `<title>`, `<textarea>` content (RCDATA)                                | `<title>${…}</title>`                  | `rcdata`             |
+| In a start tag where an attribute may begin                             | `<div ${…}>`, `<a href="x"${…}>`       | `attr-list`          |
+| Just after `<` or `</`, or in a tag name                                | `<${…}>`, `<h${…}>`                    | error                |
+| In an attribute name, or right after one with no whitespace             | `<div data-${…}="1">`, `<input a${…}>` | error                |
+| After `=`, or in an unquoted value                                      | `<a href=${…}>`, `<a href=x${…}>`      | error                |
+| In a `"…"` or `'…'` value                                               | `<p title="${…}">`                     | per attribute (§3.3) |
+| `<script>` raw text                                                     | `<script>${…}</script>`                | `script`             |
+| `<style>` raw text                                                      | `<style>${…}</style>`                  | `style`              |
+| `iframe`, `noembed`, `noframes`, `noscript`, `xmp`, `plaintext` content | `<noscript>${…}</noscript>`            | error                |
+| Comment, doctype, `<!…>`, `<?…>`, `</ …>`                               | `<!-- ${…} -->`                        | error                |
+| Inside an end tag                                                       | `</div ${…}>`                          | error                |
+| Right after `/` in a tag                                                | `<br/${…}>`                            | error                |
+
+Tokenizer details:
+
+- Tag and attribute names match case-insensitively and are stored lowercased.
+- `<script>`, `<style>`, `<title>`, `<textarea>` and the unsupported raw-text elements are
+  scanned to their end tag (`</name` followed by whitespace, `/` or `>`, case-insensitive),
+  including after `<script/>` (the self-closing flag is ignored on non-void elements).
+- A comment runs from `<!--` to `-->` or `--!>`; `<!-->` and `<!--->` are complete comments.
+  `<!doctype …>`, other `<!…>`, `<?…>` and `</` + non-letter run to the next `>`.
+- `<![CDATA[` anywhere is an error.
+- A `<` followed by anything but a letter, `/`, `!` or `?` is text.
+- After an `attr-list` slot, the next static chunk must be empty (another slot follows) or
+  start with whitespace, `>` or `/`, and its first non-whitespace character must not be `=`.
+  Otherwise whether the static text binds to a preceding attribute would depend on what the
+  slot rendered.
+- `attr-list` slots are refused on SVG `<animate>` and `<set>` (see §3.6).
+
+### 3.2 Raw text boundaries
+
+A value inserted into raw text must not be able to complete `</script`, `</style`,
+`</title`, `</textarea` or `<!--` together with the static text around it:
+
+- **Before a slot**: the static text in a raw-text or RCDATA element must not end with a
+  non-empty prefix of the element's closing sequence (`<`, `</`, `</s`, … `</script`) or, in
+  `<script>`, of `<!--` (`<`, `<!`, `<!-`). Error: "add a space". So `if (a <${x})` is refused,
+  `if (a < ${x})` is fine.
+- **After a slot**: `scriptText()` and `styleText()` output never ends with such a prefix
+  (§5.3, §5.4); `jsonScript()` output contains no `<`; RCDATA values are escaped.
+- **Static `<!--` inside `<script>` is an error.** It enters the tokenizer's script-data
+  escaped states, where `<script>` inside can make the real end tag not end the element. The
+  scanner does not model those states.
+
+### 3.3 Quoted attribute values
+
+By lowercased tag and attribute name:
+
+1. `on*` (event handlers): error. Write handlers literally, or use `scriptText()` in a
+   `<script>`.
+2. `srcdoc`: error (HTML inside an attribute).
+3. `ping`: error (a URL list; not modeled).
+4. `to`, `from`, `by`, `values`, `attributename` on SVG `<animate>` / `<set>`: error (§3.6).
+5. `srcset`, `imagesrcset`: context `srcset`. The slot must be the whole value (whitespace
+   around it only).
+6. URL attributes: §3.4.
+7. Everything else, `style` included: `attr-value`.
+
+### 3.4 URL attributes
+
+`href`, `src`, `action`, `formaction`, `poster`, `cite`, `background`, `longdesc`,
+`manifest`, `codebase`, `icon`, `xlink:href`, and `data` on `<object>`.
+
+Only the **first** slot in a URL value decides; later slots in the same value are
+`attr-value`, because the first one settled the scheme. For the first slot, let **P** be the
+static text of the value before it, with tab/LF/CR removed and leading C0 controls and space
+stripped (what the URL parser ignores).
+
+- **P is empty** → context `url` (the value goes through the policy). The static text after
+  the slot (tab/LF/CR removed), up to the closing quote or the next slot, must be either
+  whitespace to the closing quote, or start with `/`, `?` or `#`. So `href="${u}"`,
+  `src="${cdn}/img/${name}.png"` and `href="${base}?q=${q}"` work, while `href="${a}${b}"`,
+  `href="${a}:x"` and `href="${a}x"` are errors: in those, each piece could pass the policy
+  while the joined value is `javascript:…`. After a vetted value, a `/`, `?` or `#` can't
+  change its scheme.
+- **P settles the scheme** → context `attr-value` (escaping only). Let Q be P up to its
+  first `&` (a character reference could decode to scheme characters). P settles the scheme
+  when Q's first character is not an ASCII letter (relative: `/`, `./`, `#`, `?`, `//`), or Q
+  contains a character outside `[A-Za-z0-9+.-]`. If that character is `:`, Q wrote a
+  **static scheme**, which must be in the kit's allowlist: checked at render, an
+  `HtmlTemplateError` otherwise. So `href="mailto:${a}"` works, while
+  `href="javascript:go('${id}')"` and (with the default kit) `src="data:image/png;base64,${b}"`
+  are errors. For the latter, build the whole URL and pass `url(value, { schemes: ["data"] })`.
+- **Otherwise** (Q is empty or could still grow into a scheme: `href="java${x}"`,
+  `href="http${s}://x"`, `href="&#x6a;ava${x}"`) → error: ambiguous scheme.
+
+### 3.5 End of template
+
+After the last static chunk the scanner must be back in text: outside any tag, comment,
+declaration, raw text, RCDATA, and outside `<svg>`/`<math>`. Unclosed normal elements are
+fine. A stray `</svg>` or `</math>` is an error.
+
+This makes a `SafeHtml` fragment safe to drop into another template's `text` slot: it starts
+and ends in text and every value inside was rendered for its own context.
+
+### 3.6 SVG and MathML (foreign content)
+
+Inside `<svg>` and `<math>` the HTML parser does not switch the tokenizer for `<script>`,
+`<style>`, `<title>` or `<textarea>`: their content is markup. Treating them as raw text, as
+in HTML, would let `styleText("<img src=x onerror=…>")` inside an SVG `<style>` create an
+element, and would classify `<svg><title><a href="${u}">` as text (no URL policy). So:
+
+- The scanner tracks open `<svg>`/`<math>` elements (a stack; an end tag pops to the nearest
+  element of that name). `<svg/>` has no content.
+- In foreign content no tag switches the tokenizer. A slot in the content of `<script>` or
+  `<style>` there is an error; their static content is scanned as markup.
+- HTML elements that end foreign content (`<p>`, `<div>`, `<img>`, `<b>`, `<br>`, `<table>`,
+  `<font>`, … and `</p>`, `</br>`) are errors: close the `<svg>`/`<math>` first.
+- Integration points (SVG `foreignObject`, `desc`, `title`; MathML `mi`, `mo`, `mn`, `ms`,
+  `mtext`, `annotation-xml`) may contain text, comments and slots only; a start tag inside is
+  an error. Slots in SVG integration points are HTML text; in MathML ones they are foreign
+  text.
+- SVG `<animate>`/`<set>` can set another attribute (such as `href`) to any value, so slots
+  in their `to`, `from`, `by`, `values`, `attributeName` and `attr-list` slots are errors.
+- `text` slots in foreign content (outside SVG integration points) accept an `html`
+  fragment only if it is **neutral**.
+
+**Neutrality.** Every template is scanned twice: once starting in HTML, once starting inside
+a generic foreign element (no integration points, a stray `</svg>` is an error). The
+template is neutral if both scans succeed and agree on every slot (same context, tag,
+attribute and static scheme; `rcdata` in HTML may be `text` in foreign content, since
+`rcdata` accepts a subset of `text` and renders it identically). A rendered fragment is
+neutral if its template is and every fragment rendered into its text slots is. `<circle
+r="${r}"/>`, `<g>…</g>`, `<title>${t}</title>` and static `<style>` are neutral; `<p>`,
+`<style>${styleText(…)}</style>` and `<textarea><a href="${u}"></textarea>` are not.
+
+### 3.7 Strictness
+
+Anything the scanner does not model is an error, never a guess. Analysis errors depend on the
+template only, so a test that renders every template once surfaces them all. Relaxing a rule
+later is a minor release; tightening one breaks templates.
+
+### 3.8 Excerpts
+
+`HtmlTemplateError.excerpt` is the static text with slots shown as `${…}`, the failing slot
+as `${⟨here⟩}` (or `⟨here⟩` at an offset for errors in static text), whitespace collapsed,
+trimmed to about 90 characters. It never contains a value.
+
+## 4. Rendering: value × context
+
+✗ = `HtmlValueError` (slot index, context and received type/kind; never the value). E =
+§5.1 escape. P = §5.2 policy.
+
+| Value                                   | text      | rcdata   | attr-list | attr-value | url      | srcset   | script   | style    |
+| --------------------------------------- | --------- | -------- | --------- | ---------- | -------- | -------- | -------- | -------- |
+| `string`                                | E         | E        | ✗         | E          | P, E     | ✗        | ✗        | ✗        |
+| `number`, `bigint`                      | `String`  | same     | ✗         | `String`   | P, E     | ✗        | ✗        | ✗        |
+| `null`, `undefined`, `false`, `true`    | `""`      | `""`     | `""`      | `""`       | `""`     | `""`     | `""`     | `""`     |
+| array                                   | items     | items    | items     | ✗          | ✗        | ✗        | ✗        | ✗        |
+| `html` (`html`, `join`)                 | verbatim¹ | ✗        | ✗         | ✗          | ✗        | ✗        | ✗        | ✗        |
+| `attrs`                                 | ✗         | ✗        | verbatim  | ✗          | ✗        | ✗        | ✗        | ✗        |
+| `url`                                   | E         | E        | ✗         | E          | E (no P) | ✗        | ✗        | ✗        |
+| `srcset`                                | ✗         | ✗        | ✗         | E          | ✗        | E        | ✗        | ✗        |
+| `json`, `js`                            | ✗         | ✗        | ✗         | ✗          | ✗        | ✗        | verbatim | ✗        |
+| `css`                                   | ✗         | ✗        | ✗         | ✗          | ✗        | ✗        | ✗        | verbatim |
+| `unsafe`                                | verbatim  | verbatim | verbatim  | verbatim   | verbatim | verbatim | verbatim | verbatim |
+| object, function, symbol, date, promise | ✗         | ✗        | ✗         | ✗          | ✗        | ✗        | ✗        | ✗        |
+
+¹ In SVG/MathML text slots only neutral fragments (§3.6).
+
+- **Booleans render nothing, `true` included** (as in JSX), so ``${cond && html`…`}`` works.
+  Numbers render, so ``${count && html`…`}`` prints `0` when the count is zero: write
+  `count > 0 && …`.
+- **`script` and `style` accept only their serializers**, not even numbers: data goes into a
+  script through `jsonScript`.
+- **An `html` fragment in an attribute value is an error**, not escaped: escaping would
+  silently change what trusted markup means.
+- **`html` in `rcdata` is an error**: `<title>` and `<textarea>` hold text, and trusted
+  markup containing `</title>` would end the element.
+- **`url` and `srcset` values are vetted, not escaped**: they are escaped wherever rendered
+  (`srcset` is also accepted in plain attribute values, e.g. a lazy loader's
+  `data-srcset`).
+- **Arrays** render item by item under the slot's rules; nesting deeper than 100 is an error
+  (a cycle).
+- **Promises and thenables** get a dedicated message: await before rendering.
+
+## 5. Algorithms
+
+### 5.1 HTML escaping
+
+`&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`, `"` → `&quot;`, `'` → `&#39;`. Correct in text,
+RCDATA and both quoted attribute forms (not in unquoted values, which are analysis errors).
+Strings with none of these are returned unchanged.
+
+### 5.2 URL policy
+
+1. Detect the scheme as the URL parser would: skip leading C0 controls and space, ignore
+   tab/LF/CR anywhere, then `[A-Za-z][A-Za-z0-9+.-]*` followed by `:`. Anything else ends the
+   scheme: the URL is relative.
+2. Relative, or a lowercased scheme in the allowlist → allowed: the **original** string.
+3. Otherwise → blocked: `onBlockedUrl({ url, tag?, attribute? })` is called, and the kit's
+   `blockedUrl` (default `about:invalid#blocked`) is used instead (a blocked `srcset`
+   candidate is dropped).
+
+Values are escaped after the policy, so entity tricks (`jav&#x09;ascript:`) reach the
+browser as literal `&`, `#`, `x`, which is not a scheme.
+
+### 5.3 `jsonScript(value, space?)`
+
+`JSON.stringify(value, null, space)`, then `<` → `\u003c`, `>` → `\u003e`,
+`&` → `\u0026`, U+2028 → `\u2028`, U+2029 → `\u2029`. Valid JSON decoding to
+the same value, and a valid JS expression; contains no `<`, so no `</script` or `<!--`. `HtmlValueError` if there is no JSON
+representation; `JSON.stringify`'s own errors (cycles, BigInt) propagate.
+
+### 5.4 `scriptText(source)`
+
+Every case-insensitive `</script` → `<\/script`; every `<!--` → `\x3C!--` (not `<\!--`: `\!`
+is a SyntaxError in a `u`/`v` regex); and a `<` that ends the source, alone or followed by a
+proper prefix of `/script` or `!--`, → `\x3C`. The first two keep the meaning inside JS
+strings, template literals and regexes (and `</script` is invalid elsewhere). The third only
+affects sources that end mid-token, which a whole script never does.
+
+### 5.5 `styleText(source)`
+
+Every case-insensitive `</style` → `<\/style`, and a `<` that ends the source, alone or
+followed by a proper prefix of `/style`, → `\00003C`. Other `<` are kept (media-query ranges
+use them). Prevents breakout, not CSS injection.
+
+### 5.6 `srcset(candidates)`
+
+Each URL goes through the policy unless it is a `SafeUrl`; blocked and empty candidates are
+dropped. ASCII whitespace in a URL and leading/trailing commas are percent-encoded (the only
+things that break `srcset` parsing). Descriptors must match `/^\d+(\.\d+)?x$|^\d+w$/`, else
+`HtmlValueError` (checked even when the URL is blocked). Output: `url descriptor, …`,
+unescaped; escaped where rendered.
+
+## 6. Errors: "data can't make a render throw"
+
+| Error               | When                                                                            | Depends on                          |
+| ------------------- | ------------------------------------------------------------------------------- | ----------------------------------- |
+| `HtmlTemplateError` | not a template object, invalid escape, any §3 error, a disallowed static scheme | the template (and kit config)       |
+| `HtmlValueError`    | ✗ cells in §4, `jsonScript` of `undefined`, nested arrays > 100                 | the value's type, kind or structure |
+| `HtmlValueError`    | invalid attribute **name** in `attrs()`, invalid `srcset` **descriptor**        | content expected to come from code  |
+| (none)              | blocked URLs, `</script` in `scriptText`, odd characters anywhere               | content: handled, never thrown      |
+
+`onBlockedUrl` may throw; that propagates (it is the caller's choice).
+
+## 7. Performance
+
+Analysis is O(static text), twice per call site (HTML and foreign scans), cached in a
+`WeakMap` keyed by the template object; a cache hit is one lookup. Rendering is one pass
+with string concatenation (ropes, so nesting does not copy quadratically). See
+`bench/render.bench.ts` and the README for numbers.
+
+## 8. Changes from the original draft
+
+The first draft of this design was revised during implementation:
+
+1. **SVG/MathML are modeled** (§3.6). The draft scanned them as HTML and called that
+   "stricter than necessary for `<script>`/`<style>` inside SVG". It is the opposite: their
+   content is markup there, so `styleText()` could create elements, and SVG `<title>` was
+   misread as RCDATA.
+2. **Raw-text boundaries** (§3.2). The draft's `scriptText` only rewrote `</script` inside
+   its own output, so `a <${scriptText("/script>…")}` or a value ending in `</scr` followed
+   by static `ipt>` could close the element. Static `<!--` in scripts is now refused.
+3. **Static schemes are checked** (§3.4). `href="javascript:go('${id}')"` was accepted as
+   "prefix settles the scheme". Character references in the prefix are now handled
+   (`href="&#x6a;ava${x}"` was accepted).
+4. **URL slots may continue with `/`, `?`, `#`** (§3.4), which is provably safe and makes
+   `src="${cdn}/x.png"` work. The draft required the slot to be the whole value.
+5. **`rcdata` is its own context** that refuses `html` fragments (§4).
+6. **`attr-list` can't be followed by `=`** (§3.1), and `ping` is refused in `attrs()` as in
+   templates. `data` is URL-checked in `attrs()` (it can't know the tag).
+7. **SVG animation attributes** are refused (§3.3).
+8. **`SafeSrcset` stores the unescaped value** (like `SafeUrl`) and is escaped where
+   rendered; it is also accepted in plain attribute values.
+9. **`join()` skips `null`, `undefined` and booleans**, so conditional items leave no stray
+   separator.
+10. **Immutability without `Object.freeze`** (private fields): freezing cost more than the
+    rest of a small render.
+11. **Tests** use a seeded generator instead of `fast-check` (one dev dependency, `parse5`,
+    and deterministic runs), plus value round-trips through `parse5`.