@nisli/core 0.54.1 → 0.56.0

package/dist/template.js

@@ -9,8 +9,111 @@
  * 1. First render: parse template, clone, create bindings, mount
  * 2. Updates: signal changes trigger individual binding updates (O(1))
  */
-import { signal, isSignal, effect, computed, } from './signal.js';
+import { signal, isSignal, effect, computed, untrack, } from './signal.js';
 import { isRef } from './ref.js';
+// First-parse audit (ADR 0030.2 T4). The import is static — core has no
+// build-time dev/prod define yet (a named Wave-1 deliverable, §8) — but every
+// entry point is a no-op behind template-audit's own dev flag.
+import { auditTemplate, captureCallsite } from './template-audit.js';
+const canMoveWithin = (parent) => typeof parent.moveBefore === 'function';
+/**
+ * Value-returning untrack. signal.ts's `untrack` is `(fn: () => void) => void`
+ * (the value-returning form is a 0030.2 §3 papercut owned elsewhere); this
+ * local wrapper closes over the result until that lands.
+ */
+function untracked(fn) {
+    let result;
+    untrack(() => { result = fn(); });
+    return result;
+}
+/**
+ * Mark a string as trusted raw HTML. `html:inner` accepts ONLY branded
+ * values — a bare string throws N106 (the accidental-XSS-sink class closes,
+ * ADR 0030.2 §3). NEVER wrap user-generated input.
+ */
+export function raw(value) {
+    return { __raw: true, value };
+}
+function isRawHtml(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && '__raw' in value
+        && value.__raw === true
+        && typeof value.value === 'string');
+}
+/**
+ * Mark a string as untrusted markup to be sanitized at the sink — the brand
+ * for user-generated HTML, which must NEVER go through `raw()`.
+ *
+ * `html:inner` writes it with the platform's `Element.setHTML()` (the spec's
+ * XSS-safe default sanitizer) when the engine has one, otherwise with the hook
+ * registered by {@link setSanitizerFallback}. With NEITHER available the
+ * binding throws N107: it never falls back to `innerHTML`. nisli bundles no
+ * sanitizer — the trust decision, and its bytes, stay in the app.
+ */
+export function sanitized(value) {
+    return { __sanitize: true, value };
+}
+function isSanitizedHtml(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && '__sanitize' in value
+        && value.__sanitize === true
+        && typeof value.value === 'string');
+}
+let sanitizerFallback = null;
+/**
+ * Register the sanitizing writer used for `sanitized()` values on engines
+ * WITHOUT native `Element.setHTML()` (Safari today, older Chromium/Firefox),
+ * or `null` to unregister. Native `setHTML()` always wins where it exists, so
+ * modern engines never pay the hook. nisli ships no sanitizer; wire one:
+ *
+ *   setSanitizerFallback((el, html) => {
+ *     el.innerHTML = DOMPurify.sanitize(html);
+ *   });
+ */
+export function setSanitizerFallback(fn) {
+    sanitizerFallback = fn;
+}
+const nativeSetHtml = (el, html) => {
+    el.setHTML(html);
+};
+/**
+ * The sanitizing writer for this element, or `null` when the engine has none
+ * and the app registered none — the fail-closed signal N107 is thrown on.
+ *
+ * The method must be the one on `Element.prototype`, not merely *a* callable
+ * named `setHTML`. A duck-typed check here is a sanitizer bypass: an element
+ * carrying its own `setHTML` — DOM clobbering, an unsafe polyfill, a library
+ * shim — would be trusted as the platform sanitizer and would preempt the
+ * fallback the app explicitly registered as safe. Verified: with an
+ * own-property `setHTML`, the registered fallback was never called and
+ * `<img src=x onerror=…>` reached innerHTML intact.
+ *
+ * Read from the prototype per write rather than captured at module load, so a
+ * late polyfill or a test's stub is still honoured; identity is what is
+ * checked, not existence. Replacing `Element.prototype.setHTML` wholesale is
+ * out of scope — an attacker who can do that owns the realm regardless.
+ */
+function sanitizerFor(el) {
+    const platform = typeof Element === 'function'
+        ? Element.prototype.setHTML
+        : undefined;
+    return typeof platform === 'function'
+        && el.setHTML === platform
+        ? nativeSetHtml
+        : sanitizerFallback;
+}
+function isTrustedHtml(value) {
+    const tt = globalThis.trustedTypes;
+    return tt !== undefined && tt.isHTML(value);
+}
+// TODO(diagnostics): replace with the core diagnostics leaf (parallel
+// worktree); template-layer codes N101–N107 register there. N105–N107 are
+// thrown (correctness/security guards), unlike the warn-level audit codes.
+function nisliError(code, message) {
+    return new Error(`[nisli] ${code}: ${message}`);
+}
 // ── Template cache ──────────────────────────────────────────────────
 /**
  * Cache parsed templates by their static string parts.
@@ -18,6 +121,67 @@ import { isRef } from './ref.js';
  * reference per call site, we use WeakMap for efficient caching.
  */
 const templateCache = new WeakMap();
+/** Parses performed since module load — test-only regression hook (issue 0015). */
+let parseCount = 0;
+/** @internal Test-only: number of actual `<template>` parses performed. */
+export function __templateParseCount() {
+    return parseCount;
+}
+/**
+ * Parse-once (ADR 0030.2 T4, issue 0015): build the marker HTML string and
+ * parse it into a `<template>` exactly once per callsite, keyed by
+ * TemplateStringsArray identity. The string depends only on the static
+ * `strings` (marker indices are positional), so every TemplateResult from the
+ * same callsite shares one parsed template and clones per mount.
+ *
+ * The first parse also runs the one-time static audit (template-audit.ts)
+ * over the pristine parsed element — it still carries the raw `@event`/
+ * `class:`/marker attributes that processAttributes later strips from clones.
+ */
+function parseTemplate(strings, valueCount) {
+    let template = templateCache.get(strings);
+    if (template)
+        return template;
+    // Build the HTML string with markers.
+    // Track HTML parsing state to auto-quote markers in unquoted
+    // attribute positions where the > in --> would close the tag.
+    // See ADR 0069.
+    let htmlStr = '';
+    let inTag = false;
+    let quoteChar = null;
+    for (let i = 0; i < strings.length; i++) {
+        const s = strings[i] ?? '';
+        for (let c = 0; c < s.length; c++) {
+            const ch = s.charAt(c);
+            if (quoteChar) {
+                if (ch === quoteChar)
+                    quoteChar = null;
+            }
+            else if (inTag) {
+                if (ch === '>')
+                    inTag = false;
+                else if (ch === '"' || ch === "'")
+                    quoteChar = ch;
+            }
+            else {
+                if (ch === '<')
+                    inTag = true;
+            }
+        }
+        htmlStr += s;
+        if (i < valueCount) {
+            const needsQuotes = inTag && !quoteChar && /=\s*$/.test(s);
+            htmlStr += needsQuotes ? `"${createMarker(i)}"` : createMarker(i);
+        }
+    }
+    parseCount++;
+    template = document.createElement('template');
+    template.innerHTML = htmlStr;
+    templateCache.set(strings, template);
+    // Dev-only first-parse audit (N101–N104); no-op when disabled.
+    auditTemplate(strings, template);
+    return template;
+}
 // ── Marker for expression slots ─────────────────────────────────────
 const MARKER_PREFIX = '<!--bk-';
 const MARKER_SUFFIX = '-->';
@@ -46,44 +210,29 @@ function createMarker(index) {
 export function html(strings, ...values) {
     const bindings = [];
     const disposers = [];
+    // Dev-only: remember the authoring callsite for first-parse audit
+    // diagnostics — by first-mount time this frame is gone from the stack.
+    captureCallsite(strings);
+    let mounted = false;
     return {
         __templateResult: true,
         mount(host) {
-            // Build the HTML string with markers.
-            // Track HTML parsing state to auto-quote markers in unquoted
-            // attribute positions where the > in --> would close the tag.
-            // See ADR 0069.
-            let htmlStr = '';
-            let inTag = false;
-            let quoteChar = null;
-            for (let i = 0; i < strings.length; i++) {
-                const s = strings[i] ?? '';
-                for (let c = 0; c < s.length; c++) {
-                    const ch = s.charAt(c);
-                    if (quoteChar) {
-                        if (ch === quoteChar)
-                            quoteChar = null;
-                    }
-                    else if (inTag) {
-                        if (ch === '>')
-                            inTag = false;
-                        else if (ch === '"' || ch === "'")
-                            quoteChar = ch;
-                    }
-                    else {
-                        if (ch === '<')
-                            inTag = true;
-                    }
-                }
-                htmlStr += s;
-                if (i < values.length) {
-                    const needsQuotes = inTag && !quoteChar && /=\s*$/.test(s);
-                    htmlStr += needsQuotes ? `"${createMarker(i)}"` : createMarker(i);
-                }
+            // Single-mount guard (ADR 0030.2 T4 + §8): a second mount of a live,
+            // un-disposed result with value bindings would attach a second set of
+            // bindings to the same shared arrays — shared-binding corruption.
+            // Zero-binding templates (the registry's shared static icon pattern)
+            // stay multi-mountable; dispose() → mount() stays legal.
+            if (mounted && values.length > 0) {
+                throw nisliError('N105', `mount() on an already-mounted TemplateResult with ${values.length} value ` +
+                    `binding(s) — dispose() it first or create a fresh template per mount. ` +
+                    `Template starts: ${JSON.stringify((strings[0] ?? '').slice(0, 60))}`);
             }
-            // Parse the HTML
-            const template = document.createElement('template');
-            template.innerHTML = htmlStr;
+            mounted = true;
+            // Parse-once: the parsed template is cached per callsite; each mount
+            // only pays the clone + binding walk. The per-mount processNode walk
+            // below REMAINS by design until the ADR 0014-class work — caching
+            // removes the *parse*, not the walk (ADR 0030.2 §8).
+            const template = parseTemplate(strings, values.length);
             const fragment = template.content.cloneNode(true);
             // Walk the DOM tree and replace markers with bindings
             processNode(fragment, values, bindings, disposers);
@@ -107,6 +256,7 @@ export function html(strings, ...values) {
                 }
             }
             bindings.length = 0;
+            mounted = false;
         },
     };
 }
@@ -488,10 +638,14 @@ function bindAttribute(el, name, value, bindings, disposers) {
         return;
     }
     // Auto-resolution: framework components get _setProp for custom props
-    // (preserves types). Standard HTML attributes (id, style, data-*,
-    // aria-*) always use setAttribute even on framework components.
+    // (preserves types). Standard HTML attributes (id, style, data-*, aria-*,
+    // and — ADR 0030.2 §8 — title/role/tabindex/name) always use setAttribute
+    // even on framework components: routed through _setProp they were silently
+    // dead (no component declares them as props).
     const isHtmlAttr = name === 'id' || name === 'style'
-        || name === 'slot' || name.startsWith('data-') || name.startsWith('aria-');
+        || name === 'slot' || name === 'title' || name === 'role'
+        || name === 'tabindex' || name === 'name'
+        || name.startsWith('data-') || name.startsWith('aria-');
     const hasPropSetter = !isHtmlAttr && typeof el._setProp === 'function';
     if (hasPropSetter) {
         if (isSignal(value)) {
@@ -617,30 +771,95 @@ function bindClass(el, className, value, bindings, disposers) {
     }
 }
 /**
- * Bind trusted HTML content to an element's innerHTML.
+ * Bind branded HTML content to an element's inner markup.
  *
- * WARNING: This is for trusted content only (e.g., highlighted search results
- * from @orama/highlight, diff2html output). NEVER use with user-generated input.
+ * Never a bare string — a brand is the author's explicit decision about where
+ * the markup came from, which is what closes the accidental-XSS-sink class
+ * (ADR 0030.2 §3/§8). Three shapes resolve, in the order they are checked:
  *
- * Supports both static strings and reactive Signal<string> values.
- * When the signal changes, innerHTML is updated reactively.
+ * - `raw()` (core owns the `__raw` brand; @nisli/ssg re-exports it):
+ *   author-asserted trust → today's `innerHTML` sink, unchanged.
+ *   NEVER wrap user-generated input in raw().
+ * - `sanitized()` → the sanitizer sink: native `Element.setHTML()`, else the
+ *   `setSanitizerFallback()` hook, else N107. It NEVER reaches `innerHTML`
+ *   (ADR 0019:124–128, bet-09(c)).
+ * - A native `TrustedHTML` object → the same `innerHTML` sink as `raw()`,
+ *   passed through unwrapped so Trusted-Types-enforcing apps can assign
+ *   policy output directly.
+ *
+ * Anything else throws N106. Supports both static values and reactive
+ * `Signal`s of them; when the signal changes the content is rewritten through
+ * the same branch. null/undefined (branded or not) clears the content.
  *
  * Usage in templates:
- *   html`<span html:inner="${highlightedHtml}"></span>`
+ *   html`<span html:inner="${raw(highlightedHtml)}"></span>`
+ *   html`<span html:inner="${sanitized(userComment)}"></span>`
  */
 function bindInnerHtml(el, value, bindings, disposers) {
+    // PURE — validates the brand and proves a sink exists without writing
+    // anything, so the eager signal check below can run it for its throw alone.
+    // A SanitizedHtml resolves to ITSELF (the writer routes it to the
+    // sanitizer); everything else resolves to the innerHTML payload.
+    const resolveHtml = (v) => {
+        if (v == null)
+            return '';
+        if (isRawHtml(v)) {
+            // Both brands at once: trust is not resolvable in favour of the raw
+            // sink, so reject rather than guess which one the author meant.
+            if (isSanitizedHtml(v)) {
+                throw nisliError('N106', `html:inner rejects a value branded both raw() and sanitized() — the ` +
+                    `trust decision is ambiguous. Pick one brand.`);
+            }
+            return v.value;
+        }
+        if (isSanitizedHtml(v)) {
+            // FAIL CLOSED. Untrusted markup is only ever eligible to be written once
+            // a sanitizing sink is proven to exist; no native setHTML() and no
+            // registered hook is a hard error, because silently downgrading to
+            // innerHTML would reopen the exact XSS hole this brand closes.
+            if (sanitizerFor(el) === null) {
+                throw nisliError('N107', `html:inner cannot render sanitized() markup: this engine has no native ` +
+                    `Element.setHTML() and no fallback is registered. Wire one at startup — ` +
+                    `setSanitizerFallback((el, html) => { el.innerHTML = DOMPurify.sanitize(html) }) ` +
+                    `— nisli ships no sanitizer and will not fall back to innerHTML.`);
+            }
+            return v;
+        }
+        if (isTrustedHtml(v))
+            return v;
+        throw nisliError('N106', `html:inner rejects unbranded values (got ${typeof v}). Wrap trusted markup ` +
+            `in raw(html), untrusted markup in sanitized(html) — and never wrap ` +
+            `user-generated input in raw().`);
+    };
+    const writeHtml = (v) => {
+        const resolved = resolveHtml(v);
+        if (isSanitizedHtml(resolved)) {
+            // The sanitizer sink. resolveHtml has already proven a writer exists,
+            // and `el.innerHTML` is unreachable from this branch by construction.
+            sanitizerFor(el)?.(el, resolved.value);
+            return;
+        }
+        // The raw sink, unchanged: a plain string, or a TrustedHTML object handed
+        // over WITHOUT stringifying it (stringifying would defeat the CSP check).
+        // The cast only satisfies the DOM library's `string` typing.
+        el.innerHTML = resolved;
+    };
     if (isSignal(value)) {
+        // Validate the INITIAL value untracked and eagerly so an unbranded or
+        // unsanitizable signal throws synchronously out of mount(); later invalid
+        // values throw inside the effect and land in effect error containment
+        // (console.error, element content untouched).
+        untracked(() => resolveHtml(value.value));
         const binding = { type: 'innerHtml', element: el };
         bindings.push(binding);
         const dispose = effect(() => {
-            const v = value.value;
-            el.innerHTML = v == null ? '' : String(v);
+            writeHtml(value.value);
         });
         binding.dispose = dispose;
         disposers.push(dispose);
     }
     else {
-        el.innerHTML = value == null ? '' : String(value);
+        writeHtml(value);
     }
 }
 function bindEvent(el, eventName, handler, modifiers, bindings) {
@@ -693,9 +912,13 @@ function bindEvent(el, eventName, handler, modifiers, bindings) {
         }
     }
     // Wrap in try/catch for error containment — THIS is the installed handler.
+    // Handler bodies run UNTRACKED (ADR 0030.2 §8, surfaced by the T5 review):
+    // synchronous dispatchEvent from inside an effect would otherwise run the
+    // handler under that effect's observer — widening the effect's dependency
+    // set with every signal the handler reads and mis-attributing its writes.
     safeHandler = (e) => {
         try {
-            composed(e);
+            untrack(() => composed(e));
         }
         catch (err) {
             console.error(`Event handler error for '${eventName}':`, err);
@@ -716,17 +939,6 @@ function bindEvent(el, eventName, handler, modifiers, bindings) {
         dispose: () => el.removeEventListener(eventName, safeHandler),
     });
 }
-/**
- * Conditional rendering helper.
- * Shows the template when condition is truthy.
- *
- * Supports both static and reactive (signal) conditions.
- * For signal conditions, returns a computed that reactively switches
- * between the template and null.
- *
- * The template argument can be a TemplateResult or a lazy callback
- * `() => TemplateResult` to avoid evaluating expensive branches.
- */
 // ── each() reactive list rendering ──────────────────────────────────
 /** Brand for each result detection */
 const EACH_BRAND = Symbol.for('backlog.each');
@@ -744,6 +956,32 @@ const EACH_BRAND = Symbol.for('backlog.each');
  * )}</ul>`
  * ```
  */
+/**
+ * Adapt whatever a template callback returned into a mountable TemplateResult.
+ * Factory descriptors (the value `component()` factories actually return) are
+ * mounted through the same path every other slot uses (issue 0021).
+ */
+function asTemplateResult(result) {
+    if (result && typeof result === 'object' && '__templateResult' in result) {
+        return result;
+    }
+    if (result && typeof result === 'object' && result.__type === 'factory') {
+        let mounted = null;
+        return {
+            __templateResult: true,
+            mount(host) {
+                mounted = mountFactoryResult(result);
+                host.appendChild(mounted.element);
+            },
+            dispose() {
+                mounted?.dispose();
+                mounted?.element.remove();
+                mounted = null;
+            },
+        };
+    }
+    throw new TypeError(`each(): template callback must return a TemplateResult or a component factory result, got ${result === null ? 'null' : typeof result}`);
+}
 export function each(items, keyFn, templateFn) {
     let startMarker;
     let endMarker;
@@ -822,7 +1060,7 @@ export function each(items, keyFn, templateFn) {
                 const indexSignal = signal(index);
                 const wrapper = document.createElement('each-item');
                 wrapper.style.display = 'contents';
-                const templateResult = templateFn(itemSignal, indexSignal);
+                const templateResult = asTemplateResult(templateFn(itemSignal, indexSignal));
                 templateResult.mount(wrapper);
                 newEntries.push({ key, itemSignal, indexSignal, templateResult, wrapper });
             }
@@ -841,20 +1079,65 @@ export function each(items, keyFn, templateFn) {
         for (const entry of newEntries) {
             const nextSibling = cursor.nextSibling;
             if (nextSibling !== entry.wrapper) {
-                parent.insertBefore(entry.wrapper, nextSibling);
+                if (entry.wrapper.parentNode === parent && canMoveWithin(parent)) {
+                    // Already attached under this parent: atomic move preconditions hold.
+                    parent.moveBefore(entry.wrapper, nextSibling);
+                }
+                else {
+                    // Fresh wrapper, or a browser without moveBefore().
+                    parent.insertBefore(entry.wrapper, nextSibling);
+                }
             }
             cursor = entry.wrapper;
         }
         entries = newEntries;
     }
 }
-export function when(condition, template) {
-    const resolveTemplate = () => typeof template === 'function' ? template() : template;
+/**
+ * Conditional rendering helper (ADR 0030.2 §3, boolean-gated with `else`).
+ *
+ * Shows `template` when the condition is truthy, `elseTemplate` (optional)
+ * when falsy. Both arms accept a TemplateResult or a lazy callback
+ * `() => TemplateResult`; callbacks are only evaluated for the active arm.
+ *
+ * Semantics for signal conditions:
+ * - The gate is `!!condition.value` — a truthy→truthy (or falsy→falsy)
+ *   transition returns the memoized previous result, so the live branch is
+ *   NEVER rebuilt (no state/scroll/focus loss) and callbacks never re-run.
+ * - Branch callbacks evaluate UNTRACKED: a signal read during branch
+ *   construction does not subscribe the when() computed, so it cannot
+ *   trigger a rebuild. Reactive parts inside a branch must be interpolated
+ *   as signals/computeds (values), not read raw at construction time.
+ */
+export function when(condition, template, elseTemplate) {
+    const resolveBranch = (branch) => {
+        if (branch === undefined)
+            return null;
+        if (typeof branch === 'function')
+            return untracked(branch);
+        return branch;
+    };
     if (isSignal(condition)) {
-        // Reactive: return a computed that re-evaluates when the signal changes
-        return computed(() => condition.value ? resolveTemplate() : null);
+        // Boolean-gated memo: notify() marks observers dirty EAGERLY (before
+        // value-equality is known), so a computed chain alone cannot stop a
+        // truthy→truthy recompute from re-evaluating the branch. The memo pins
+        // branch evaluation to actual boolean FLIPS; equal gates return the
+        // cached result, which the slot then memoizes by identity (ADR 0008.1).
+        let lastGate;
+        let lastResult = null;
+        return computed(() => {
+            const gate = !!condition.value;
+            if (gate === lastGate)
+                return lastResult;
+            const next = gate ? resolveBranch(template) : resolveBranch(elseTemplate);
+            // Commit the memo only after a successful resolve so a throwing branch
+            // callback retries on the next read (computed error containment).
+            lastGate = gate;
+            lastResult = next;
+            return next;
+        });
     }
-    return condition ? resolveTemplate() : null;
+    return condition ? resolveBranch(template) : resolveBranch(elseTemplate);
 }
 /**
  * Build a DOM element by a (possibly *dynamic*) tag name with reactive