@marianmeres/safe-html 0.2.0

package/dist/scanner.js

@@ -0,0 +1,742 @@
+/**
+ * Context analysis (the scanner).
+ *
+ * Purpose: classify every slot of a template from its static strings alone, once per call
+ * site, and cache the result (including a failure) by template object.
+ *
+ * Invariants:
+ * - Models only the part of the HTML tokenizer, and of the tree construction that switches the
+ *   tokenizer (raw text, RCDATA, SVG/MathML foreign content), needed to classify slots.
+ *   Anything it does not model is an error, never a guess.
+ * - A slot never changes the scanner state: every value renders so that it can't.
+ * - A template ends where it started: in text, outside any tag, comment, raw text or foreign
+ *   content. That makes a fragment safe to drop into another template's text slot.
+ * - Foreign content: a fragment is "neutral" when a second scan that starts inside SVG/MathML
+ *   agrees with the HTML scan; only neutral fragments may go into SVG/MathML text slots.
+ */
+import { HtmlTemplateError } from "./errors.js";
+import { LEADING_C0_SPACE, ONLY_C0_SPACE } from "./url.js";
+/** Creates a slot description (always the same shape, which keeps rendering monomorphic). */
+export function slotInfo(context, tag = "", attr = "", scheme = "", foreign = false) {
+    return Object.freeze({ context, tag, attr, scheme, foreign });
+}
+// ---- character classes ------------------------------------------------------------------
+const isWs = (c) => c === " " || c === "\t" || c === "\n" || c === "\f" || c === "\r";
+const isAlpha = (c) => (c >= "a" && c <= "z") || (c >= "A" && c <= "Z");
+const isSchemeChar = (c) => isAlpha(c) || (c >= "0" && c <= "9") || c === "+" || c === "." || c === "-";
+const WS_ONLY = /^[\t\n\f\r ]*$/;
+/** Elements whose start tag switches the tokenizer (HTML mode only). */
+const RAW_KIND = new Map([
+    ["script", "script"],
+    ["style", "style"],
+    ["title", "rcdata"],
+    ["textarea", "rcdata"],
+    ["iframe", "unsupported"],
+    ["noembed", "unsupported"],
+    ["noframes", "unsupported"],
+    ["noscript", "unsupported"],
+    ["xmp", "unsupported"],
+    ["plaintext", "plaintext"],
+]);
+/** Start tags that end SVG/MathML foreign content (`font` only with some attributes; always here). */
+const BREAKOUT = new Set(("b big blockquote body br center code dd div dl dt em embed font h1 h2 h3 h4 h5 h6 head " +
+    "hr i img li listing menu meta nobr ol p pre ruby s small span strong strike sub sup " +
+    "table tt u ul var").split(" "));
+/** SVG HTML integration points: their content is parsed as HTML. */
+const SVG_INTEGRATION = new Set(["foreignobject", "desc", "title"]);
+/** MathML text integration points and `annotation-xml`. */
+const MATH_INTEGRATION = new Set([
+    "mi",
+    "mo",
+    "mn",
+    "ms",
+    "mtext",
+    "annotation-xml",
+]);
+/** SVG animation elements, which can set another attribute (e.g. `href`) to any value. */
+const SVG_ANIMATION = new Set(["animate", "set"]);
+const SVG_ANIMATION_ATTRS = new Set([
+    "attributename",
+    "to",
+    "from",
+    "by",
+    "values",
+]);
+/** Attributes whose value is a URL (plus `data` on `<object>`). */
+export const URL_ATTRIBUTES = new Set([
+    "href",
+    "src",
+    "action",
+    "formaction",
+    "poster",
+    "cite",
+    "background",
+    "longdesc",
+    "manifest",
+    "codebase",
+    "icon",
+    "xlink:href",
+]);
+const isUrlAttr = (tag, attr) => URL_ATTRIBUTES.has(attr) || (attr === "data" && tag === "object");
+// ---- tokenizer states -------------------------------------------------------------------
+const TEXT = 0;
+const TAG_OPEN = 1;
+const END_TAG_OPEN = 2;
+const TAG_NAME = 3;
+const BEFORE_ATTR_NAME = 4;
+const ATTR_NAME = 5;
+const AFTER_ATTR_NAME = 6;
+const BEFORE_ATTR_VALUE = 7;
+const ATTR_VALUE_QUOTED = 8;
+const ATTR_VALUE_UNQUOTED = 9;
+const AFTER_ATTR_VALUE_QUOTED = 10;
+const SELF_CLOSING = 11;
+const MARKUP_DECL = 12;
+const COMMENT = 13;
+const BOGUS_COMMENT = 14;
+const RAW = 15;
+/** Internal failure; turned into an `HtmlTemplateError` with an excerpt. */
+class ScanError {
+    reason;
+    slot;
+    chunk;
+    offset;
+    useRaw;
+    constructor(reason, slot, chunk, offset, useRaw = false) {
+        this.reason = reason;
+        this.slot = slot;
+        this.chunk = chunk;
+        this.offset = offset;
+        this.useRaw = useRaw;
+    }
+}
+const closerCache = new Map();
+function closerRe(name) {
+    let re = closerCache.get(name);
+    if (!re) {
+        re = new RegExp(`</${name}(?=[\\t\\n\\f\\r />])`, "gi");
+        closerCache.set(name, re);
+    }
+    return re;
+}
+/** Does `text` end with a non-empty prefix of `seq` (case-insensitive)? E.g. `"<"`, `"</scr"`. */
+function endsWithPartial(text, seq) {
+    const lt = text.lastIndexOf("<");
+    return lt !== -1 && seq.startsWith(text.slice(lt).toLowerCase());
+}
+/**
+ * The static text before the first slot of a URL attribute (normalized, non-empty):
+ * returns the lowercased scheme it writes, `""` if it settles the URL as relative, or `false`
+ * if it could still become the start of a scheme. Text from the first `&` on is ignored,
+ * because a character reference may decode to scheme characters.
+ */
+function settleScheme(prefix) {
+    const amp = prefix.indexOf("&");
+    const p = amp === -1 ? prefix : prefix.slice(0, amp);
+    if (p === "")
+        return false;
+    if (!isAlpha(p[0]))
+        return "";
+    for (let i = 1; i < p.length; i++) {
+        if (p[i] === ":")
+            return p.slice(0, i).toLowerCase();
+        if (!isSchemeChar(p[i]))
+            return "";
+    }
+    return false;
+}
+class Scanner {
+    strings;
+    floor;
+    slots = [];
+    state = TEXT;
+    k = 0; // current chunk
+    // current tag and attribute
+    tag = "";
+    isEnd = false;
+    selfClosing = false;
+    attr = "";
+    quote = "";
+    valueStatic = "";
+    valueSlots = 0;
+    // raw text / RCDATA (HTML mode)
+    raw = "";
+    rawKind = "script";
+    rawStart = 0;
+    // foreign content: ns is the namespace of the outermost <svg>/<math> ("generic" for the
+    // virtual one a neutrality scan starts inside); stack holds the open svg/math elements
+    ns = "";
+    stack = [];
+    foreignRaw = ""; // inside <script>/<style> in foreign content
+    integration = ""; // inside an integration point
+    integrationHtml = false; // SVG integration point (content parsed as HTML)
+    constructor(strings, floor) {
+        this.strings = strings;
+        this.floor = floor;
+        if (floor)
+            this.ns = "generic";
+    }
+    run() {
+        const n = this.strings.length;
+        for (let k = 0; k < n; k++) {
+            this.k = k;
+            this.chunk(this.strings[k]);
+            if (k < n - 1)
+                this.slot(k);
+        }
+        this.end();
+        return this.slots;
+    }
+    fail(reason, offset) {
+        throw new ScanError(reason, undefined, this.k, offset);
+    }
+    chunk(s) {
+        this.rawStart = 0;
+        const len = s.length;
+        let i = 0;
+        while (i < len) {
+            const c = s[i];
+            switch (this.state) {
+                case TEXT: {
+                    const j = s.indexOf("<", i);
+                    if (j === -1)
+                        i = len;
+                    else {
+                        this.state = TAG_OPEN;
+                        i = j + 1;
+                    }
+                    break;
+                }
+                case TAG_OPEN:
+                    if (c === "!")
+                        i = this.markupDecl(s, i + 1);
+                    else if (c === "/") {
+                        this.state = END_TAG_OPEN;
+                        i++;
+                    }
+                    else if (isAlpha(c)) {
+                        this.startTag(c, false);
+                        i++;
+                    }
+                    else if (c === "?") {
+                        this.state = BOGUS_COMMENT;
+                        i++;
+                    }
+                    else
+                        this.state = TEXT; // a stray "<" is text
+                    break;
+                case END_TAG_OPEN:
+                    if (isAlpha(c)) {
+                        this.startTag(c, true);
+                        i++;
+                    }
+                    else if (c === ">") {
+                        this.state = TEXT; // "</>" is ignored
+                        i++;
+                    }
+                    else
+                        this.state = BOGUS_COMMENT;
+                    break;
+                case TAG_NAME:
+                    if (isWs(c)) {
+                        this.state = BEFORE_ATTR_NAME;
+                        i++;
+                    }
+                    else if (c === "/") {
+                        this.state = SELF_CLOSING;
+                        i++;
+                    }
+                    else if (c === ">")
+                        i = this.emitTag(i);
+                    else {
+                        this.tag += c.toLowerCase();
+                        i++;
+                    }
+                    break;
+                case BEFORE_ATTR_NAME:
+                case AFTER_ATTR_NAME:
+                    if (isWs(c))
+                        i++;
+                    else if (c === "/") {
+                        this.state = SELF_CLOSING;
+                        i++;
+                    }
+                    else if (c === ">")
+                        i = this.emitTag(i);
+                    else if (c === "=" && this.state === AFTER_ATTR_NAME) {
+                        this.state = BEFORE_ATTR_VALUE;
+                        i++;
+                    }
+                    else {
+                        this.attr = c.toLowerCase();
+                        this.state = ATTR_NAME;
+                        i++;
+                    }
+                    break;
+                case ATTR_NAME:
+                    if (isWs(c)) {
+                        this.state = AFTER_ATTR_NAME;
+                        i++;
+                    }
+                    else if (c === "/") {
+                        this.state = SELF_CLOSING;
+                        i++;
+                    }
+                    else if (c === "=") {
+                        this.state = BEFORE_ATTR_VALUE;
+                        i++;
+                    }
+                    else if (c === ">")
+                        i = this.emitTag(i);
+                    else {
+                        this.attr += c.toLowerCase();
+                        i++;
+                    }
+                    break;
+                case BEFORE_ATTR_VALUE:
+                    if (isWs(c))
+                        i++;
+                    else if (c === '"' || c === "'") {
+                        this.quote = c;
+                        this.valueStatic = "";
+                        this.valueSlots = 0;
+                        this.state = ATTR_VALUE_QUOTED;
+                        i++;
+                    }
+                    else if (c === ">")
+                        i = this.emitTag(i);
+                    else
+                        this.state = ATTR_VALUE_UNQUOTED;
+                    break;
+                case ATTR_VALUE_QUOTED: {
+                    const j = s.indexOf(this.quote, i);
+                    if (j === -1) {
+                        this.valueStatic += s.slice(i);
+                        i = len;
+                    }
+                    else {
+                        this.valueStatic += s.slice(i, j);
+                        this.state = AFTER_ATTR_VALUE_QUOTED;
+                        i = j + 1;
+                    }
+                    break;
+                }
+                case ATTR_VALUE_UNQUOTED:
+                    if (isWs(c)) {
+                        this.state = BEFORE_ATTR_NAME;
+                        i++;
+                    }
+                    else if (c === ">")
+                        i = this.emitTag(i);
+                    else
+                        i++;
+                    break;
+                case AFTER_ATTR_VALUE_QUOTED:
+                    if (isWs(c)) {
+                        this.state = BEFORE_ATTR_NAME;
+                        i++;
+                    }
+                    else if (c === "/") {
+                        this.state = SELF_CLOSING;
+                        i++;
+                    }
+                    else if (c === ">")
+                        i = this.emitTag(i);
+                    else
+                        this.state = BEFORE_ATTR_NAME;
+                    break;
+                case SELF_CLOSING:
+                    if (c === ">") {
+                        this.selfClosing = true;
+                        i = this.emitTag(i);
+                    }
+                    else
+                        this.state = BEFORE_ATTR_NAME;
+                    break;
+                case BOGUS_COMMENT: {
+                    const j = s.indexOf(">", i);
+                    if (j === -1)
+                        i = len;
+                    else {
+                        this.state = TEXT;
+                        i = j + 1;
+                    }
+                    break;
+                }
+                case RAW:
+                    i = this.rawText(s, i);
+                    break;
+                default: // COMMENT, MARKUP_DECL: unterminated in this chunk
+                    i = len;
+            }
+        }
+    }
+    startTag(c, isEnd) {
+        this.tag = c.toLowerCase();
+        this.isEnd = isEnd;
+        this.selfClosing = false;
+        this.attr = "";
+        this.state = TAG_NAME;
+    }
+    /** After `<!`. Returns the next index. */
+    markupDecl(s, i) {
+        if (s.startsWith("--", i)) {
+            const j = i + 2;
+            this.state = TEXT;
+            if (s[j] === ">")
+                return j + 1; // <!-->
+            if (s.startsWith("->", j))
+                return j + 2; // <!--->
+            const a = s.indexOf("-->", j);
+            const b = s.indexOf("--!>", j);
+            if (b !== -1 && (a === -1 || b < a))
+                return b + 4;
+            if (a !== -1)
+                return a + 3;
+            this.state = COMMENT;
+            return s.length;
+        }
+        const head = s.slice(i, i + 7);
+        if (head.toUpperCase() === "[CDATA[") {
+            this.fail("CDATA sections are not supported", i - 2);
+        }
+        if (i + head.length === s.length &&
+            ("--".startsWith(head) || "[CDATA[".startsWith(head.toUpperCase()))) {
+            // the chunk ends before the kind of declaration is known
+            this.state = MARKUP_DECL;
+            return s.length;
+        }
+        this.state = BOGUS_COMMENT; // <!doctype …>, <!…>
+        return i;
+    }
+    /** Raw text of the current element (HTML mode). Returns the next index. */
+    rawText(s, i) {
+        if (this.rawKind === "plaintext")
+            return s.length;
+        const re = closerRe(this.raw);
+        re.lastIndex = i;
+        const m = re.exec(s);
+        const end = m ? m.index : -1;
+        if (this.rawKind === "script") {
+            const c = s.indexOf("<!--", i);
+            if (c !== -1 && (end === -1 || c < end)) {
+                this.fail('"<!--" inside <script> is not supported (script-data escape states are not modeled)', c);
+            }
+        }
+        if (end === -1)
+            return s.length;
+        // the end tag: continue in the tag machinery, which handles the terminator
+        this.startTag(this.raw[0], true);
+        this.tag = this.raw;
+        this.raw = "";
+        return end + 2 + this.tag.length;
+    }
+    /** Called with `i` at the `>` of a tag. Returns the next index. */
+    emitTag(i) {
+        const tag = this.tag;
+        this.state = TEXT;
+        if (this.isEnd) {
+            this.endTag(tag, i);
+            return i + 1;
+        }
+        if (this.integration) {
+            this.fail(`<${tag}> inside <${this.integration}> (an SVG/MathML integration point) is not supported`, i);
+        }
+        if (this.ns) {
+            if (BREAKOUT.has(tag)) {
+                this.fail(`<${tag}> inside <svg>/<math> ends the foreign content; close the <svg>/<math> first`, i);
+            }
+            if (this.selfClosing)
+                return i + 1; // honored in foreign content
+            if (tag === "svg" || tag === "math")
+                this.stack.push(tag);
+            else if (tag === "script" || tag === "style")
+                this.foreignRaw ||= tag;
+            else if ((this.ns === "svg" && SVG_INTEGRATION.has(tag)) ||
+                (this.ns === "math" && MATH_INTEGRATION.has(tag))) {
+                this.integration = tag;
+                this.integrationHtml = this.ns === "svg";
+            }
+            return i + 1;
+        }
+        if (tag === "svg" || tag === "math") {
+            if (!this.selfClosing) {
+                this.ns = tag;
+                this.stack = [tag];
+            }
+            return i + 1;
+        }
+        const kind = RAW_KIND.get(tag); // the self-closing flag is ignored here, as in HTML
+        if (kind) {
+            this.raw = tag;
+            this.rawKind = kind;
+            this.rawStart = i + 1;
+            this.state = RAW;
+        }
+        return i + 1;
+    }
+    endTag(tag, i) {
+        if (this.integration) {
+            if (tag === this.integration)
+                this.integration = "";
+            else
+                this.fail(`</${tag}> inside <${this.integration}> is not supported`, i);
+            return;
+        }
+        if (!this.ns) {
+            if (tag === "svg" || tag === "math") {
+                this.fail(`</${tag}> without a matching <${tag}> in the same template`, i);
+            }
+            return;
+        }
+        if (tag === "br" || tag === "p") {
+            this.fail(`</${tag}> inside <svg>/<math> ends the foreign content`, i);
+        }
+        if (tag === this.foreignRaw)
+            this.foreignRaw = "";
+        else if (tag === "svg" || tag === "math") {
+            const at = this.stack.lastIndexOf(tag);
+            if (at === -1) {
+                this.fail(`</${tag}> without a matching <${tag}> in the same template`, i);
+            }
+            this.stack.length = at;
+            this.foreignRaw = "";
+            if (!this.stack.length && !this.floor)
+                this.ns = "";
+        }
+    }
+    slot(k) {
+        const next = this.strings[k + 1];
+        const fail = (reason) => {
+            throw new ScanError(reason, k);
+        };
+        switch (this.state) {
+            case TEXT:
+                if (this.foreignRaw) {
+                    fail(`slot inside <${this.foreignRaw}> within <svg>/<math> is not supported`);
+                }
+                this.slots.push(slotInfo("text", "", "", "", this.integration ? !this.integrationHtml : this.ns !== ""));
+                return;
+            case RAW: {
+                const kind = this.rawKind;
+                if (kind === "unsupported" || kind === "plaintext") {
+                    fail(`slot inside <${this.raw}> is not supported`);
+                }
+                const before = this.strings[k].slice(this.rawStart);
+                if (endsWithPartial(before, "</" + this.raw) ||
+                    (kind === "script" && endsWithPartial(before, "<!--"))) {
+                    fail(`slot right after "<" inside <${this.raw}>: add a space between them`);
+                }
+                this.slots.push(slotInfo(kind, this.raw));
+                return;
+            }
+            case ATTR_VALUE_QUOTED:
+                return this.valueSlot(next, fail);
+            case BEFORE_ATTR_NAME:
+            case AFTER_ATTR_NAME:
+            case AFTER_ATTR_VALUE_QUOTED:
+                if (this.isEnd)
+                    fail("slot inside an end tag");
+                if (SVG_ANIMATION.has(this.tag)) {
+                    fail(`attribute-list slot on <${this.tag}> is not supported`);
+                }
+                if (next !== "" && !(isWs(next[0]) || next[0] === ">" || next[0] === "/")) {
+                    fail('an attribute-list slot must be followed by whitespace, ">" or "/"');
+                }
+                if (/^[\t\n\f\r ]*=/.test(next)) {
+                    fail('an attribute-list slot can\'t be followed by "="');
+                }
+                this.slots.push(slotInfo("attr-list", this.tag));
+                this.state = BEFORE_ATTR_NAME;
+                return;
+            case TAG_OPEN:
+            case END_TAG_OPEN:
+            case TAG_NAME:
+                fail("slot in a tag name: tag names must be static");
+                break;
+            case ATTR_NAME:
+                fail("slot in or right after an attribute name: add whitespace before it, or use attrs()");
+                break;
+            case BEFORE_ATTR_VALUE:
+            case ATTR_VALUE_UNQUOTED:
+                fail('unquoted attribute value: quote it, e.g. name="${…}"');
+                break;
+            case SELF_CLOSING:
+                fail('slot right after "/" in a tag');
+                break;
+            default:
+                fail("slot inside a comment or declaration");
+        }
+    }
+    valueSlot(next, fail) {
+        const { tag, attr } = this;
+        if (this.isEnd)
+            fail("slot inside an end tag");
+        if (attr.startsWith("on")) {
+            fail(`slot in event-handler attribute "${attr}": write the handler literally, or use scriptText() in a <script>`);
+        }
+        if (attr === "srcdoc") {
+            fail('slot in "srcdoc" (HTML inside an attribute) is not supported');
+        }
+        if (attr === "ping")
+            fail('slot in "ping" (a URL list) is not supported');
+        if (SVG_ANIMATION.has(tag) && SVG_ANIMATION_ATTRS.has(attr)) {
+            fail(`slot in "${attr}" on <${tag}> is not supported (SVG animation can set href)`);
+        }
+        const q = next.indexOf(this.quote);
+        const after = q === -1 ? null : next.slice(0, q); // null: another slot comes first
+        let info;
+        if (attr === "srcset" || attr === "imagesrcset") {
+            if (this.valueSlots > 0 || !WS_ONLY.test(this.valueStatic) ||
+                after === null ||
+                !WS_ONLY.test(after)) {
+                fail(`a "${attr}" slot must be the whole value: use srcset([...])`);
+            }
+            info = slotInfo("srcset", tag, attr);
+        }
+        else if (!isUrlAttr(tag, attr) || this.valueSlots > 0) {
+            // a later slot in a URL value: the first one already settled the scheme
+            info = slotInfo("attr-value", tag, attr);
+        }
+        else {
+            const prefix = this.valueStatic.replace(/[\t\n\r]/g, "").replace(LEADING_C0_SPACE, "");
+            if (prefix === "") {
+                const rest = (after ?? next).replace(/[\t\n\r]/g, "");
+                const ok = /^[/?#]/.test(rest) ||
+                    (after !== null && ONLY_C0_SPACE.test(rest));
+                if (!ok) {
+                    fail('a URL value that starts with a slot must be the slot alone, or continue with "/", "?" or "#": build the URL in code');
+                }
+                info = slotInfo("url", tag, attr);
+            }
+            else {
+                const scheme = settleScheme(prefix);
+                if (scheme === false) {
+                    fail("ambiguous URL scheme: the static text before the slot could still become a scheme; build the URL in code");
+                }
+                info = slotInfo("attr-value", tag, attr, scheme);
+            }
+        }
+        this.slots.push(info);
+        this.valueSlots++;
+    }
+    end() {
+        const last = this.strings.length - 1;
+        const at = this.strings[last].length;
+        const fail = (reason) => {
+            throw new ScanError(reason, undefined, last, at);
+        };
+        switch (this.state) {
+            case TEXT:
+                break;
+            case RAW:
+                fail(`template ends inside <${this.raw}>: close it in the same template`);
+                break;
+            case COMMENT:
+            case BOGUS_COMMENT:
+            case MARKUP_DECL:
+                fail("template ends inside a comment or declaration");
+                break;
+            default:
+                fail("template ends inside a tag");
+        }
+        if (this.integration)
+            fail(`template ends inside <${this.integration}>`);
+        if (this.foreignRaw)
+            fail(`template ends inside <${this.foreignRaw}>`);
+        if (this.stack.length) {
+            fail(`template ends inside <${this.stack[0]}>: close it in the same template`);
+        }
+    }
+}
+// ---- cache ------------------------------------------------------------------------------
+const cache = new WeakMap();
+let analyses = 0;
+/** Number of analyses run so far. For tests only (not exported from mod.ts). */
+export function analysisCount() {
+    return analyses;
+}
+function compute(strings) {
+    for (let i = 0; i < strings.length; i++) {
+        if (typeof strings[i] !== "string") {
+            return new ScanError("invalid escape sequence in the template", undefined, i, 0, true);
+        }
+    }
+    try {
+        const slots = new Scanner(strings, false).run();
+        let neutral = false;
+        try {
+            const f = new Scanner(strings, true).run();
+            neutral = slots.every((h, i) => {
+                const g = f[i];
+                // rcdata accepts a subset of what text accepts, and renders it identically
+                if (h.context === "rcdata")
+                    return g.context === "text";
+                return h.context === g.context && h.tag === g.tag && h.attr === g.attr &&
+                    h.scheme === g.scheme;
+            });
+        }
+        catch (e) {
+            if (!(e instanceof ScanError))
+                throw e;
+        }
+        return { slots, neutral };
+    }
+    catch (e) {
+        if (e instanceof ScanError)
+            return e;
+        throw e;
+    }
+}
+/**
+ * The analysis of a template, from the cache or computed once. Throws `HtmlTemplateError` if
+ * `strings` is not a genuine template object, or if the template is refused.
+ */
+export function analyze(strings) {
+    let a = cache.get(strings);
+    if (a === undefined) {
+        if (!Array.isArray(strings) || !Object.isFrozen(strings) ||
+            !Array.isArray(strings.raw) || !Object.isFrozen(strings.raw) ||
+            strings.raw.length !== strings.length || strings.length === 0) {
+            throw new HtmlTemplateError("html must be called as a tagged template: html`…`");
+        }
+        analyses++;
+        a = compute(strings);
+        cache.set(strings, a);
+    }
+    if (a instanceof ScanError) {
+        throw templateError(strings, a.reason, a.slot, a.chunk, a.offset, a.useRaw);
+    }
+    return a;
+}
+// ---- excerpts ---------------------------------------------------------------------------
+const collapse = (s) => s.replace(/\s+/g, " ");
+/**
+ * An `HtmlTemplateError` whose excerpt shows the static text with slots as `${…}` and the
+ * error position (a slot, or a chunk offset) marked `⟨here⟩`.
+ */
+export function templateError(strings, reason, slot, chunk, offset, useRaw = false) {
+    const src = useRaw ? strings.raw : strings;
+    let text = "";
+    let mark = 0;
+    for (let k = 0; k < src.length; k++) {
+        const s = src[k] ?? "";
+        if (k === chunk && offset !== undefined) {
+            text += collapse(s.slice(0, offset));
+            mark = text.length;
+            text += "⟨here⟩" + collapse(s.slice(offset));
+        }
+        else
+            text += collapse(s);
+        if (k < src.length - 1) {
+            if (k === slot)
+                mark = text.length;
+            text += k === slot ? "${⟨here⟩}" : "${…}";
+        }
+    }
+    const from = Math.max(0, mark - 40);
+    const to = Math.min(text.length, mark + 50);
+    const excerpt = (from > 0 ? "…" : "") + text.slice(from, to) +
+        (to < text.length ? "…" : "");
+    return new HtmlTemplateError(reason, excerpt, slot);
+}