snice 7.1.0 → 7.1.1

package/dist/index.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.0.3
+ * snice v7.1.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.
@@ -60,9 +60,15 @@ const CONTROLLER_NAME_KEY = getSymbol('controller-name');
 const CONTROLLER_ID = getSymbol('controller-id');
 const CONTROLLER_OPERATIONS = getSymbol('controller-operations');
 const NATIVE_CONTROLLER = getSymbol('native-controller');
+// Decorator name stored on the class so direct class bindings can expose the
+// same useful DOM label without resolving the controller through the registry.
+const CONTROLLER_REGISTRY_NAME = getSymbol('controller-registry-name');
 // Set while a controller CLASS (not a registry name) is attached — the
 // attribute/MutationObserver channel must not attach over or detach it.
 const DIRECT_CONTROLLER = getSymbol('direct-controller');
+// Guards framework-authored diagnostic controller attribute writes from the
+// synchronous custom-element attributeChangedCallback path.
+const CONTROLLER_ATTRIBUTE_SYNC = getSymbol('controller-attribute-sync');
 // A controller class bound by a template before the custom element was
 // defined/upgraded. Picked up by connectedCallback on first initialization.
 const PENDING_CONTROLLER_BINDING = getSymbol('pending-controller-binding');
@@ -2120,6 +2126,12 @@ function controller(name) {
         registry.set(name, constructor);
         // Mark as controller class for channel decorator detection
         constructor.prototype[IS_CONTROLLER_CLASS] = true;
+        // Preserve the registry name on the class. Direct class attachments still
+        // skip registry lookup; this is only their inspectable DOM label.
+        Object.defineProperty(constructor, CONTROLLER_REGISTRY_NAME, {
+            value: name,
+            configurable: true
+        });
         const pending = snice.pendingControllerAttachments.get(name);
         if (pending) {
             snice.pendingControllerAttachments.delete(name);
@@ -2191,6 +2203,52 @@ function controllerLabel(controller) {
         ? controller
         : (controller?.name || '(anonymous controller class)');
 }
+/** Registry/decorator name used for a direct class attachment's DOM marker. */
+function directControllerAttributeName(controllerClass) {
+    const registeredName = Object.prototype.hasOwnProperty.call(controllerClass, CONTROLLER_REGISTRY_NAME)
+        ? controllerClass[CONTROLLER_REGISTRY_NAME]
+        : undefined;
+    return typeof registeredName === 'string'
+        ? registeredName
+        : controllerLabel(controllerClass);
+}
+/**
+ * Write the inspectable controller marker without feeding it back into the
+ * custom-element attribute channel. Native MutationObservers are asynchronous
+ * and are excluded independently by DIRECT_CONTROLLER.
+ */
+function writeControllerAttribute(element, value) {
+    if (value === null) {
+        if (!element.hasAttribute('controller'))
+            return;
+    }
+    else if (element.getAttribute('controller') === value) {
+        return;
+    }
+    element[CONTROLLER_ATTRIBUTE_SYNC] = true;
+    try {
+        if (value === null)
+            element.removeAttribute('controller');
+        else
+            element.setAttribute('controller', value);
+    }
+    finally {
+        delete element[CONTROLLER_ATTRIBUTE_SYNC];
+    }
+}
+/**
+ * Restore the diagnostic attribute for an attached class controller. Returns
+ * true when the direct class channel owns the element.
+ */
+function restoreDirectControllerAttribute(element) {
+    if (!element[DIRECT_CONTROLLER])
+        return false;
+    const source = element[CONTROLLER_NAME_KEY];
+    if (typeof source !== 'function')
+        return false;
+    writeControllerAttribute(element, directControllerAttributeName(source));
+    return true;
+}
 /**
  * Attaches a controller to an element
  * @param element The element to attach the controller to
@@ -2220,11 +2278,26 @@ async function attachController(element, controller) {
     }
     if (existingSource === controller && existingController) {
         // Already attached and controller exists (name or class reference match)
+        if (typeof controller !== 'string') {
+            restoreDirectControllerAttribute(element);
+        }
         return;
     }
     // If there's an existing controller, detach it first
     if (existingController) {
         await detachController(element);
+        // Light-DOM reconciliation can issue commit() and reconnected() requests
+        // for the same class while the previous controller is still detaching.
+        // If the other request already installed that exact source, this request
+        // is redundant. Different sources retain the established rapid-switch
+        // behavior and continue through the normal replacement path.
+        const replacement = element[CONTROLLER_KEY];
+        const replacementSource = element[CONTROLLER_NAME_KEY];
+        if (replacement && replacementSource === controller) {
+            if (typeof controller !== 'string')
+                restoreDirectControllerAttribute(element);
+            return;
+        }
     }
     let ControllerClass;
     if (typeof controller === 'string') {
@@ -2240,13 +2313,16 @@ async function attachController(element, controller) {
     }
     else {
         ControllerClass = controller;
-        // The class channel owns the element from here on: the attribute /
-        // MutationObserver channel goes inert and its bookkeeping is dropped.
-        element[DIRECT_CONTROLLER] = true;
-        delete element[NATIVE_CONTROLLER];
     }
     // Create controller instance with unique ID and scope
     const controllerInstance = new ControllerClass();
+    if (typeof controller !== 'string') {
+        // Construction succeeded, so the class channel can safely take ownership.
+        // Setting this before construction would leave a stale observer guard when
+        // a controller constructor throws.
+        element[DIRECT_CONTROLLER] = true;
+        delete element[NATIVE_CONTROLLER];
+    }
     snice.controllerIdCounter += 1;
     const controllerId = snice.controllerIdCounter;
     const scope = new ControllerScope();
@@ -2265,6 +2341,12 @@ async function attachController(element, controller) {
     element[CONTROLLER_KEY] = controllerInstance;
     element[CONTROLLER_NAME_KEY] = controller;
     element[CONTROLLER_OPERATIONS] = scope;
+    if (typeof controller !== 'string') {
+        // The class reference remains the sole attachment authority. This
+        // attribute is diagnostic only; custom-element callbacks and native
+        // MutationObservers are guarded from treating it as a string attachment.
+        restoreDirectControllerAttribute(element);
+    }
     // Wait for element to be ready. Race against abort (detachController) and
     // a 30s deadline so a caller that forgets to append the element gets a
     // clear error instead of an unresolvable promise.
@@ -2296,6 +2378,9 @@ async function attachController(element, controller) {
         // attached — otherwise a later attach short-circuits as "already attached"
         // and a detach would run detach() on it.
         if (element[CONTROLLER_KEY] === controllerInstance) {
+            if (typeof controller !== 'string') {
+                writeControllerAttribute(element, null);
+            }
             delete element[CONTROLLER_KEY];
             delete element[CONTROLLER_NAME_KEY];
             delete element[CONTROLLER_OPERATIONS];
@@ -2347,6 +2432,12 @@ async function detachController(element) {
     // controller reassignment) finds no instance and returns, instead of running
     // detach() a second time on the same controller. The rest of this function
     // works off the locals captured above.
+    if (typeof controllerSource === 'function') {
+        // Remove the class channel's diagnostic marker while its guards are still
+        // active. A queued native MutationObserver therefore sees no attribute and
+        // cannot resurrect a registry attachment after detach.
+        writeControllerAttribute(element, null);
+    }
     delete element[CONTROLLER_KEY];
     delete element[CONTROLLER_NAME_KEY];
     delete element[CONTROLLER_OPERATIONS];
@@ -2421,8 +2512,12 @@ function useNativeElementControllers() {
         // attachController(el, Class)). The class channel owns the element:
         // attribute writes must not attach over it, and insertion sweeps must
         // not detach it.
-        if (element[DIRECT_CONTROLLER])
+        if (element[DIRECT_CONTROLLER]) {
+            // External writes cannot replace a class binding. Keep the DOM marker
+            // honest about the class that is actually attached.
+            restoreDirectControllerAttribute(element);
             return;
+        }
         const controllerName = element.getAttribute('controller');
         const currentControllerName = element[NATIVE_CONTROLLER];
         // No change
@@ -4660,8 +4755,8 @@ class PropertyPart extends Part {
  * Accepts a controller class decorated with @controller (attached directly,
  * no registry lookup) or a registry name string (delegated to the attribute
  * channel with the exact semantics of a static controller="name"). While a
- * class is bound it owns the element: the attribute/MutationObserver channel
- * is inert until the class is unbound.
+ * class is bound it owns the element: the decorator name is reflected for
+ * inspection, while the attribute/MutationObserver attach channel stays inert.
  *
  * Renders commit while the tree is detached and connect afterwards, so
  * attachment happens on reconnected()/connected commits; every hook is
@@ -4700,10 +4795,6 @@ class ControllerPart extends Part {
             }
         }
         if (typeof next === 'function') {
-            // Class binding takes over — drop any attribute so the string channel
-            // cannot fight it.
-            if (this.element.hasAttribute('controller'))
-                this.element.removeAttribute('controller');
             if (this.isConnected) {
                 this._apply(next);
             }
@@ -6775,6 +6866,14 @@ function applyElementFunctionality(constructor) {
     constructor.prototype.attributeChangedCallback = function (name, oldValue, newValue) {
         originalAttributeChangedCallback?.call(this, name, oldValue, newValue);
         if (name === 'controller') {
+            // A class attachment reflects its decorator name for DOM diagnostics,
+            // but the class reference remains the only attachment authority.
+            if (this[CONTROLLER_ATTRIBUTE_SYNC])
+                return;
+            if (this[DIRECT_CONTROLLER]) {
+                restoreDirectControllerAttribute(this);
+                return;
+            }
             this.controller = newValue;
             return;
         }