snice 7.7.0 → 7.8.0

package/dist/index.esm.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.
@@ -1557,17 +1557,33 @@ function respond(requestName, options) {
         });
     };
 }
-// 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
@@ -1651,7 +1667,10 @@ function setupResponseHandlers(instance, element) {
             // 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);
             })
@@ -1666,10 +1685,17 @@ function setupResponseHandlers(instance, element) {
                 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);
@@ -1678,6 +1704,7 @@ function setupResponseHandlers(instance, element) {
 }
 // Helper to cleanup response handlers
 function cleanupResponseHandlers(instance) {
+    registeredHandlers.delete(instance);
     if (instance[CLEANUP]?.channels) {
         for (const cleanup of instance[CLEANUP].channels) {
             cleanup();
@@ -1803,6 +1830,8 @@ function matchesKeyboardFilter(event, filter) {
  * 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
  *
@@ -1864,18 +1893,42 @@ function on(eventName, selectorOrOptions, options) {
     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();
             }
@@ -2890,6 +2943,35 @@ async function attachController(element, controller) {
         // 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.
@@ -2902,6 +2984,11 @@ async function attachController(element, controller) {
         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
@@ -2920,8 +3007,10 @@ async function attachController(element, controller) {
         }
         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);
@@ -2943,20 +3032,30 @@ async function attachController(element, controller) {
     }
     // 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 }
     }));