@nisli/core 0.54.0 → 0.55.0

package/dist/template.js

@@ -11,6 +11,109 @@
  */
 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;
         },
     };
 }
@@ -287,159 +437,145 @@ function replaceMarkerWithBinding(comment, value, bindings, disposers) {
     if (!parent)
         return;
     if (isSignal(value)) {
-        // Probe the current value WITHOUT tracking. This read runs during mount,
-        // which may execute inside an enclosing reactive scope (a parent reactive
-        // slot's effect, or an each() reconcile effect). The real subscription for
-        // THIS slot is established by the dedicated inner effect(s) below — the
-        // probe is only used to decide which kind of binding to create. If the
-        // probe were tracked, every nested `${signal}` slot would leak its signal
-        // (and its transitive deps) into the enclosing effect, so unrelated state
-        // changes would tear down and rebuild the whole subtree. Mount must never
-        // establish dependencies in the enclosing scope — same principle as the
-        // child-component connectedCallback isolation (ADR 0008 Gap 1).
-        let signalValue;
-        untrack(() => { signalValue = value.value; });
-        // Check if the signal holds a TemplateResult, factory, null, undefined, or array
-        // (e.g., from reactive when(), computed(() => items.map(renderFn)), or factory results)
-        const isReactiveSlot = signalValue === null || signalValue === undefined
-            || (signalValue && typeof signalValue === 'object' && '__templateResult' in signalValue)
-            || (signalValue && typeof signalValue === 'object' && '__type' in signalValue)
-            || Array.isArray(signalValue);
-        if (isReactiveSlot) {
-            // Reactive template slot — mount/unmount templates as signal changes
-            const startMarker = document.createComment('slot-start');
-            const endMarker = document.createComment('slot-end');
-            parent.replaceChild(endMarker, comment);
-            parent.insertBefore(startMarker, endMarker);
-            let currentResults = [];
-            let currentNodes = [];
-            let currentFactoryDisposers = [];
-            // Sentinel distinct from any resolvable value (including null/undefined)
-            // so the FIRST effect run always mounts. See ADR 0008.1.
-            const NOT_RENDERED = Symbol('not-rendered');
-            let lastValue = NOT_RENDERED;
-            const dispose = effect(() => {
-                const newValue = value.value;
-                // Use endMarker.parentNode — the captured `parent` may be a
-                // DocumentFragment that was already appended to the real DOM,
-                // leaving the markers reparented under the actual DOM element.
-                const liveParent = endMarker.parentNode;
-                if (!liveParent)
-                    return;
-                // Memoize by referential identity. A computed/signal only notifies
-                // when its value changes by Object.is, so an EQUAL value here means
-                // this effect was re-triggered by some OTHER dependency (a tracking
-                // leak), not by an actual change to this slot. Re-mounting identical
-                // content would destroy live DOM (and reset scroll/focus) for nothing.
-                // Defense-in-depth against the leak class fixed at the probe in this
-                // same file. See ADR 0008.1.
-                if (newValue === lastValue)
-                    return;
-                lastValue = newValue;
-                // Dispose and remove the previous slot value before mounting the next.
-                // Ownership is per VALUE, not per outer template lifetime: factory prop
-                // subscriptions must stop as soon as their child leaves (issue 0011).
-                for (const r of currentResults) {
-                    try {
-                        r.dispose();
-                    }
-                    catch (_) { }
-                }
-                for (const dispose of currentFactoryDisposers) {
-                    try {
-                        dispose();
-                    }
-                    catch (_) { }
-                }
-                for (const node of currentNodes) {
-                    node.parentNode?.removeChild(node);
+        // Every reactive child is a slot because its future values may have any
+        // documented child type. The slot still keeps a single Text node alive for
+        // primitive-to-primitive updates, preserving the O(1) text fast path.
+        const startMarker = document.createComment('slot-start');
+        const endMarker = document.createComment('slot-end');
+        parent.replaceChild(endMarker, comment);
+        parent.insertBefore(startMarker, endMarker);
+        let currentResults = [];
+        let currentNodes = [];
+        let currentFactoryDisposers = [];
+        let currentText = null;
+        // Sentinel distinct from any resolvable value (including null/undefined)
+        // so the FIRST effect run always mounts. See ADR 0008.1.
+        const NOT_RENDERED = Symbol('not-rendered');
+        let lastValue = NOT_RENDERED;
+        const dispose = effect(() => {
+            const newValue = value.value;
+            // Use endMarker.parentNode — the captured `parent` may be a
+            // DocumentFragment that was already appended to the real DOM,
+            // leaving the markers reparented under the actual DOM element.
+            const liveParent = endMarker.parentNode;
+            if (!liveParent)
+                return;
+            // Memoize by referential identity. A computed/signal only notifies
+            // when its value changes by Object.is, so an EQUAL value here means
+            // this effect was re-triggered by some OTHER dependency (a tracking
+            // leak), not by an actual change to this slot. Re-mounting identical
+            // content would destroy live DOM (and reset scroll/focus) for nothing.
+            // See ADR 0008.1.
+            if (newValue === lastValue)
+                return;
+            lastValue = newValue;
+            const isTemplate = Boolean(newValue
+                && typeof newValue === 'object'
+                && '__templateResult' in newValue);
+            const isFactory = Boolean(newValue
+                && typeof newValue === 'object'
+                && '__type' in newValue
+                && newValue.__type === 'factory');
+            const isPrimitive = newValue != null
+                && newValue !== false
+                && !Array.isArray(newValue)
+                && !isTemplate
+                && !isFactory;
+            if (isPrimitive && currentText) {
+                currentText.data = String(newValue);
+                return;
+            }
+            // Dispose and remove the previous slot value before mounting the next.
+            // Ownership is per VALUE, not per outer template lifetime: factory prop
+            // subscriptions must stop as soon as their child leaves (issue 0011).
+            for (const r of currentResults) {
+                try {
+                    r.dispose();
                 }
-                currentNodes = [];
-                currentResults = [];
-                currentFactoryDisposers = [];
-                if (newValue == null) {
-                    // null/undefined — nothing to mount
+                catch (_) { }
+            }
+            for (const dispose of currentFactoryDisposers) {
+                try {
+                    dispose();
                 }
-                else if (Array.isArray(newValue)) {
-                    // Array of TemplateResults (or mixed content)
-                    for (const item of newValue) {
-                        if (item && typeof item === 'object' && '__templateResult' in item) {
-                            const tpl = item;
-                            const wrapper = document.createDocumentFragment();
-                            tpl.mount(wrapper);
-                            const nodes = [...wrapper.childNodes];
-                            currentNodes.push(...nodes);
-                            currentResults.push(tpl);
-                            liveParent.insertBefore(wrapper, endMarker);
-                        }
-                        else if (item && typeof item === 'object' && '__type' in item && item.__type === 'factory') {
-                            const mounted = mountFactoryResult(item);
-                            currentNodes.push(mounted.element);
-                            currentFactoryDisposers.push(mounted.dispose);
-                            liveParent.insertBefore(mounted.element, endMarker);
-                        }
-                        else if (item != null && item !== false) {
-                            const textNode = document.createTextNode(String(item));
-                            currentNodes.push(textNode);
-                            liveParent.insertBefore(textNode, endMarker);
-                        }
+                catch (_) { }
+            }
+            for (const node of currentNodes) {
+                node.parentNode?.removeChild(node);
+            }
+            currentNodes = [];
+            currentResults = [];
+            currentFactoryDisposers = [];
+            currentText = null;
+            if (newValue == null) {
+                // null/undefined — nothing to mount
+            }
+            else if (Array.isArray(newValue)) {
+                // Array of TemplateResults (or mixed content)
+                for (const item of newValue) {
+                    if (item && typeof item === 'object' && '__templateResult' in item) {
+                        const tpl = item;
+                        const wrapper = document.createDocumentFragment();
+                        tpl.mount(wrapper);
+                        const nodes = [...wrapper.childNodes];
+                        currentNodes.push(...nodes);
+                        currentResults.push(tpl);
+                        liveParent.insertBefore(wrapper, endMarker);
                     }
-                }
-                else if (typeof newValue === 'object' && '__templateResult' in newValue) {
-                    // Single TemplateResult
-                    const tpl = newValue;
-                    const wrapper = document.createDocumentFragment();
-                    tpl.mount(wrapper);
-                    currentNodes = [...wrapper.childNodes];
-                    currentResults.push(tpl);
-                    liveParent.insertBefore(wrapper, endMarker);
-                }
-                else if (typeof newValue === 'object' && '__type' in newValue && newValue.__type === 'factory') {
-                    // Factory result — create child element
-                    const mounted = mountFactoryResult(newValue);
-                    currentNodes.push(mounted.element);
-                    currentFactoryDisposers.push(mounted.dispose);
-                    liveParent.insertBefore(mounted.element, endMarker);
-                }
-                else if (newValue !== false) {
-                    // Primitive reached from an initially null/undefined reactive slot.
-                    const textNode = document.createTextNode(String(newValue));
-                    currentNodes.push(textNode);
-                    liveParent.insertBefore(textNode, endMarker);
-                }
-            });
-            disposers.push(dispose);
-            // TemplateResult.dispose() intentionally leaves mounted DOM in place, but
-            // it must still dispose bindings owned by the CURRENT reactive slot value.
-            // Previously that cleanup only happened on the next value change.
-            disposers.push(() => {
-                for (const r of currentResults.splice(0)) {
-                    try {
-                        r.dispose();
+                    else if (item && typeof item === 'object' && '__type' in item && item.__type === 'factory') {
+                        const mounted = mountFactoryResult(item);
+                        currentNodes.push(mounted.element);
+                        currentFactoryDisposers.push(mounted.dispose);
+                        liveParent.insertBefore(mounted.element, endMarker);
                     }
-                    catch (_) { }
-                }
-                for (const factoryDispose of currentFactoryDisposers.splice(0)) {
-                    try {
-                        factoryDispose();
+                    else if (item != null && item !== false) {
+                        const textNode = document.createTextNode(String(item));
+                        currentNodes.push(textNode);
+                        liveParent.insertBefore(textNode, endMarker);
                     }
-                    catch (_) { }
                 }
-                currentNodes = [];
-            });
-        }
-        else {
-            // Primitive signal — create a reactive text node
-            const textNode = document.createTextNode(String(signalValue));
-            parent.replaceChild(textNode, comment);
-            const binding = { type: 'text', node: textNode };
-            bindings.push(binding);
-            const dispose = effect(() => {
-                textNode.data = String(value.value);
-            });
-            binding.dispose = dispose;
-            disposers.push(dispose);
-        }
+            }
+            else if (isTemplate) {
+                // Single TemplateResult
+                const tpl = newValue;
+                const wrapper = document.createDocumentFragment();
+                tpl.mount(wrapper);
+                currentNodes = [...wrapper.childNodes];
+                currentResults.push(tpl);
+                liveParent.insertBefore(wrapper, endMarker);
+            }
+            else if (isFactory) {
+                // Factory result — create child element
+                const mounted = mountFactoryResult(newValue);
+                currentNodes.push(mounted.element);
+                currentFactoryDisposers.push(mounted.dispose);
+                liveParent.insertBefore(mounted.element, endMarker);
+            }
+            else if (newValue !== false) {
+                currentText = document.createTextNode(String(newValue));
+                currentNodes.push(currentText);
+                liveParent.insertBefore(currentText, endMarker);
+            }
+        });
+        disposers.push(dispose);
+        // TemplateResult.dispose() intentionally leaves mounted DOM in place, but
+        // it must still dispose bindings owned by the CURRENT reactive slot value.
+        disposers.push(() => {
+            for (const r of currentResults.splice(0)) {
+                try {
+                    r.dispose();
+                }
+                catch (_) { }
+            }
+            for (const factoryDispose of currentFactoryDisposers.splice(0)) {
+                try {
+                    factoryDispose();
+                }
+                catch (_) { }
+            }
+            currentNodes = [];
+            currentText = null;
+        });
     }
     else if (value && typeof value === 'object' && '__templateResult' in value) {
         // Nested template result — mount it
@@ -502,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)) {
@@ -631,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) {
@@ -707,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);
@@ -730,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');
@@ -790,6 +988,26 @@ export function each(items, keyFn, templateFn) {
         const parent = endMarker.parentNode;
         if (!parent)
             return;
+        // Validate the whole key set before updating item signals, mounting new
+        // entries, or touching DOM. A duplicate update must leave the last valid
+        // reconciliation intact so a later corrected array can recover normally.
+        const keyedItems = [];
+        const keyIndices = new Map();
+        for (let i = 0; i < newItems.length; i++) {
+            const item = newItems[i];
+            if (item === undefined)
+                continue;
+            const key = keyFn(item, i);
+            const previousIndex = keyIndices.get(key);
+            if (previousIndex !== undefined) {
+                const formattedKey = typeof key === 'string' ? JSON.stringify(key) : String(key);
+                console.error(`each() requires unique keys. Duplicate key ${formattedKey} ` +
+                    `found at indices ${previousIndex} and ${i}; reconciliation skipped.`);
+                return;
+            }
+            keyIndices.set(key, i);
+            keyedItems.push({ item, index: i, key });
+        }
         // Build old key → entry map
         const oldMap = new Map();
         for (const entry of entries) {
@@ -798,17 +1016,13 @@ export function each(items, keyFn, templateFn) {
         // Build new entries list
         const newEntries = [];
         const newKeys = new Set();
-        for (let i = 0; i < newItems.length; i++) {
-            const item = newItems[i];
-            if (item === undefined)
-                continue;
-            const key = keyFn(item, i);
+        for (const { item, index, key } of keyedItems) {
             newKeys.add(key);
             const existing = oldMap.get(key);
             if (existing) {
                 // Reuse — update signals in place
                 existing.itemSignal.value = item;
-                existing.indexSignal.value = i;
+                existing.indexSignal.value = index;
                 newEntries.push(existing);
             }
             else {
@@ -817,7 +1031,7 @@ export function each(items, keyFn, templateFn) {
                 // inner reactive content can freely swap DOM nodes without
                 // invalidating the each() reconciler's node tracking.
                 const itemSignal = signal(item);
-                const indexSignal = signal(i);
+                const indexSignal = signal(index);
                 const wrapper = document.createElement('each-item');
                 wrapper.style.display = 'contents';
                 const templateResult = templateFn(itemSignal, indexSignal);
@@ -839,20 +1053,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