snice 7.5.0 → 7.7.0

package/dist/index.cjs

@@ -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.
@@ -716,6 +716,18 @@ function createThrottled(fn, delay) {
         }
     };
 }
+/** 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.
  *
@@ -1849,6 +1861,11 @@ function on(eventName, selectorOrOptions, options) {
     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 () {
@@ -1860,7 +1877,7 @@ function on(eventName, selectorOrOptions, options) {
             // 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();
             }
@@ -1940,6 +1957,10 @@ function setupEventHandlers(instance, targetElement) {
         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
@@ -1960,13 +1981,13 @@ function setupEventHandlers(instance, targetElement) {
         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
@@ -1974,15 +1995,21 @@ function setupEventHandlers(instance, targetElement) {
         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
@@ -2000,6 +2027,20 @@ function setupEventHandlers(instance, targetElement) {
             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 {
@@ -2021,56 +2062,125 @@ function setupEventHandlers(instance, targetElement) {
         }
         // 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
@@ -2078,6 +2188,20 @@ function setupEventHandlers(instance, targetElement) {
             // 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;
@@ -2086,46 +2210,39 @@ function setupEventHandlers(instance, targetElement) {
                     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);
         }
     }
 }
@@ -2145,6 +2262,185 @@ function cleanupEventHandlers(instance) {
     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
  */
@@ -2683,6 +2979,9 @@ async function detachController(element) {
     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
@@ -2715,6 +3014,8 @@ async function detachController(element) {
     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);
@@ -3074,36 +3375,184 @@ function findRenderHost(node) {
     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;
     }
@@ -3203,7 +3652,7 @@ class Template {
                 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({
@@ -3222,7 +3671,7 @@ class Template {
                 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();
@@ -3231,7 +3680,7 @@ class Template {
                                 }
                             }
                             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.');
                             }
                         }
@@ -3251,7 +3700,7 @@ class Template {
                 }
                 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',
@@ -3266,7 +3715,7 @@ class Template {
                 }
                 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',
@@ -3283,12 +3732,12 @@ class Template {
                         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
@@ -3429,7 +3878,7 @@ class Template {
             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('');
@@ -3441,11 +3890,11 @@ class Template {
                         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,
@@ -3458,10 +3907,10 @@ class Template {
             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);
@@ -3583,13 +4032,13 @@ function prepareTemplate(result) {
                 // 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
@@ -3604,7 +4053,7 @@ function prepareTemplate(result) {
                     }
                     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>)
@@ -3612,7 +4061,7 @@ function prepareTemplate(result) {
                     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();
@@ -3625,7 +4074,7 @@ function prepareTemplate(result) {
             else {
                 // Outside any tag - this is node content
                 attrNamesForParts.push('');
-                htmlParts.push(nodeMarker);
+                htmlParts.push(templateNodeMarker);
             }
         }
     }
@@ -3659,22 +4108,37 @@ function prepareTemplate(result) {
  * 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;
     }
     /**
@@ -3684,6 +4148,10 @@ class TemplateInstance {
     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
@@ -3712,7 +4180,7 @@ class TemplateInstance {
                     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);
@@ -3720,7 +4188,7 @@ class TemplateInstance {
                         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);
@@ -3740,7 +4208,7 @@ class TemplateInstance {
                         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);
@@ -3919,7 +4387,9 @@ class Part {
  * - 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;
@@ -3934,6 +4404,11 @@ class NodePart extends Part {
         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
@@ -4042,7 +4517,7 @@ class NodePart extends Part {
         // 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);
@@ -4093,7 +4568,9 @@ class NodePart extends Part {
      */
     _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.');
         }
@@ -4139,7 +4616,7 @@ class NodePart extends Part {
                 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 {
@@ -4243,7 +4720,7 @@ class NodePart extends Part {
                 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]);
@@ -4315,7 +4792,7 @@ class NodePart extends Part {
             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 () => {
@@ -4328,8 +4805,9 @@ class NodePart extends Part {
                     }
                 }
                 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) {
@@ -4350,14 +4828,14 @@ class NodePart extends Part {
                 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) {
@@ -4725,7 +5203,8 @@ function validateSpreadEvents(next, label) {
 }
 /** 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 = {};
@@ -4733,6 +5212,7 @@ class SpreadPart extends Part {
         this.consumedOnce = new Map();
         this.element = element;
         this.name = name;
+        this.#customElementRegistry = customElementRegistry;
     }
     commit(value) {
         if (value === noChange)
@@ -4754,13 +5234,13 @@ class SpreadPart extends Part {
     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) {
@@ -4844,6 +5324,9 @@ class SpreadPart extends Part {
             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);
     }
@@ -4858,12 +5341,14 @@ class SpreadPart extends Part {
  * 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)
@@ -4887,7 +5372,10 @@ class PropertyPart extends Part {
                 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
@@ -5607,16 +6095,6 @@ function resetHostAutofocus(host) {
  * 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;
 }
@@ -5719,6 +6197,8 @@ const MAX_RENDER_DEPTH = 50;
  * 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) {
@@ -5774,12 +6254,16 @@ function performRender(element, options, precomputedResult) {
         }
         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
@@ -5839,7 +6323,7 @@ function performRender(element, options, precomputedResult) {
             throw cleanupError;
     }
     catch (error) {
-        const contextual = contextualizeRenderError(element, error);
+        const contextual = contextualizeRenderError(renderIdentity, error);
         if (strictRenderErrors)
             throw contextual;
         console.error('Error rendering element:', contextual);
@@ -6127,134 +6611,6 @@ function applyStyles(element) {
     }
 }
 
-// @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
@@ -7137,6 +7493,10 @@ function applyElementFunctionality(constructor) {
         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);
         }
@@ -7181,7 +7541,6 @@ function applyElementFunctionality(constructor) {
         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);
@@ -7190,6 +7549,11 @@ function applyElementFunctionality(constructor) {
     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])
@@ -7367,12 +7731,16 @@ function defineElement(tagName, constructor, context, options) {
         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) {
@@ -8781,6 +9149,72 @@ function provideRouterContext(root, navigation) {
     }, 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().
@@ -8896,8 +9330,13 @@ function Router(options) {
                 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 => {
@@ -9147,7 +9586,7 @@ function Router(options) {
     }
     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;