snice 7.5.0 → 7.7.0

package/dist/index.iife.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.4.0
+ * snice v7.6.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.
@@ -717,6 +717,18 @@ var Snice = (function (exports) {
             }
         };
     }
+    /** Resolve and validate an @on/@dispatch debounce or throttle interval. */
+    function resolveEventTiming(instance, timing, decorator, option) {
+        if (timing === undefined)
+            return undefined;
+        const value = typeof timing === 'function'
+            ? timing.call(instance)
+            : timing;
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+            throw new TypeError(`${decorator} ${option} must resolve to a finite, non-negative number of milliseconds.`);
+        }
+        return value;
+    }
     /**
      * Resolve a scope option to a concrete EventTarget.
      *
@@ -1850,6 +1862,11 @@ var Snice = (function (exports) {
         else if (selectorOrOptions === null && options) {
             opts = options;
         }
+        // `target` is the options-object spelling of the positional selector; fold it
+        // into the same delegation path. The positional argument wins when both are given.
+        if (!selector && opts.target) {
+            selector = opts.target;
+        }
         return function (originalMethod, context) {
             const methodName = context.name;
             context.addInitializer(function () {
@@ -1861,7 +1878,7 @@ var Snice = (function (exports) {
                 // and child registrations pollute parent (and vice versa) via the
                 // prototype chain.
                 const eventNames = Array.isArray(eventName) ? eventName : [eventName];
-                const registrationKey = `${methodName}::${eventNames.join(',')}::${selector ?? ''}::daemon:${opts.daemon ?? ''}`;
+                const registrationKey = `${methodName}::${eventNames.join(',')}::${selector ?? ''}::daemon:${opts.daemon ?? ''}::light:${opts.light ?? ''}::shadow:${opts.shadow ?? ''}`;
                 if (!Object.prototype.hasOwnProperty.call(constructor, ON_METHODS)) {
                     constructor[ON_METHODS] = new Set();
                 }
@@ -1941,6 +1958,10 @@ var Snice = (function (exports) {
             const currentMethod = instance[handler.methodName];
             let boundMethod = currentMethod ? currentMethod.bind(instance) : handler.method.bind(instance);
             const handlerOptions = handler.options || {};
+            const debounceDelay = resolveEventTiming(instance, handlerOptions.debounce, '@on', 'debounce');
+            const throttleDelay = debounceDelay && debounceDelay > 0
+                ? undefined
+                : resolveEventTiming(instance, handlerOptions.throttle, '@on', 'throttle');
             // Parse event name for key modifiers
             // Supports both dot notation (@keydown.enter) and colon notation (@keydown:Enter)
             // Only parse colons for keyboard events, not custom events
@@ -1961,13 +1982,13 @@ var Snice = (function (exports) {
             if (delimiterIndex <= 0)
                 warnIfModifierMisuse(handler.eventName);
             // Apply debounce (takes precedence over throttle)
-            if (handlerOptions.debounce && handlerOptions.debounce > 0) {
-                const debounced = createDebounced(boundMethod, handlerOptions.debounce);
+            if (debounceDelay && debounceDelay > 0) {
+                const debounced = createDebounced(boundMethod, debounceDelay);
                 instance[CLEANUP].eventCancels.push(() => debounced.cancel());
                 boundMethod = debounced;
             }
-            else if (handlerOptions.throttle && handlerOptions.throttle > 0) {
-                boundMethod = throttle$1(boundMethod, handlerOptions.throttle);
+            else if (throttleDelay && throttleDelay > 0) {
+                boundMethod = throttle$1(boundMethod, throttleDelay);
             }
             // Create event handler with key modifier support
             // Uses shared keyboard filter implementation from parts.ts
@@ -1975,15 +1996,21 @@ var Snice = (function (exports) {
             if (keyModifier && ['keydown', 'keyup', 'keypress'].includes(baseEventName)) {
                 keyFilter = parseKeyboardFilter(keyModifier);
             }
+            // Returns whether the method actually ran, so `once` can be managed
+            // manually: native `once` consumes the listener on ANY invocation — a
+            // non-matching key or (with multiple tree listeners) a different root
+            // would either eat the single firing or allow a second one.
             const createKeyModifierHandler = (method) => {
                 if (!keyFilter) {
-                    return method;
+                    return (event) => { method(event); return true; };
                 }
                 return (event) => {
                     const keyEvent = event;
                     if (matchesKeyboardFilter(keyEvent, keyFilter)) {
                         method(event);
+                        return true;
                     }
+                    return false;
                 };
             };
             // Apply key modifier wrapper
@@ -2001,6 +2028,20 @@ var Snice = (function (exports) {
                 continue;
             }
             const hasExplicitTarget = hasExplicitScope || hasDaemon;
+            // Tree toggles — the same light/shadow pair @query uses. Both default to
+            // true: direct listeners attach in both trees, delegated listeners match
+            // in both. An explicit scope/daemon owns the listener target outright, so
+            // the flags are meaningless there and ignored with a warning.
+            const inShadow = handlerOptions.shadow !== false;
+            const inLight = handlerOptions.light !== false;
+            if (hasExplicitTarget
+                && (handlerOptions.light !== undefined || handlerOptions.shadow !== undefined)) {
+                console.warn(`[snice/@on] light/shadow are ignored for "${handler.eventName}" — an explicit scope/daemon owns the listener target.`);
+            }
+            if (!hasExplicitTarget && !inShadow && !inLight) {
+                console.warn(`[snice/@on] "${handler.eventName}" disables both light and shadow — listener skipped.`);
+                continue;
+            }
             let scopedTarget = null;
             if (hasDaemon) {
                 try {
@@ -2022,56 +2063,125 @@ var Snice = (function (exports) {
             }
             // Main event handler with error handling and event delegation
             if (handler.selector) {
-                // Delegated event handling.
-                // - Default eventRoot: shadow root if present, else host element.
-                // - With explicit scope: attach to the scoped target instead.
-                const eventRoot = hasExplicitTarget
-                    ? scopedTarget
-                    : (targetElement.shadowRoot || targetElement);
-                const delegatedHandler = (event) => {
-                    const target = event.target;
-                    const matchingElement = (target.matches && target.matches(handler.selector) && target) ||
-                        (target.closest && target.closest(handler.selector)) ||
-                        null;
-                    if (!matchingElement)
-                        return;
-                    if (handlerOptions.preventDefault)
-                        event.preventDefault();
-                    if (handlerOptions.stopPropagation) {
-                        event.stopPropagation();
-                        event.stopImmediatePropagation();
-                    }
-                    try {
-                        keyModifierMethod(event);
-                    }
-                    catch (error) {
-                        console.error(`Error in event handler ${handler.methodName}:`, error);
-                    }
-                };
+                // Delegated event handling. Listener roots by tree toggle:
+                // - shadow → the shadow root (when present)
+                // - light  → the host element (hears light-DOM bubbles)
+                // - explicit scope: the scoped target only
+                const componentShadowRoot = targetElement.shadowRoot;
+                const delegationRoots = hasExplicitTarget
+                    ? [scopedTarget]
+                    : [
+                        ...(inShadow && componentShadowRoot ? [componentShadowRoot] : []),
+                        ...(inLight ? [targetElement] : []),
+                    ];
+                if (delegationRoots.length === 0) {
+                    console.warn(`[snice/@on] "${handler.eventName}" cannot delegate "${handler.selector}" — no shadow root and light disabled; listener skipped.`);
+                    continue;
+                }
+                // One event can reach more than one root (e.g. a slotted click seen by
+                // both the shadow root and the host); a per-handler Symbol keeps the
+                // handler to one invocation per event. The symbol is only stamped on a
+                // match so a non-matching root never blocks the other.
+                const handledSymbol = Symbol();
                 // Auto-enable capture for non-bubbling events when using delegation
                 const needsCapture = NON_BUBBLING_EVENTS.has(baseEventName);
                 const useCapture = handlerOptions.capture !== undefined
                     ? handlerOptions.capture
                     : needsCapture;
+                // `once` is managed manually (never native): the handler fires exactly
+                // once — a non-matching event or key must not consume it, and a match
+                // must retire the listeners on EVERY root, not just the one that fired.
                 const listenerOptions = {
                     capture: useCapture,
-                    once: handlerOptions.once || false,
+                    once: false,
                     passive: handlerOptions.passive || false,
                 };
-                eventRoot.addEventListener(baseEventName, delegatedHandler, listenerOptions);
-                instance[CLEANUP].events.push({
-                    target: eventRoot,
-                    eventName: baseEventName,
-                    handler: delegatedHandler,
-                    options: listenerOptions,
-                });
+                const listenerGroup = [];
+                const removeGroup = () => {
+                    for (const entry of listenerGroup) {
+                        entry.target.removeEventListener(baseEventName, entry.handler, listenerOptions);
+                    }
+                };
+                for (const eventRoot of delegationRoots) {
+                    // Delegation matches only elements visible in the listener's own tree
+                    // scope: a shadow-root listener matches its shadow tree, anything else
+                    // matches its containing document/root. This mirrors native retargeting
+                    // (child-component internals never match) while still matching a shadow
+                    // wrapper when the click lands on light-DOM content slotted into it —
+                    // `target.closest()` alone cannot cross that slot boundary.
+                    const treeScope = eventRoot instanceof ShadowRoot
+                        ? eventRoot
+                        : (eventRoot.getRootNode?.() ?? document);
+                    const findDelegateMatch = (event) => {
+                        if (typeof event.composedPath !== 'function') {
+                            // Fallback for environments without composedPath: ancestor walk.
+                            const target = event.target;
+                            return (target.matches && target.matches(handler.selector) && target)
+                                || (target.closest && target.closest(handler.selector))
+                                || null;
+                        }
+                        for (const node of event.composedPath()) {
+                            const el = node;
+                            if (el === eventRoot)
+                                break;
+                            if (el.nodeType !== 1)
+                                continue;
+                            if (el.getRootNode() !== treeScope)
+                                continue;
+                            if (el.matches(handler.selector))
+                                return el;
+                        }
+                        return null;
+                    };
+                    const delegatedHandler = (event) => {
+                        if (event[handledSymbol])
+                            return;
+                        const matchingElement = findDelegateMatch(event);
+                        if (!matchingElement)
+                            return;
+                        event[handledSymbol] = true;
+                        if (handlerOptions.preventDefault)
+                            event.preventDefault();
+                        if (handlerOptions.stopPropagation) {
+                            event.stopPropagation();
+                            event.stopImmediatePropagation();
+                        }
+                        let fired = false;
+                        try {
+                            fired = keyModifierMethod(event);
+                        }
+                        catch (error) {
+                            // A throw can only escape user code, so the handler DID run.
+                            fired = true;
+                            console.error(`Error in event handler ${handler.methodName}:`, error);
+                        }
+                        if (fired && handlerOptions.once)
+                            removeGroup();
+                    };
+                    eventRoot.addEventListener(baseEventName, delegatedHandler, listenerOptions);
+                    listenerGroup.push({ target: eventRoot, handler: delegatedHandler });
+                    instance[CLEANUP].events.push({
+                        target: eventRoot,
+                        eventName: baseEventName,
+                        handler: delegatedHandler,
+                        options: listenerOptions,
+                    });
+                }
             }
             else {
                 // Direct event handling.
                 // - Default: shadow root + host element (so events inside shadow and on
                 //   the host itself both fire). A per-handler Symbol dedupes.
+                // - light/shadow narrow the attachment: shadow → the shadow root
+                //   listener, light → the host listener.
                 // - With explicit scope: attach to the scoped target ONLY (no duplication).
-                const shadowRoot = hasExplicitTarget ? null : targetElement.shadowRoot;
+                const shadowRoot = (hasExplicitTarget || !inShadow)
+                    ? null
+                    : targetElement.shadowRoot;
+                if (!hasExplicitTarget && !shadowRoot && !inLight) {
+                    console.warn(`[snice/@on] "${handler.eventName}" requests shadow only but the element has no shadow root — listener skipped.`);
+                    continue;
+                }
                 // Per-handler private Symbol so dedup is scoped to THIS handler's two
                 // listeners (shadowRoot + host). Using Symbol.for() with the method name
                 // would collide across components that share a method name (e.g. a parent
@@ -2079,6 +2189,20 @@ var Snice = (function (exports) {
                 // handler to be silently swallowed when events bubble up through a
                 // shadow boundary.
                 const handledSymbol = Symbol();
+                // `once` is managed manually (never native): a key-filtered handler must
+                // not be consumed by a non-matching key, and with listeners in two trees
+                // the first real firing must retire BOTH, not just the one that fired.
+                const listenerOptions = {
+                    capture: handlerOptions.capture || false,
+                    once: false,
+                    passive: handlerOptions.passive || false,
+                };
+                const listenerGroup = [];
+                const removeGroup = () => {
+                    for (const entry of listenerGroup) {
+                        entry.target.removeEventListener(baseEventName, entry.handler, listenerOptions);
+                    }
+                };
                 const wrappedMethod = (event) => {
                     if (event[handledSymbol])
                         return;
@@ -2087,46 +2211,39 @@ var Snice = (function (exports) {
                         event.preventDefault();
                     if (handlerOptions.stopPropagation)
                         event.stopPropagation();
+                    let fired = false;
                     try {
-                        keyModifierMethod(event);
+                        fired = keyModifierMethod(event);
                     }
                     catch (error) {
+                        // A throw can only escape user code, so the handler DID run.
+                        fired = true;
                         console.error(`Error in event handler ${handler.methodName}:`, error);
                     }
+                    if (fired && handlerOptions.once)
+                        removeGroup();
                 };
-                const listenerOptions = {
-                    capture: handlerOptions.capture || false,
-                    once: handlerOptions.once || false,
-                    passive: handlerOptions.passive || false,
-                };
-                if (hasExplicitTarget) {
-                    scopedTarget.addEventListener(baseEventName, wrappedMethod, listenerOptions);
+                const attach = (target) => {
+                    target.addEventListener(baseEventName, wrappedMethod, listenerOptions);
+                    listenerGroup.push({ target, handler: wrappedMethod });
                     instance[CLEANUP].events.push({
-                        target: scopedTarget,
+                        target,
                         eventName: baseEventName,
                         handler: wrappedMethod,
                         options: listenerOptions,
                     });
+                };
+                if (hasExplicitTarget) {
+                    attach(scopedTarget);
                     continue;
                 }
-                if (shadowRoot) {
-                    // Listen on shadow root for events inside shadow DOM
-                    shadowRoot.addEventListener(baseEventName, wrappedMethod, listenerOptions);
-                    instance[CLEANUP].events.push({
-                        target: shadowRoot,
-                        eventName: baseEventName,
-                        handler: wrappedMethod,
-                        options: listenerOptions,
-                    });
-                }
-                // Also listen on host element (for clicks on host itself or when no shadow root)
-                targetElement.addEventListener(baseEventName, wrappedMethod, listenerOptions);
-                instance[CLEANUP].events.push({
-                    target: targetElement,
-                    eventName: baseEventName,
-                    handler: wrappedMethod,
-                    options: listenerOptions,
-                });
+                // Listen on shadow root for events inside shadow DOM
+                if (shadowRoot)
+                    attach(shadowRoot);
+                // Also listen on host element (for clicks on host itself, light-DOM
+                // bubbles, or when no shadow root) — unless light is disabled.
+                if (inLight)
+                    attach(targetElement);
             }
         }
     }
@@ -2146,6 +2263,185 @@ var Snice = (function (exports) {
         instance[CLEANUP].events = [];
     }
 
+    // @dispatch decorator - auto-dispatches custom events from method return values
+    const DISPATCH_GENERATION = getSymbol('dispatch-generation');
+    function isDispatchGenerationActive(instance, generation) {
+        return (instance[DISPATCH_GENERATION] ?? 0) === generation;
+    }
+    /**
+     * Decorator that automatically dispatches a custom event after a method is called.
+     * The return value of the method becomes the event detail.
+     *
+     * @param eventName The name of the event to dispatch
+     * @param options Optional configuration extending EventInit
+     */
+    function dispatch(eventName, options) {
+        return function (originalMethod, _context) {
+            // Decorator-instance identity avoids collisions such as event `a_b` on
+            // method `c` versus event `a` on method `b_c`.
+            const timerKey = Symbol(`@dispatch:${eventName}`);
+            return function (...args) {
+                // Resolve against the actual decorated instance for every invocation.
+                // Capture the generation before calling an async method so teardown can
+                // invalidate work that has not reached the scheduling step yet.
+                const generation = this[DISPATCH_GENERATION] ?? 0;
+                // Create timing wrappers for dispatch (per-instance)
+                if (!this[DISPATCH_TIMERS]) {
+                    this[DISPATCH_TIMERS] = new Map();
+                }
+                if (!this[DISPATCH_TIMERS].has(timerKey)) {
+                    this[DISPATCH_TIMERS].set(timerKey, {
+                        debounceTimeout: null,
+                        throttleLastCall: 0,
+                        throttleTimeout: null,
+                        invocation: 0,
+                    });
+                }
+                const timers = this[DISPATCH_TIMERS].get(timerKey);
+                const debounceDelay = resolveEventTiming(this, options?.debounce, '@dispatch', 'debounce');
+                const throttleDelay = debounceDelay && debounceDelay > 0
+                    ? undefined
+                    : resolveEventTiming(this, options?.throttle, '@dispatch', 'throttle');
+                const invocation = ++timers.invocation;
+                // A new invocation supersedes deferred work for this decorated method.
+                // In particular, a resolver changing debounce to 0 must not leave the
+                // previous positive-delay timer armed. Throttle trailing work is also
+                // rebuilt below using this invocation's freshly resolved interval.
+                if (timers.debounceTimeout)
+                    clearTimeout(timers.debounceTimeout);
+                timers.debounceTimeout = null;
+                if (timers.throttleTimeout)
+                    clearTimeout(timers.throttleTimeout);
+                timers.throttleTimeout = null;
+                timers.latestDetail = undefined;
+                if (debounceDelay && debounceDelay > 0) {
+                    // Switching from throttle to debounce starts a new timing regime.
+                    timers.throttleLastCall = 0;
+                }
+                else if (!throttleDelay || throttleDelay <= 0) {
+                    // An un-timed invocation cancels both old regimes completely.
+                    timers.throttleLastCall = 0;
+                }
+                // Call the original method with preserved this context
+                const result = originalMethod.apply(this, args);
+                // Helper to dispatch the event
+                const doDispatch = (detail) => {
+                    // Skip dispatch if result is undefined and dispatchOnUndefined is false
+                    if (detail === undefined && options?.dispatchOnUndefined === false) {
+                        return;
+                    }
+                    // Copy only platform EventInit fields; Snice-only decorator options do
+                    // not belong in the CustomEvent constructor dictionary.
+                    const event = new CustomEvent(eventName, {
+                        bubbles: options?.bubbles ?? true,
+                        cancelable: options?.cancelable ?? false,
+                        composed: options?.composed ?? true,
+                        detail
+                    });
+                    if (options?.scope !== undefined && options?.daemon !== undefined) {
+                        throw new TypeError(`@dispatch('${eventName}') cannot use both scope and daemon.`);
+                    }
+                    if (options?.daemon !== undefined) {
+                        requireDaemonTarget(this, options.daemon).dispatchEvent(event);
+                        return;
+                    }
+                    if (options?.scope !== undefined) {
+                        const target = resolveScope(this, options.scope);
+                        if (!target) {
+                            console.warn(`[snice/@dispatch] scope did not resolve for "${eventName}" — event not dispatched.`);
+                            return;
+                        }
+                        target.dispatchEvent(event);
+                        return;
+                    }
+                    const target = defaultCommunicationTarget(this);
+                    if (!target) {
+                        throw new TypeError(`@dispatch('${eventName}') requires an element, attached controller, or provided @daemon instance.`);
+                    }
+                    target.dispatchEvent(event);
+                };
+                // Helper to handle timed dispatch
+                const timedDispatch = (detail) => {
+                    if (!isDispatchGenerationActive(this, generation))
+                        return;
+                    if (debounceDelay && debounceDelay > 0) {
+                        timers.debounceTimeout = setTimeout(() => {
+                            timers.debounceTimeout = null;
+                            if (isDispatchGenerationActive(this, generation) && timers.invocation === invocation) {
+                                doDispatch(detail);
+                            }
+                        }, debounceDelay);
+                        return;
+                    }
+                    if (!throttleDelay || throttleDelay <= 0) {
+                        doDispatch(detail);
+                        return;
+                    }
+                    const now = Date.now();
+                    const remaining = throttleDelay - (now - timers.throttleLastCall);
+                    if (remaining <= 0) {
+                        clearTimeout(timers.throttleTimeout);
+                        timers.throttleLastCall = now;
+                        doDispatch(detail);
+                        return;
+                    }
+                    // Record the LATEST detail so the trailing dispatch carries fresh
+                    // data, not the first-suppressed-call detail captured by closure.
+                    timers.latestDetail = detail;
+                    // Always schedule from the last actual dispatch using the interval
+                    // resolved for THIS invocation. A later invocation can therefore
+                    // lengthen or shorten the pending trailing window coherently.
+                    timers.throttleTimeout = setTimeout(() => {
+                        timers.throttleLastCall = Date.now();
+                        timers.throttleTimeout = null;
+                        const d = timers.latestDetail;
+                        timers.latestDetail = undefined;
+                        if (isDispatchGenerationActive(this, generation) && timers.invocation === invocation) {
+                            doDispatch(d);
+                        }
+                    }, remaining);
+                };
+                // Handle async methods
+                if (result instanceof Promise) {
+                    return result.then((resolvedResult) => {
+                        const usesDeferredTiming = (debounceDelay ?? 0) > 0 || (throttleDelay ?? 0) > 0;
+                        if (isDispatchGenerationActive(this, generation)
+                            && (!usesDeferredTiming || timers.invocation === invocation)) {
+                            timedDispatch(resolvedResult);
+                        }
+                        return resolvedResult;
+                    });
+                }
+                // Sync method
+                timedDispatch(result);
+                return result;
+            };
+        };
+    }
+    /**
+     * Clear any pending debounce/throttle dispatch timers on an instance (e.g. on
+     * disconnect, so a queued event doesn't fire into a detached node). A dispatch
+     * is a one-shot signal, so pending ones are dropped, not replayed.
+     */
+    function clearDispatchTimers(instance) {
+        const generation = (instance[DISPATCH_GENERATION] ?? 0) + 1;
+        instance[DISPATCH_GENERATION] = generation;
+        const timers = instance[DISPATCH_TIMERS];
+        if (!timers)
+            return;
+        for (const t of timers.values()) {
+            if (t.debounceTimeout)
+                clearTimeout(t.debounceTimeout);
+            if (t.throttleTimeout)
+                clearTimeout(t.throttleTimeout);
+            t.debounceTimeout = null;
+            t.throttleTimeout = null;
+            t.throttleLastCall = 0;
+            t.latestDetail = undefined;
+            t.invocation = (t.invocation ?? 0) + 1;
+        }
+    }
+
     /**
      * @context decorator for receiving router context updates
      */
@@ -2684,6 +2980,9 @@ var Snice = (function (exports) {
         if (!controllerInstance) {
             return;
         }
+        // Invalidate dispatch work before every teardown path, including an attach
+        // that is still waiting for host readiness and will return early below.
+        clearDispatchTimers(controllerInstance);
         // Claim the controller immediately — before any await — so a second detach
         // that overlaps this one (e.g. disconnect's fire-and-forget detach racing a
         // controller reassignment) finds no instance and returns, instead of running
@@ -2716,6 +3015,8 @@ var Snice = (function (exports) {
         else {
             await controllerInstance.detach(element);
         }
+        // detach() itself may have invoked a decorated dispatch method.
+        clearDispatchTimers(controllerInstance);
         controllerInstance.element = null;
         // Cleanup @observe observers for controller
         cleanupObservers(controllerInstance);
@@ -3075,36 +3376,184 @@ var Snice = (function (exports) {
         return null;
     }
 
-    // Unique marker for dynamic parts
-    // This parses as a comment node but doesn't get escaped in attributes
-    const marker = `snice$${Math.random().toFixed(9).slice(2)}$`;
-    const markerMatch = '?' + marker;
+    const SAFE_TAG = /^[a-z][a-z0-9._-]{0,127}$/;
+    const SAFE_CLASS = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;
+    const AMBIGUOUS_RENDER_HOST_IDENTITY = Symbol('ambiguous-render-host-identity');
+    // Keys are weak; values contain only a sanitized label or the ambiguity
+    // sentinel. The same frozen identity is recorded for the exact constructor
+    // and its exact prototype only after the caller verifies registration.
+    const registeredRenderHosts = new WeakMap();
+    function registerRenderHostIdentity(constructor, tagName) {
+        try {
+            if (typeof constructor !== 'function' || !SAFE_TAG.test(tagName))
+                return;
+            const prototypeDescriptor = Object.getOwnPropertyDescriptor(constructor, 'prototype');
+            const prototype = prototypeDescriptor && 'value' in prototypeDescriptor
+                ? prototypeDescriptor.value
+                : undefined;
+            if ((typeof prototype !== 'object' && typeof prototype !== 'function') || prototype === null)
+                return;
+            const nameDescriptor = Object.getOwnPropertyDescriptor(constructor, 'name');
+            const name = nameDescriptor && 'value' in nameDescriptor && typeof nameDescriptor.value === 'string'
+                ? nameDescriptor.value
+                : '';
+            const className = SAFE_CLASS.test(name) ? name : '';
+            const identity = Object.freeze({
+                label: className ? `<${tagName}> (${className})` : `<${tagName}>`,
+            });
+            const constructorState = registeredRenderHosts.get(constructor);
+            const prototypeState = registeredRenderHosts.get(prototype);
+            const existingStates = [constructorState, prototypeState].filter((state) => state !== undefined);
+            const ambiguous = existingStates.some(state => state === AMBIGUOUS_RENDER_HOST_IDENTITY || state.label !== identity.label);
+            const nextState = ambiguous
+                ? AMBIGUOUS_RENDER_HOST_IDENTITY
+                : existingStates[0] ?? identity;
+            // Update both exact keys in the same synchronous registration call. Once
+            // either key is ambiguous, no later registration can restore attribution.
+            registeredRenderHosts.set(constructor, nextState);
+            registeredRenderHosts.set(prototype, nextState);
+        }
+        catch {
+            // Registration diagnostics are best-effort and must not affect the
+            // successful custom-elements registration that already occurred.
+        }
+    }
+    function registeredIdentity(host) {
+        const prototype = Object.getPrototypeOf(host);
+        if (!prototype)
+            return undefined;
+        const constructorDescriptor = Object.getOwnPropertyDescriptor(prototype, 'constructor');
+        const constructor = constructorDescriptor && 'value' in constructorDescriptor
+            ? constructorDescriptor.value
+            : undefined;
+        if (typeof constructor !== 'function')
+            return undefined;
+        const prototypeIdentity = registeredRenderHosts.get(prototype);
+        const constructorIdentity = registeredRenderHosts.get(constructor);
+        return prototypeIdentity !== AMBIGUOUS_RENDER_HOST_IDENTITY &&
+            prototypeIdentity === constructorIdentity
+            ? prototypeIdentity
+            : undefined;
+    }
+    /** Capture once at the render boundary; failures fall back without masking the render error. */
+    function captureRenderHostIdentity(host) {
+        let label = '<element>';
+        try {
+            const registration = registeredIdentity(host);
+            if (registration)
+                label = registration.label;
+        }
+        catch {
+            // Host/prototype objects can be proxied. Attribution is best-effort
+            // and must never replace the original render or template error.
+        }
+        return Object.freeze({ label, marker: Symbol('render-host-identity') });
+    }
+    class ContextualRenderError extends Error {
+        #identityMarker;
+        constructor(identity, message, cause) {
+            super(message, { cause });
+            this.#identityMarker = identity.marker;
+        }
+        belongsTo(identity) {
+            return this.#identityMarker === identity.marker;
+        }
+    }
+    function contextualizeRenderError(identity, error) {
+        if (error instanceof ContextualRenderError && error.belongsTo(identity))
+            return error;
+        const message = error instanceof Error ? error.message : String(error);
+        const contextual = new ContextualRenderError(identity, `snice: render failed for ${identity.label}: ${message}`, error);
+        if (error instanceof Error)
+            contextual.name = error.name;
+        return contextual;
+    }
+
+    // Unique marker for dynamic template parts. It parses as a comment node but
+    // does not get escaped in attributes.
+    const templateMarker = `snice$${Math.random().toFixed(9).slice(2)}$`;
+    const templateMarkerMatch = '?' + templateMarker;
     // A true comment, not a processing instruction (<?...>): in HTML content both
     // parse to the same comment node, but PIs are dropped inside foreign content
     // (<svg>), which would silently kill any node binding inside an svg block.
-    const nodeMarker = `<!--${markerMatch}-->`;
+    const templateNodeMarker = `<!--${templateMarkerMatch}-->`;
     // Escape the `$` chars — as a bare RegExp they'd be end anchors and the
     // pattern would never match, so marker-bearing text/comments never split.
-    const markerRegex = new RegExp(marker.replace(/\$/g, '\\$'), 'g');
+    const templateMarkerRegex = new RegExp(templateMarker.replace(/\$/g, '\\$'), 'g');
+    function hasTemplateMarker(value) {
+        return value?.includes(templateMarker) ?? false;
+    }
+
     // Template cache - templates with same string array can be reused
     const templateCache = new WeakMap();
     // Sentinel for "not yet set" - distinct from undefined/null
     const NOT_COMMITTED = Symbol('not-committed');
-    function markPreUpgradePropertyBinding(element, propertyName) {
+    const pendingDefinitionRegistries = new WeakMap();
+    function isUpgradedBy(element, constructor) {
+        return Object.prototype.isPrototypeOf.call(constructor.prototype, element);
+    }
+    function flushPreUpgradePropertyBindings(element, registry) {
+        const tagName = element.localName;
+        const constructor = tagName && registry?.get(tagName);
+        if (!constructor || !isUpgradedBy(element, constructor))
+            return;
+        const target = element;
+        const markedBindings = target[PRE_UPGRADE_PROPERTY_BINDINGS];
+        if (!markedBindings?.size)
+            return;
+        for (const propertyName of Array.from(markedBindings)) {
+            // A Snice @property initializer consumes its own marker and expando while
+            // the element upgrades. Anything left belongs to a class that retained
+            // the native/custom property channel, so replay the latest parked value
+            // through that now-upgraded channel.
+            if (Object.prototype.hasOwnProperty.call(target, propertyName)) {
+                const value = target[propertyName];
+                delete target[propertyName];
+                target[propertyName] = value;
+            }
+            markedBindings.delete(propertyName);
+        }
+        delete target[PRE_UPGRADE_PROPERTY_BINDINGS];
+    }
+    function schedulePreUpgradePropertyFlush(element, registry) {
+        if (!registry?.whenDefined || pendingDefinitionRegistries.get(element) === registry)
+            return;
+        pendingDefinitionRegistries.set(element, registry);
+        const reference = new WeakRef(element);
+        void registry.whenDefined(element.localName).then(() => {
+            const target = reference.deref();
+            if (target)
+                flushPreUpgradePropertyBindings(target, registry);
+        });
+    }
+    function markPreUpgradePropertyBinding(element, propertyName, registry) {
         const tagName = element.localName;
         if (!tagName?.includes('-'))
             return false;
-        const registry = element.ownerDocument?.defaultView?.customElements ?? globalThis.customElements;
-        if (registry?.get(tagName))
-            return false;
+        const registeredConstructor = registry?.get(tagName);
+        if (registeredConstructor) {
+            // Template contents can still contain an unupgraded HTMLElement after the
+            // definition has been registered. Registry presence alone therefore does
+            // not prove that the reactive accessor exists on this clone yet.
+            const isUpgraded = isUpgradedBy(element, registeredConstructor);
+            if (isUpgraded)
+                return false;
+            // A registered non-Snice element (or a Snice element that did not
+            // redeclare this member) must retain the native IDL channel. Parking its
+            // role/title/etc. would replace native reflection with an own expando.
+            const reactiveProperties = registeredConstructor[PROPERTIES];
+            if (!reactiveProperties?.has(propertyName))
+                return false;
+        }
         const target = element;
         if (!target[PRE_UPGRADE_PROPERTY_BINDINGS])
             target[PRE_UPGRADE_PROPERTY_BINDINGS] = new Set();
         target[PRE_UPGRADE_PROPERTY_BINDINGS].add(propertyName);
+        schedulePreUpgradePropertyFlush(element, registry);
         return true;
     }
-    function commitPropertyValue(element, propertyName, value) {
-        if (!markPreUpgradePropertyBinding(element, propertyName)) {
+    function commitPropertyValue(element, propertyName, value, registry) {
+        if (!markPreUpgradePropertyBinding(element, propertyName, registry)) {
             element[propertyName] = value;
             return;
         }
@@ -3204,7 +3653,7 @@ var Snice = (function (exports) {
                     if (tagName === 'if') {
                         // <if value="${condition}">children</if>
                         const valueAttr = element.getAttribute('value');
-                        if (valueAttr && valueAttr.includes(marker)) {
+                        if (valueAttr && valueAttr.includes(templateMarker)) {
                             // Remove the value attribute
                             element.removeAttribute('value');
                             this.parts.push({
@@ -3223,7 +3672,7 @@ var Snice = (function (exports) {
                     if (tagName === 'case') {
                         // <case value="${value}">children</case>
                         const valueAttr = element.getAttribute('value');
-                        if (valueAttr && valueAttr.includes(marker)) {
+                        if (valueAttr && valueAttr.includes(templateMarker)) {
                             for (const child of Array.from(element.childNodes)) {
                                 if (child.nodeType === Node.ELEMENT_NODE) {
                                     const branchTag = child.tagName.toLowerCase();
@@ -3232,7 +3681,7 @@ var Snice = (function (exports) {
                                     }
                                 }
                                 else if (child.nodeType === Node.TEXT_NODE && child.textContent?.trim() ||
-                                    child.nodeType === Node.COMMENT_NODE && child.data.includes(marker)) {
+                                    child.nodeType === Node.COMMENT_NODE && child.data.includes(templateMarker)) {
                                     throw new Error('snice: content inside <case> must be nested in a <when> or <default> branch.');
                                 }
                             }
@@ -3252,7 +3701,7 @@ var Snice = (function (exports) {
                     }
                     if (tagName === 'else-if') {
                         const valueAttr = element.getAttribute('value');
-                        if (valueAttr && valueAttr.includes(marker)) {
+                        if (valueAttr && valueAttr.includes(templateMarker)) {
                             element.removeAttribute('value');
                             this.parts.push({
                                 type: 'conditional-else-if',
@@ -3267,7 +3716,7 @@ var Snice = (function (exports) {
                     }
                     if (tagName === 'when') {
                         const valueAttr = element.getAttribute('value');
-                        if (valueAttr && valueAttr.includes(marker)) {
+                        if (valueAttr && valueAttr.includes(templateMarker)) {
                             element.removeAttribute('value');
                             this.parts.push({
                                 type: 'conditional-when',
@@ -3284,12 +3733,12 @@ var Snice = (function (exports) {
                             const attr = attributes[i];
                             const value = attr.value;
                             // Check for attribute bindings
-                            if (value.includes(marker)) {
+                            if (value.includes(templateMarker)) {
                                 attrsToRemove.push(attr);
                                 // Get original attribute name with preserved case
                                 const originalName = attrNamesForParts[partIndex] || attr.name;
                                 // Extract static string segments by splitting on marker
-                                const attrStrings = value.split(marker);
+                                const attrStrings = value.split(templateMarker);
                                 // Number of expressions = number of markers = attrStrings.length - 1
                                 const expressionCount = attrStrings.length - 1;
                                 // Property/boolean/event bindings take a SINGLE expression — they
@@ -3430,7 +3879,7 @@ var Snice = (function (exports) {
                 else if (node.nodeType === Node.COMMENT_NODE) {
                     const comment = node;
                     // Check for marker match (processing instruction becomes comment)
-                    if (comment.data === markerMatch) {
+                    if (comment.data === templateMarkerMatch) {
                         // Node part
                         const parent = comment.parentNode;
                         const endNode = document.createComment('');
@@ -3442,11 +3891,11 @@ var Snice = (function (exports) {
                             endNode
                         });
                     }
-                    else if (comment.data.includes(marker)) {
+                    else if (comment.data.includes(templateMarker)) {
                         // Binding(s) inside an authored HTML comment (<!-- ${x} -->).
                         // Render values into the comment text; critically, consume the
                         // right number of value indices so later parts stay aligned.
-                        const commentStrings = comment.data.split(markerRegex);
+                        const commentStrings = comment.data.split(templateMarkerRegex);
                         this.parts.push({
                             type: 'comment',
                             index: partIndex,
@@ -3459,10 +3908,10 @@ var Snice = (function (exports) {
                 else if (node.nodeType === Node.TEXT_NODE) {
                     const text = node;
                     const data = text.data;
-                    if (data.includes(marker)) {
+                    if (data.includes(templateMarker)) {
                         // Split text node at markers
                         const parent = text.parentNode;
-                        const parts = data.split(markerRegex);
+                        const parts = data.split(templateMarkerRegex);
                         const lastIndex = parts.length - 1;
                         for (let i = 0; i < lastIndex; i++) {
                             parent.insertBefore(document.createTextNode(parts[i]), text);
@@ -3584,13 +4033,13 @@ var Snice = (function (exports) {
                     // the value index stays aligned (a swallowed marker would shift every
                     // binding after the comment).
                     attrNamesForParts.push('');
-                    htmlParts.push(marker);
+                    htmlParts.push(templateMarker);
                 }
                 else if (inAttrValue) {
                     // We're inside a quoted attribute value - this is an attribute binding
                     // For subsequent interpolations in same attribute, keep using same attr name
                     attrNamesForParts.push(currentAttrName);
-                    htmlParts.push(marker);
+                    htmlParts.push(templateMarker);
                 }
                 else if (inTag) {
                     // Inside tag but not in attr value - check for special cases
@@ -3605,7 +4054,7 @@ var Snice = (function (exports) {
                         }
                         currentAttrName = trimmed.substring(attrStart + 1, trimmed.length - 1).trim();
                         attrNamesForParts.push(currentAttrName);
-                        htmlParts.push(marker);
+                        htmlParts.push(templateMarker);
                     }
                     else {
                         // Check if this is a meta element (<if> or <case>)
@@ -3613,7 +4062,7 @@ var Snice = (function (exports) {
                         if (metaElementMatch) {
                             currentAttrName = 'value';
                             attrNamesForParts.push('value');
-                            htmlParts.push(`value="${marker}"`);
+                            htmlParts.push(`value="${templateMarker}"`);
                         }
                         else {
                             const nearbyTemplate = (str.slice(-40) + '${…}' + (strings[i + 1] ?? '').slice(0, 40)).replace(/\s+/g, ' ').trim();
@@ -3626,7 +4075,7 @@ var Snice = (function (exports) {
                 else {
                     // Outside any tag - this is node content
                     attrNamesForParts.push('');
-                    htmlParts.push(nodeMarker);
+                    htmlParts.push(templateNodeMarker);
                 }
             }
         }
@@ -3660,22 +4109,37 @@ var Snice = (function (exports) {
      * Extract the key of a list item rendered from a template with a
      * `key=${...}` binding. Returns undefined for unkeyed items.
      */
-    function getItemKey(item) {
+    function getItemKey(item, renderIdentity) {
         if (!isTemplateResult(item))
             return undefined;
-        const tmpl = prepareTemplate(item);
+        let tmpl;
+        try {
+            tmpl = prepareTemplate(item);
+        }
+        catch (error) {
+            throw renderIdentity ? contextualizeRenderError(renderIdentity, error) : error;
+        }
         return tmpl.keyIndex === -1 ? undefined : item.values[tmpl.keyIndex];
     }
     /**
      * Instance of a rendered template
      */
     class TemplateInstance {
-        constructor(result) {
+        #renderIdentity;
+        #customElementRegistry;
+        constructor(result, renderIdentity = null, customElementRegistry = document.defaultView?.customElements ?? globalThis.customElements ?? null) {
             this.parts = [];
             this.fragment = null;
             this.conditionalParts = []; // if/case parts with their indices
             this.regularParts = []; // all other parts with their indices
-            this.template = prepareTemplate(result);
+            this.#renderIdentity = renderIdentity;
+            this.#customElementRegistry = customElementRegistry;
+            try {
+                this.template = prepareTemplate(result);
+            }
+            catch (error) {
+                throw renderIdentity ? contextualizeRenderError(renderIdentity, error) : error;
+            }
             this.strings = result.strings;
         }
         /**
@@ -3685,6 +4149,10 @@ var Snice = (function (exports) {
         isSameTemplate(strings) {
             return this.strings === strings;
         }
+        /** Internal attribution value; intentionally contains no live renderer host. */
+        getRenderHostIdentity() {
+            return this.#renderIdentity;
+        }
         renderFragment() {
             if (!this.fragment) {
                 // First render - clone template and create parts
@@ -3713,7 +4181,7 @@ var Snice = (function (exports) {
                         case 'node':
                             const startNode = nodeMap.get(partDef.startNode);
                             const endNode = nodeMap.get(partDef.endNode);
-                            part = new NodePart(startNode, endNode);
+                            part = new NodePart(startNode, endNode, this.#renderIdentity, this.#customElementRegistry);
                             break;
                         case 'attribute':
                             const attrElement = nodeMap.get(partDef.element);
@@ -3721,7 +4189,7 @@ var Snice = (function (exports) {
                             break;
                         case 'property':
                             const propElement = nodeMap.get(partDef.element);
-                            part = new PropertyPart(propElement, partDef.name);
+                            part = new PropertyPart(propElement, partDef.name, this.#customElementRegistry);
                             break;
                         case 'boolean-attribute':
                             const boolElement = nodeMap.get(partDef.element);
@@ -3741,7 +4209,7 @@ var Snice = (function (exports) {
                             break;
                         case 'spread':
                             const spreadElement = nodeMap.get(partDef.element);
-                            part = new SpreadPart(spreadElement, partDef.name);
+                            part = new SpreadPart(spreadElement, partDef.name, this.#customElementRegistry);
                             break;
                         case 'controller':
                             const controllerElement = nodeMap.get(partDef.element);
@@ -3920,7 +4388,9 @@ var Snice = (function (exports) {
      * - Reuses child NodeParts when rendering arrays
      */
     class NodePart extends Part {
-        constructor(startNode, endNode) {
+        #renderIdentity;
+        #customElementRegistry;
+        constructor(startNode, endNode, renderIdentity = null, customElementRegistry = null) {
             super();
             this.type = 'node';
             this._committedValue = NOT_COMMITTED;
@@ -3935,6 +4405,11 @@ var Snice = (function (exports) {
             this._committingAsyncValue = false;
             this.startNode = startNode;
             this.endNode = endNode;
+            this.#renderIdentity = renderIdentity;
+            this.#customElementRegistry = customElementRegistry;
+        }
+        _withRenderContext(error) {
+            return this.#renderIdentity ? contextualizeRenderError(this.#renderIdentity, error) : error;
         }
         commit(value) {
             // Handle noChange sentinel
@@ -4043,7 +4518,7 @@ var Snice = (function (exports) {
             // Different template or first render: prepare and validate the replacement
             // while it is detached. If a binding throws, the currently
             // committed range remains intact and its lifecycle stays connected.
-            const instance = new TemplateInstance(result);
+            const instance = new TemplateInstance(result, this.#renderIdentity, this.#customElementRegistry);
             const fragment = instance.renderFragment();
             try {
                 instance.update(result.values);
@@ -4094,7 +4569,9 @@ var Snice = (function (exports) {
          */
         _commitIterable(value, explicitKeys) {
             const items = Array.isArray(value) ? value : Array.from(value);
-            const newKeys = explicitKeys ? Array.from(explicitKeys) : items.map(getItemKey);
+            const newKeys = explicitKeys
+                ? Array.from(explicitKeys)
+                : items.map(item => getItemKey(item, this.#renderIdentity));
             if (newKeys.length !== items.length) {
                 throw new Error('snice: keyed iterable produced a different number of keys and values.');
             }
@@ -4140,7 +4617,7 @@ var Snice = (function (exports) {
                     const endMarker = document.createComment('');
                     this._insertBefore(startMarker);
                     this._insertBefore(endMarker);
-                    itemPart = new NodePart(startMarker, endMarker);
+                    itemPart = new NodePart(startMarker, endMarker, this.#renderIdentity, this.#customElementRegistry);
                     itemParts.push(itemPart);
                 }
                 else {
@@ -4244,7 +4721,7 @@ var Snice = (function (exports) {
                     const endMarker = document.createComment('');
                     parent.insertBefore(startMarker, ref);
                     parent.insertBefore(endMarker, ref);
-                    part = new NodePart(startMarker, endMarker);
+                    part = new NodePart(startMarker, endMarker, this.#renderIdentity, this.#customElementRegistry);
                     newParts[i] = part;
                 }
                 part.commit(items[i]);
@@ -4316,7 +4793,7 @@ var Snice = (function (exports) {
                 catch (error) {
                     this._asyncRunning = false;
                     this._asyncCompleted = true;
-                    console.error('snice: async iterable template value failed:', error);
+                    console.error('snice: async iterable template value failed:', this._withRenderContext(error));
                     return;
                 }
                 void (async () => {
@@ -4329,8 +4806,9 @@ var Snice = (function (exports) {
                         }
                     }
                     catch (error) {
-                        if (version === this._asyncVersion)
-                            console.error('snice: async iterable template value failed:', error);
+                        if (version === this._asyncVersion) {
+                            console.error('snice: async iterable template value failed:', this._withRenderContext(error));
+                        }
                     }
                     finally {
                         if (version === this._asyncVersion) {
@@ -4351,14 +4829,14 @@ var Snice = (function (exports) {
                     this._commitAsyncValue(value);
                 }
                 catch (error) {
-                    console.error('snice: promise template value failed:', error);
+                    console.error('snice: promise template value failed:', this._withRenderContext(error));
                 }
             }, error => {
                 if (version !== this._asyncVersion)
                     return;
                 this._asyncRunning = false;
                 this._asyncCompleted = true;
-                console.error('snice: promise template value failed:', error);
+                console.error('snice: promise template value failed:', this._withRenderContext(error));
             });
         }
         _commitAsyncValue(value) {
@@ -4726,7 +5204,8 @@ var Snice = (function (exports) {
     }
     /** Named spreads: ...props, ...attrs, and ...events. */
     class SpreadPart extends Part {
-        constructor(element, name) {
+        #customElementRegistry;
+        constructor(element, name, customElementRegistry = null) {
             super();
             this.type = 'spread';
             this.committed = {};
@@ -4734,6 +5213,7 @@ var Snice = (function (exports) {
             this.consumedOnce = new Map();
             this.element = element;
             this.name = name;
+            this.#customElementRegistry = customElementRegistry;
         }
         commit(value) {
             if (value === noChange)
@@ -4755,13 +5235,13 @@ var Snice = (function (exports) {
         commitProperties(next) {
             for (const key of Object.keys(this.committed)) {
                 if (!Object.prototype.hasOwnProperty.call(next, key)) {
-                    commitPropertyValue(this.element, key, undefined);
+                    commitPropertyValue(this.element, key, undefined, this.#customElementRegistry);
                 }
             }
             for (const [key, value] of Object.entries(next)) {
                 if (Object.is(this.committed[key], value))
                     continue;
-                commitPropertyValue(this.element, key, value === nothing ? undefined : value);
+                commitPropertyValue(this.element, key, value === nothing ? undefined : value, this.#customElementRegistry);
             }
         }
         commitAttributes(next) {
@@ -4845,6 +5325,9 @@ var Snice = (function (exports) {
                 this.detachListeners();
         }
         reconnected() {
+            if (this.name === 'props' || this.name === 'properties') {
+                flushPreUpgradePropertyBindings(this.element, this.#customElementRegistry);
+            }
             if (this.name === 'events' && this.listeners.size === 0)
                 this.commitEvents(this.committed);
         }
@@ -4859,12 +5342,14 @@ var Snice = (function (exports) {
      * PropertyPart handles property bindings (.property=${value})
      */
     class PropertyPart extends Part {
-        constructor(element, name) {
+        #customElementRegistry;
+        constructor(element, name, customElementRegistry = null) {
             super();
             this.type = 'property';
             this._committedValue = NOT_COMMITTED;
             this.element = element;
             this.name = name;
+            this.#customElementRegistry = customElementRegistry;
         }
         commit(value) {
             if (value === noChange)
@@ -4888,7 +5373,10 @@ var Snice = (function (exports) {
                     return;
             }
             this._committedValue = value;
-            commitPropertyValue(this.element, this.name, value === nothing ? undefined : value);
+            commitPropertyValue(this.element, this.name, value === nothing ? undefined : value, this.#customElementRegistry);
+        }
+        reconnected() {
+            flushPreUpgradePropertyBindings(this.element, this.#customElementRegistry);
         }
         clear() {
             // This part is being destroyed with its owning template. The element is
@@ -5608,16 +6096,6 @@ var Snice = (function (exports) {
      * Production default is false (log and keep the previous DOM).
      */
     let strictRenderErrors = false;
-    function contextualizeRenderError(element, error) {
-        const tag = element.tagName?.toLowerCase() || 'element';
-        const message = error instanceof Error ? error.message : String(error);
-        const contextual = new Error(`snice: render failed for <${tag}>: ${message}`, {
-            cause: error
-        });
-        if (error instanceof Error)
-            contextual.name = error.name;
-        return contextual;
-    }
     function setStrictRenderErrors(value) {
         strictRenderErrors = value;
     }
@@ -5720,6 +6198,8 @@ var Snice = (function (exports) {
      * Perform the actual render of an element
      */
     function performRender(element, options, precomputedResult) {
+        const capturedIdentity = captureRenderHostIdentity(element);
+        let renderIdentity = capturedIdentity;
         const hasPrecomputedResult = arguments.length >= 3;
         const renderMethod = element[RENDER_METHOD];
         if (!renderMethod) {
@@ -5775,12 +6255,16 @@ var Snice = (function (exports) {
             }
             let instance = element[RENDER_INSTANCE];
             if (instance && instance.isSameTemplate(result.strings)) {
+                renderIdentity = instance.getRenderHostIdentity() ?? capturedIdentity;
                 instance.update(result.values);
                 flushRenderCallbacks(element);
                 scheduleAutofocus(element);
                 return;
             }
-            const nextInstance = new TemplateInstance(result);
+            const customElementRegistry = renderRoot instanceof ShadowRoot
+                ? renderRoot.customElementRegistry ?? renderRoot.ownerDocument.defaultView?.customElements ?? null
+                : renderRoot.ownerDocument.defaultView?.customElements ?? null;
+            const nextInstance = new TemplateInstance(result, capturedIdentity, customElementRegistry);
             const nextFragment = nextInstance.renderFragment();
             // Commit while detached first. A malformed binding can then fail without
             // exposing a half-updated tree. Connection-aware parts are paired with
@@ -5840,7 +6324,7 @@ var Snice = (function (exports) {
                 throw cleanupError;
         }
         catch (error) {
-            const contextual = contextualizeRenderError(element, error);
+            const contextual = contextualizeRenderError(renderIdentity, error);
             if (strictRenderErrors)
                 throw contextual;
             console.error('Error rendering element:', contextual);
@@ -6128,134 +6612,6 @@ var Snice = (function (exports) {
         }
     }
 
-    // @dispatch decorator - auto-dispatches custom events from method return values
-    /**
-     * Decorator that automatically dispatches a custom event after a method is called.
-     * The return value of the method becomes the event detail.
-     *
-     * @param eventName The name of the event to dispatch
-     * @param options Optional configuration extending EventInit
-     */
-    function dispatch(eventName, options) {
-        return function (originalMethod, _context) {
-            return function (...args) {
-                // Create timing wrappers for dispatch (per-instance)
-                if (!this[DISPATCH_TIMERS]) {
-                    this[DISPATCH_TIMERS] = new Map();
-                }
-                const timerKey = `${eventName}_${_context.name}`;
-                if (!this[DISPATCH_TIMERS].has(timerKey)) {
-                    this[DISPATCH_TIMERS].set(timerKey, {
-                        debounceTimeout: null,
-                        throttleLastCall: 0,
-                        throttleTimeout: null
-                    });
-                }
-                const timers = this[DISPATCH_TIMERS].get(timerKey);
-                // Call the original method with preserved this context
-                const result = originalMethod.apply(this, args);
-                // Helper to dispatch the event
-                const doDispatch = (detail) => {
-                    // Skip dispatch if result is undefined and dispatchOnUndefined is false
-                    if (detail === undefined && options?.dispatchOnUndefined === false) {
-                        return;
-                    }
-                    // Copy only platform EventInit fields; Snice-only decorator options do
-                    // not belong in the CustomEvent constructor dictionary.
-                    const event = new CustomEvent(eventName, {
-                        bubbles: options?.bubbles ?? true,
-                        cancelable: options?.cancelable ?? false,
-                        composed: options?.composed ?? true,
-                        detail
-                    });
-                    if (options?.scope !== undefined && options?.daemon !== undefined) {
-                        throw new TypeError(`@dispatch('${eventName}') cannot use both scope and daemon.`);
-                    }
-                    if (options?.daemon !== undefined) {
-                        requireDaemonTarget(this, options.daemon).dispatchEvent(event);
-                        return;
-                    }
-                    if (options?.scope !== undefined) {
-                        const target = resolveScope(this, options.scope);
-                        if (!target) {
-                            console.warn(`[snice/@dispatch] scope did not resolve for "${eventName}" — event not dispatched.`);
-                            return;
-                        }
-                        target.dispatchEvent(event);
-                        return;
-                    }
-                    const target = defaultCommunicationTarget(this);
-                    if (!target) {
-                        throw new TypeError(`@dispatch('${eventName}') requires an element, attached controller, or provided @daemon instance.`);
-                    }
-                    target.dispatchEvent(event);
-                };
-                // Helper to handle timed dispatch
-                const timedDispatch = (detail) => {
-                    if (options?.debounce) {
-                        clearTimeout(timers.debounceTimeout);
-                        timers.debounceTimeout = setTimeout(() => doDispatch(detail), options.debounce);
-                        return;
-                    }
-                    if (!options?.throttle) {
-                        doDispatch(detail);
-                        return;
-                    }
-                    const now = Date.now();
-                    const remaining = options.throttle - (now - timers.throttleLastCall);
-                    if (remaining <= 0) {
-                        clearTimeout(timers.throttleTimeout);
-                        timers.throttleLastCall = now;
-                        doDispatch(detail);
-                        return;
-                    }
-                    // Record the LATEST detail so the trailing dispatch carries fresh
-                    // data, not the first-suppressed-call detail captured by closure.
-                    timers.latestDetail = detail;
-                    if (!timers.throttleTimeout) {
-                        timers.throttleTimeout = setTimeout(() => {
-                            timers.throttleLastCall = Date.now();
-                            timers.throttleTimeout = null;
-                            const d = timers.latestDetail;
-                            timers.latestDetail = undefined;
-                            doDispatch(d);
-                        }, remaining);
-                    }
-                };
-                // Handle async methods
-                if (result instanceof Promise) {
-                    return result.then((resolvedResult) => {
-                        timedDispatch(resolvedResult);
-                        return resolvedResult;
-                    });
-                }
-                // Sync method
-                timedDispatch(result);
-                return result;
-            };
-        };
-    }
-    /**
-     * Clear any pending debounce/throttle dispatch timers on an instance (e.g. on
-     * disconnect, so a queued event doesn't fire into a detached node). A dispatch
-     * is a one-shot signal, so pending ones are dropped, not replayed.
-     */
-    function clearDispatchTimers(instance) {
-        const timers = instance[DISPATCH_TIMERS];
-        if (!timers)
-            return;
-        for (const t of timers.values()) {
-            if (t.debounceTimeout)
-                clearTimeout(t.debounceTimeout);
-            if (t.throttleTimeout)
-                clearTimeout(t.throttleTimeout);
-            t.debounceTimeout = null;
-            t.throttleTimeout = null;
-            t.throttleLastCall = 0;
-            t.latestDetail = undefined;
-        }
-    }
-
     /**
      * Method decorators for common patterns
      * @debounce, @throttle, @once, @memoize
@@ -7138,6 +7494,10 @@ var Snice = (function (exports) {
             scheduleAutofocus(this);
         };
         constructor.prototype.disconnectedCallback = async function () {
+            // Invalidate @dispatch work queued or started before disconnect synchronously.
+            // The platform does not await disconnectedCallback, and @dispose may be
+            // async, so waiting until the end permits events from a detached host.
+            clearDispatchTimers(this);
             try {
                 disconnectRenderTree(this);
             }
@@ -7182,7 +7542,6 @@ var Snice = (function (exports) {
             if (clearRenderTimers(this)) {
                 this[PENDING_RECONNECT_RENDER] = true;
             }
-            clearDispatchTimers(this);
             // @moved / @adopted debounce-throttle timers, likewise dropped so they
             // don't fire on a dead element.
             clearLifecycleTimers(this, MOVED_TIMERS);
@@ -7191,6 +7550,11 @@ var Snice = (function (exports) {
         constructor.prototype.attributeChangedCallback = function (name, oldValue, newValue) {
             originalAttributeChangedCallback?.call(this, name, oldValue, newValue);
             if (name === 'controller') {
+                // Parsing a dynamic controller binding briefly creates this marker
+                // attribute on the inert template element. It is renderer metadata,
+                // not a registry name, so it must never start an attachment.
+                if (hasTemplateMarker(newValue))
+                    return;
                 // A class attachment reflects its decorator name for DOM diagnostics,
                 // but the class reference remains the only attachment authority.
                 if (this[CONTROLLER_ATTRIBUTE_SYNC])
@@ -7368,12 +7732,16 @@ var Snice = (function (exports) {
             constructor.prototype[RENDER_OPTIONS] = constructor.renderOptions || {};
         }
         applyElementFunctionality(constructor);
-        if (customElements.get(tagName)) {
+        const existing = customElements.get(tagName);
+        if (existing) {
+            if (existing === constructor)
+                registerRenderHostIdentity(constructor, tagName);
             if (globalThis.SNICE_DEBUG)
                 console.warn(`[snice] "${tagName}" is already registered. Skipping.`);
             return constructor;
         }
         customElements.define(tagName, constructor);
+        registerRenderHostIdentity(constructor, tagName);
         return constructor;
     }
     function element(tagName, options) {
@@ -8782,6 +9150,72 @@ var Snice = (function (exports) {
         }, navigation);
     }
 
+    const EMPTY_QUERY_MARKER = '__snice_empty_query_value__';
+    const QUERY_PARAM_PATTERN = /=:[\w-]+\)?$/;
+    function containsDecodedMarker(url, marker) {
+        if (url.includes(marker))
+            return true;
+        const queryIndex = url.indexOf('?');
+        if (queryIndex === -1)
+            return false;
+        return url.slice(queryIndex + 1).split('&').some(part => {
+            try {
+                return decodeURIComponent(part).includes(marker);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    function emptyQueryMarker(route, url) {
+        let marker = EMPTY_QUERY_MARKER;
+        while (route.spec.includes(marker) || containsDecodedMarker(url, marker)) {
+            marker += '_';
+        }
+        return marker;
+    }
+    function fillEmptyQueryParams(route, url, marker) {
+        const urlQueryIndex = url.indexOf('?');
+        const routeQueryIndex = route.spec.indexOf('?');
+        if (urlQueryIndex === -1 || routeQueryIndex === -1)
+            return null;
+        const urlParts = url.slice(urlQueryIndex + 1).split('&');
+        const routeParts = route.spec.slice(routeQueryIndex + 1).split('&');
+        let changed = false;
+        const normalizedParts = urlParts.map((part, index) => {
+            if (part.endsWith('=') && QUERY_PARAM_PATTERN.test(routeParts[index] ?? '')) {
+                changed = true;
+                return `${part}${marker}`;
+            }
+            return part;
+        });
+        if (!changed)
+            return null;
+        return `${url.slice(0, urlQueryIndex + 1)}${normalizedParts.join('&')}`;
+    }
+    /**
+     * Match through pica-route while preserving legal empty query parameter values.
+     * pica-route 1.1.2 rejects an empty param and therefore discards the whole route.
+     * Keep this compatibility shim in sync with packages/react/src/route-match.ts.
+     */
+    function matchRoute(route, url) {
+        const directMatch = route.match(url);
+        if (directMatch !== false)
+            return directMatch;
+        const marker = emptyQueryMarker(route, url);
+        const normalizedUrl = fillEmptyQueryParams(route, url, marker);
+        if (normalizedUrl === null)
+            return false;
+        const params = route.match(normalizedUrl);
+        if (params === false)
+            return false;
+        for (const name of Object.keys(params)) {
+            if (params[name] === marker)
+                params[name] = '';
+        }
+        return params;
+    }
+
     // Router historically allows a later Router instance to take over the same
     // target. Track only Router-owned provider releases so that handoff remains
     // explicit without weakening duplicate protection for public provideContext().
@@ -8897,8 +9331,13 @@ var Snice = (function (exports) {
                     delete this[CONTEXT_HANDLER];
                 };
                 // Define the custom element (skip if already registered)
-                if (!win.customElements.get(pageOptions.tag)) {
+                const existing = win.customElements.get(pageOptions.tag);
+                if (!existing) {
                     win.customElements.define(pageOptions.tag, constructor);
+                    registerRenderHostIdentity(constructor, pageOptions.tag);
+                }
+                else if (existing === constructor) {
+                    registerRenderHostIdentity(constructor, pageOptions.tag);
                 }
                 // Register the routes with guards, layout, and placard
                 pageOptions.routes.forEach(route => {
@@ -9148,7 +9587,7 @@ var Snice = (function (exports) {
         }
         async function resolveRoute(path, target, stale) {
             for (const route of routes) {
-                const params = route.route.match(path);
+                const params = matchRoute(route.route, path);
                 const isMatch = params !== false;
                 if (!isMatch) {
                     continue;