snice 7.7.0 → 7.8.0

package/dist/index.iife.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.6.0
+ * snice v7.7.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.
@@ -1560,17 +1560,33 @@ var Snice = (function (exports) {
             });
         };
     }
-    // Helper to setup response handlers for elements and controllers
-    function setupResponseHandlers(instance, element) {
+    // Which handler descriptors an instance has already registered, so a second
+    // setup pass only picks up what the first one deferred.
+    const registeredHandlers = new WeakMap();
+    /**
+     * Helper to setup response handlers for elements and controllers.
+     *
+     * Safe to call more than once for the same instance: a handler already
+     * registered is skipped rather than double-bound.
+     */
+    function setupResponseHandlers(instance, element, options) {
         const handlers = instance.constructor[CHANNEL_HANDLERS];
         if (!handlers)
             return;
+        const claim = options?.claim;
+        let registered = registeredHandlers.get(instance);
+        if (!registered) {
+            registered = new Set();
+            registeredHandlers.set(instance, registered);
+        }
         // Store cleanup functions
         // Initialize cleanup object if needed
         if (!instance[CLEANUP]) {
             instance[CLEANUP] = { events: [], channels: [] };
         }
         for (const handler of handlers) {
+            if (registered.has(handler))
+                continue;
             const boundMethod = handler.method.bind(instance);
             const eventName = `@request/${handler.channelName}`;
             // Create timing variables for debounce/throttle per handler
@@ -1654,7 +1670,10 @@ var Snice = (function (exports) {
                 // Clear the discovery timeout immediately - we found a handler
                 discovery.resolve();
                 // Call the timed responder method and handle the result
-                Promise.resolve(timedMethod(payload))
+                const answer = claim
+                    ? Promise.resolve(claim()).then(() => timedMethod(payload))
+                    : Promise.resolve(timedMethod(payload));
+                answer
                     .then(result => {
                     data.resolve(result);
                 })
@@ -1669,10 +1688,17 @@ var Snice = (function (exports) {
                     responseTarget = requireDaemonTarget(instance, handler.options.daemon);
                 }
                 catch (error) {
+                    // The app context reaches a controller through its host element, so it
+                    // can be unreachable while the host is still disconnected. Leave the
+                    // handler for the later pass instead of dropping it permanently.
+                    if (options?.deferUnresolvableDaemons)
+                        continue;
                     console.warn(`[snice/@respond] ${error.message} Responder "${handler.channelName}" skipped.`);
+                    registered.add(handler);
                     continue;
                 }
             }
+            registered.add(handler);
             responseTarget.addEventListener(eventName, responseHandler);
             instance[CLEANUP].channels.push(() => {
                 responseTarget.removeEventListener(eventName, responseHandler);
@@ -1681,6 +1707,7 @@ var Snice = (function (exports) {
     }
     // Helper to cleanup response handlers
     function cleanupResponseHandlers(instance) {
+        registeredHandlers.delete(instance);
         if (instance[CLEANUP]?.channels) {
             for (const cleanup of instance[CLEANUP].channels) {
                 cleanup();
@@ -1806,6 +1833,8 @@ var Snice = (function (exports) {
      * Use in elements or controllers to listen to DOM events or custom events
      */
     const ON_HANDLERS = getSymbol('on-handlers');
+    // Per-decoration-site counter — see the registration identity note in `on()`.
+    let registrationCount = 0;
     /**
      * @on decorator for listening to events
      *
@@ -1867,18 +1896,42 @@ var Snice = (function (exports) {
         if (!selector && opts.target) {
             selector = opts.target;
         }
+        const eventNames = Array.isArray(eventName) ? eventName : [eventName];
+        // Registration identity — derived from EVERY decorator argument, so no
+        // option can be forgotten here and silently collapse two distinct stacked
+        // @on decorators into one (that is how { debounce: 300 } stacked on a plain
+        // @on for the same event used to lose one of its two registrations).
+        // Options are serialized generically (sorted, so literal key order doesn't
+        // matter); values that can't be compared by value — an EventTarget or a
+        // resolver function passed as `scope` — fall back to this decoration site's
+        // own id, which is stable across instances but unique per @on application.
+        const siteId = `site:${++registrationCount}`;
+        let optionSignature = '';
+        let hasOpaqueOption = false;
+        for (const key of Object.keys(opts).sort()) {
+            const value = opts[key];
+            if (value === undefined)
+                continue;
+            if (value !== null && (typeof value === 'object' || typeof value === 'function')) {
+                hasOpaqueOption = true;
+                continue;
+            }
+            optionSignature += `${key}=${String(value)};`;
+        }
+        const argumentKey = `${eventNames.join(',')}::${selector ?? ''}::${optionSignature}${hasOpaqueOption ? `::${siteId}` : ''}`;
         return function (originalMethod, context) {
             const methodName = context.name;
+            // Same decoration, same method name → same registration. A subclass that
+            // re-declares an identically decorated method must NOT add a second
+            // listener on top of the one its parent's initializer already registered.
+            const registrationKey = `${methodName}::${argumentKey}`;
             context.addInitializer(function () {
                 const constructor = this.constructor;
-                // Dedup by registration identity (method + events + selector), NOT by
-                // method reference alone — stacked @on decorators share one method and
-                // must each register. Use hasOwnProperty so subclasses get their OWN
-                // Set instead of inheriting — otherwise parent and child share state
-                // 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 ?? ''}::light:${opts.light ?? ''}::shadow:${opts.shadow ?? ''}`;
+                // Dedup by registration identity, NOT by method reference — stacked @on
+                // decorators share one method and must each register. Use hasOwnProperty
+                // so subclasses get their OWN Set instead of inheriting — otherwise
+                // parent and child share state and child registrations pollute parent
+                // (and vice versa) via the prototype chain.
                 if (!Object.prototype.hasOwnProperty.call(constructor, ON_METHODS)) {
                     constructor[ON_METHODS] = new Set();
                 }
@@ -2893,6 +2946,35 @@ var Snice = (function (exports) {
             // MutationObservers are guarded from treating it as a string attachment.
             restoreDirectControllerAttribute(element);
         }
+        // @respond handlers are installed before the readiness gate below, exactly
+        // as elements install theirs in connectedCallback. A child's mount-time
+        // @request can be the very thing keeping the host from becoming ready, so
+        // the responder has to be reachable while `ready` is still pending. Such a
+        // request also releases the gate — it proves the host subtree is live and
+        // that something is blocked on this attachment — and is answered once
+        // attach() and the remaining setup have run.
+        //
+        // A `@respond({ daemon })` handler resolves its target through the host's app
+        // context, which is unreachable while the host is still disconnected (attach
+        // before appendChild). Those are deferred here and registered by the second
+        // pass past the gate, where they behaved correctly before this ordering.
+        let requestClaimed = false;
+        let releaseReadyGate;
+        let completeAttach;
+        let failAttach;
+        const attached = new Promise((resolve, reject) => {
+            completeAttach = resolve;
+            failAttach = reject;
+        });
+        attached.catch(() => { }); // No requester when nothing was claimed
+        setupResponseHandlers(controllerInstance, element, {
+            deferUnresolvableDaemons: true,
+            claim: () => {
+                requestClaimed = true;
+                releaseReadyGate?.();
+                return attached;
+            },
+        });
         // Normally a controller waits for its host's full initialization. The sole
         // exception is attachController(host, ...) from that host's own @ready
         // handler: awaiting ready there would wait on the current handler itself.
@@ -2905,6 +2987,11 @@ var Snice = (function (exports) {
             try {
                 await Promise.race([
                     element.ready,
+                    new Promise(resolve => {
+                        if (requestClaimed)
+                            return resolve();
+                        releaseReadyGate = resolve;
+                    }),
                     new Promise((_, reject) => {
                         const onAbort = () => {
                             // Tagged so fire-and-forget call sites can tell this designed
@@ -2923,8 +3010,10 @@ var Snice = (function (exports) {
             }
             catch (error) {
                 // Attach never got past `ready` (aborted or deadline). Roll back the
-                // stored references so a later attach does not short-circuit against an
-                // instance whose attach() never ran.
+                // stored references and the early responders so a later attach does not
+                // short-circuit against an instance whose attach() never ran.
+                cleanupResponseHandlers(controllerInstance);
+                failAttach(error);
                 if (element[CONTROLLER_KEY] === controllerInstance) {
                     if (typeof controller !== 'string') {
                         writeControllerAttribute(element, null);
@@ -2946,20 +3035,30 @@ var Snice = (function (exports) {
         }
         // Past `ready` — mark the controller so detach knows attach was actually run.
         controllerInstance[CONTROLLER_ATTACHED] = true;
-        // Run attach in the controller's scope
-        await scope.runOperation(async () => {
-            await controllerInstance.attach(element);
-        });
-        // @context has the same managed lifecycle on controllers as @on,
-        // @observe and @respond. Catch up controllers whose async attach completed
-        // after the Router announced the current navigation.
-        await setupContextHandler(controllerInstance, 'microtask');
-        // Setup @observe observers for controller
-        setupObservers(controllerInstance, element);
-        // Setup @channel handlers for controller
-        setupResponseHandlers(controllerInstance, element);
-        // Setup @on event handlers for controller
-        setupEventHandlers(controllerInstance, element);
+        try {
+            // Run attach in the controller's scope
+            await scope.runOperation(async () => {
+                await controllerInstance.attach(element);
+            });
+            // @context has the same managed lifecycle on controllers as @on,
+            // @observe and @respond. Catch up controllers whose async attach completed
+            // after the Router announced the current navigation.
+            await setupContextHandler(controllerInstance, 'microtask');
+            // Setup @observe observers for controller
+            setupObservers(controllerInstance, element);
+            // Second @respond pass: registers only what the pre-gate pass deferred —
+            // daemon-scoped responders whose app context was not resolvable yet.
+            setupResponseHandlers(controllerInstance, element);
+            // Setup @on event handlers for controller
+            setupEventHandlers(controllerInstance, element);
+        }
+        catch (error) {
+            // A claimed request must not wait on an attachment that never completed.
+            failAttach(error);
+            throw error;
+        }
+        // Answer whatever was claimed while the host was still becoming ready.
+        completeAttach();
         element.dispatchEvent(new CustomEvent('controller-attached', {
             detail: { name: controllerName, controller: controllerInstance }
         }));