@webjsdev/core 0.7.64 → 0.8.0

package/src/component/lifecycle.js

@@ -1,5 +1,5 @@
 import { render as clientRender } from '../render-client.js';
-import { readAttributeValue, resolveAttributeProperty, observedAttributeNames } from '../attribute-reader.js';
+import { readAttributeValue, resolveAttributeProperty, observedAttributeNames, isAttributeBacked } from '../attribute-reader.js';
 import { setActiveActionSignal, activeActionSignal } from '../action-abort-client.js';
 import { carriesFunction } from '../form-action.js';
 import { isCSS, adoptStyles } from '../css.js';
@@ -84,7 +84,7 @@ const isBrowser = typeof window !== 'undefined' && typeof HTMLElement !== 'undef
  * @property {(newValue: unknown, oldValue: unknown) => boolean} [hasChanged]
  *   Custom dirty-check function. Called by the generated setter before
  *   scheduling an update. Return `true` to trigger a re-render, `false`
- *   to skip. Default: strict inequality `(a, b) => a !== b`.
+ *   to skip. Default: `(a, b) => !Object.is(a, b)`.
  *
  *   Note: this fires on the FIRST assignment too, with `oldValue` set
  *   to `undefined`. Numeric comparators that subtract against undefined
@@ -115,6 +115,61 @@ const FACTORY_PROPS = Symbol('webjs.factoryProps');
 // Per-class memo so the constructor-time enforcement walk runs once per class.
 const _propsChecked = new WeakSet();
 
+/** A settled `updateComplete` shared by every instance until its first update. */
+const RESOLVED_TRUE = Promise.resolve(true);
+/** Iterated in place of a controller set no instance has created. */
+const NO_CONTROLLERS = new Set();
+
+/**
+ * Per class, the declared reactive properties with their accessors installed
+ * on the prototype.
+ * @type {WeakMap<Function, { propName: string, decl: any }[]>}
+ */
+const _accessorPlans = new WeakMap();
+
+/**
+ * Define the getter/setter pair for every declared property on the class's
+ * prototype, once, and record the plan the constructor applies per instance
+ * (own-value capture and `default`). The setter coerces nothing itself (the
+ * attribute readers do), runs `hasChanged`, reflects, and schedules an update.
+ * @param {any} Ctor
+ * @param {Record<string, unknown>} props
+ */
+function installAccessors(Ctor, props) {
+  /** @type {{ propName: string, decl: any }[]} */
+  const plan = [];
+  for (const [propName, decl] of Object.entries(props)) {
+    const d = typeof decl === 'object' && decl !== null ? decl : { type: decl };
+    plan.push({ propName, decl: d });
+    const changedCheck = d.hasChanged || defaultHasChanged;
+    Object.defineProperty(Ctor.prototype, propName, {
+      configurable: true,
+      enumerable: true,
+      get() { return this.__propValues[propName]; },
+      set(newVal) {
+        const oldVal = this.__propValues[propName];
+        this.__propValues[propName] = newVal;
+        if (!changedCheck(newVal, oldVal)) return;
+        // Reflect to attribute if requested (_reflectAttribute skips a prop
+        // with no attribute: `state: true` or `attribute: false`).
+        if (d.reflect) {
+          if (this._connected) {
+            this._reflectAttribute(propName, newVal, d);
+          } else {
+            (this.__reflectPending ??= new Set()).add(propName);
+          }
+        }
+        // requestUpdate records the (name, oldValue) entry AND schedules a
+        // render. During the update phase the scheduler short-circuits and
+        // the entry folds into the current cycle's changedProperties.
+        this.requestUpdate(propName, oldVal);
+      },
+    });
+  }
+  _accessorPlans.set(Ctor, plan);
+  return plan;
+}
+
 class WebComponentBase extends Base {
   /** Whether to use shadow DOM. Default: false (light DOM). @type {boolean} */
   static shadow = false;
@@ -146,8 +201,9 @@ class WebComponentBase extends Base {
    * that trigger re-renders on change, coerce attribute values by type,
    * and optionally reflect back to attributes.
    *
-   * Properties with `state: true` are excluded from `observedAttributes`
-   * and never reflect: they behave like private reactive state.
+   * Properties with `state: true` (internal state) or `attribute: false` (a
+   * property-only input) are excluded from `observedAttributes` and never
+   * reflect.
    *
    * @type {Record<string, PropertyDeclaration>}
    */
@@ -178,8 +234,8 @@ class WebComponentBase extends Base {
 
   /**
    * Returns the list of attribute names the browser should observe.
-   * Properties with `state: true` are excluded: they are internal-only
-   * and do not correspond to any HTML attribute.
+   * Properties with `state: true` or `attribute: false` are excluded: they
+   * do not correspond to any HTML attribute.
    *
    * @returns {string[]}
    */
@@ -199,10 +255,12 @@ class WebComponentBase extends Base {
     this._connected = false;
 
     /**
-     * Set of attached reactive controllers.
-     * @type {Set<ReactiveController>}
+     * Set of attached reactive controllers, created by the first
+     * `addController` (#1646: most instances never attach one, and the SSR
+     * walk constructs an instance per rendered element).
+     * @type {Set<ReactiveController> | null}
      */
-    this.__controllers = new Set();
+    this.__controllers = null;
 
     /**
      * Whether the component has completed its first render.
@@ -235,7 +293,7 @@ class WebComponentBase extends Base {
      * @type {Promise<boolean>}
      * @private
      */
-    this._updatePromise = Promise.resolve(true);
+    this._updatePromise = RESOLVED_TRUE;
 
     /**
      * Set while the component is inside the update phase (between
@@ -288,13 +346,14 @@ class WebComponentBase extends Base {
   }
 
   /**
-   * For every key in `static properties`, create a getter/setter pair on
-   * the instance that coerces values, runs `hasChanged`, schedules updates,
-   * and optionally reflects to the HTML attribute.
+   * Give the instance its reactive-property backing store and make sure the
+   * class's getter/setter pairs (which run `hasChanged`, schedule updates and
+   * optionally reflect to the HTML attribute) are installed on its PROTOTYPE,
+   * once per class. Per instance this only lifts a value written before the
+   * element upgraded and applies the declared `default`s.
    *
-   * This is called once from the constructor. The backing store is a plain
-   * object (`this.__propValues`) so accessors don't collide with the
-   * prototype.
+   * Called once from the constructor. The backing store is a plain object
+   * (`this.__propValues`), so the accessors never collide with it.
    * @private
    */
   _initializeProperties() {
@@ -305,35 +364,24 @@ class WebComponentBase extends Base {
     /** @type {Record<string, unknown>} */
     this.__propValues = {};
 
-    for (const [propName, decl] of Object.entries(props)) {
-      const d = typeof decl === 'object' ? decl : { type: decl };
-      // Capture any value set before the accessor was installed (e.g. via
-      // attribute or property assignment before `super()` returns).
-      const initial = /** @type {any} */ (this)[propName];
-
-      Object.defineProperty(this, propName, {
-        configurable: true,
-        enumerable: true,
-        get: () => this.__propValues[propName],
-        set: (newVal) => {
-          const oldVal = this.__propValues[propName];
-          const changed = (d.hasChanged || defaultHasChanged)(newVal, oldVal);
-          if (!changed) return;
-          this.__propValues[propName] = newVal;
-
-          // Reflect to attribute if requested (and not internal state).
-          if (d.reflect && !d.state && this._connected) {
-            this._reflectAttribute(propName, newVal, d);
-          }
-
-          // requestUpdate records the (name, oldValue) entry AND schedules
-          // a render. When called during the update phase (willUpdate /
-          // hostUpdate / update / hostUpdated), the scheduler short-circuits
-          // and the entry folds into the current cycle's changedProperties.
-          this.requestUpdate(propName, oldVal);
-        },
-      });
-
+    // The accessors live on the PROTOTYPE, installed once per class (#1646).
+    // They used to be defined on every instance, two closures and a
+    // defineProperty per declared property, which was the largest single
+    // cost of constructing a component on the SSR path (one instance per
+    // rendered element) and a measurable one on upgrade in the browser.
+    let plan = _accessorPlans.get(Ctor);
+    if (plan === undefined) plan = installAccessors(Ctor, props);
+
+    for (let i = 0; i < plan.length; i++) {
+      const { propName, decl: d } = plan[i];
+      // Capture any value set before the accessor could apply (an own data
+      // property written on the element before it upgraded). It shadows the
+      // prototype accessor, so it is lifted into the backing store.
+      let initial;
+      if (Object.hasOwn(this, propName)) {
+        initial = /** @type {any} */ (this)[propName];
+        delete (/** @type {any} */ (this))[propName];
+      }
       if (initial !== undefined) {
         this.__propValues[propName] = initial;
       } else if (d.default !== undefined) {
@@ -358,6 +406,9 @@ class WebComponentBase extends Base {
    * @private
    */
   _reflectAttribute(propName, value, decl) {
+    // A property with no attribute (`state: true` / `attribute: false`) has
+    // nothing to reflect to.
+    if (!isAttributeBacked(decl)) return;
     // A custom `attribute` option wins over the kebab-cased property name.
     const attrName = decl.attribute || hyphenate(propName);
     // Guard against re-entrant loops: attributeChangedCallback fires when
@@ -535,6 +586,17 @@ class WebComponentBase extends Base {
 
   _activate() {
     this._connected = true;
+    // A value written on the element before its class was defined is an own
+    // data property, and it hides any accessor of the same name for good.
+    // `_initializeProperties` lifts the declared properties in the
+    // constructor; an accessor the subclass defines itself (a getter/setter
+    // over a private signal, the shape internal state another element assigns
+    // takes) gets the same lift here, on the first connect, since its private
+    // field does not exist yet while the base constructor runs.
+    if (!this.__accessorsLifted) {
+      this.__accessorsLifted = true;
+      liftShadowedAccessors(this);
+    }
     // Reflect declared reflect:true properties from their current value now
     // that the element is connected. Constructor / willUpdate defaults were
     // set while disconnected (the setter skips reflection then), so this is
@@ -596,7 +658,7 @@ class WebComponentBase extends Base {
       // b. SSR hydration (first mount, <!--webjs-hydrate--> marker
       //    present). Children are already inside their
       //    <slot data-webjs-light data-projection="actual"> elements
-      //    (injectDSD placed them). Adopt those assignments BEFORE
+      //    (the SSR walk placed them). Adopt those assignments BEFORE
       //    _performRender so we retain references to the SSR'd nodes;
       //    the renderer's createInstance().replaceChildren() will
       //    detach them, but the slot-apply step re-attaches the same
@@ -648,7 +710,7 @@ class WebComponentBase extends Base {
     }
 
     // Notify all controllers that the host is connected.
-    for (const c of this.__controllers) {
+    for (const c of this.__controllers || NO_CONTROLLERS) {
       if (c.hostConnected) c.hostConnected();
     }
 
@@ -731,11 +793,14 @@ class WebComponentBase extends Base {
     // Dispose the signal watcher so dependency edges drop. Without
     // this the element holds references to module-scope signals
     // (and vice versa) forever.
-    if (this.__signalWatcher) {
-      this.__signalWatcher.dispose();
-      this.__signalWatcher = undefined;
+    for (const slot of ['__signalWatcher', '__postWatcher']) {
+      const self = /** @type {any} */ (this);
+      if (self[slot]) {
+        self[slot].dispose();
+        self[slot] = undefined;
+      }
     }
-    for (const c of this.__controllers) {
+    for (const c of this.__controllers || NO_CONTROLLERS) {
       if (c.hostDisconnected) c.hostDisconnected();
     }
   }
@@ -832,18 +897,92 @@ class WebComponentBase extends Base {
    *   7. `firstUpdated(changedProperties)` runs once, on the first render only
    *   8. `updated(changedProperties)` runs after every commit
    *   9. Resolve `updateComplete` promise
+   *
+   * Every signal the SYNCHRONOUS part of that cycle reads is tracked, not
+   * only the ones `render()` reads, which is the span lit-labs/signals tracks
+   * by running `performUpdate` inside a computed. So a signal read only in
+   * `willUpdate()` or `updated()` (a host attribute derived from internal
+   * state) re-renders the component when it changes. Two watchers split it
+   * (see {@link _tracked}): one over steps 2-6 (`render()` included), one
+   * over the post-commit hooks, so a write `updated()` makes to something
+   * `render()` read still schedules the next update. The DOM commits are
+   * the parts left untracked (see `update()`).
    * @private
    */
   _performRender() {
     if (!this._renderRoot) return;
+    this.__cycleRendered = false;
+    const postCommit = this._tracked('__signalWatcher', () => this._runUpdateCycle());
+    // A sync commit runs its post-commit hooks OUTSIDE the first watcher's
+    // phase, under their own watcher.
+    if (postCommit) postCommit();
+  }
+
+  /**
+   * Run one phase of the update cycle with the signals it reads recorded on
+   * the watcher in `slot`, creating the watcher on first use. A watcher
+   * re-records its read set on every phase it observes, and a later change
+   * to any of those signals schedules an update.
+   *
+   * Three rules keep that safe:
+   *  - A phase ignores notifications from its OWN writes. A write to a signal
+   *    the phase read earlier is the phase's business, not a reason to run it
+   *    again: before a commit it is already folded into this pass, and after
+   *    one it is often not the component's code at all (an event `updated()`
+   *    dispatches, whose listener does a read-modify-write on a store), which
+   *    would otherwise loop.
+   *  - A pre-commit phase that never reached `render()` (`shouldUpdate()`
+   *    returned false, or a hook threw) keeps the signals the last render
+   *    read on top of the ones it read itself, or a skipped cycle would
+   *    silently unsubscribe the component.
+   *  - A watcher disposed during its own phase (a hook that detached the
+   *    host) is disposed again afterwards, since the phase kept recording.
+   *
+   * @template T
+   * @param {'__signalWatcher' | '__postWatcher'} slot
+   * @param {() => T} fn
+   * @returns {T}
+   * @private
+   */
+  _tracked(slot, fn) {
+    const self = /** @type {any} */ (this);
+    /** @type {any} */
+    let watcher = self[slot];
+    if (!watcher) {
+      watcher = self[slot] = new Signal.subtle.Watcher(() => {
+        if (!watcher.__inPhase && this._connected) this.requestUpdate();
+      });
+    }
+    const before = slot === '__signalWatcher' ? Signal.subtle.introspectSources(watcher) : null;
+    watcher.__inPhase = true;
+    try {
+      return watcher.observe(fn);
+    } finally {
+      watcher.__inPhase = false;
+      if (before && !this.__cycleRendered) {
+        watcher.watch(...new Set([...before, ...Signal.subtle.introspectSources(watcher)]));
+      }
+      if (!this._connected) {
+        watcher.dispose();
+        if (self[slot] === watcher) self[slot] = undefined;
+      }
+    }
+  }
+
+  /**
+   * Steps 1-6 of the update cycle, the phase {@link _performRender} tracks
+   * with the first watcher. Returns the post-commit half to run for a sync
+   * commit, or nothing (an async commit runs it when it lands).
+   * @returns {(() => void) | undefined}
+   * @private
+   */
+  _runUpdateCycle() {
 
     // Hold a stable reference to the current Map so all hooks see the same
     // snapshot. During the update phase (steps 3-6) the Map is mutated in
     // place when property setters fire, folding those changes into THIS
-    // cycle. The Map is replaced with a fresh empty one only after a
-    // successful commit so post-commit assignments queue the NEXT cycle.
-    // On `shouldUpdate=false` or hook errors, the Map is preserved so the
-    // accumulated changes survive into the next render.
+    // cycle. The Map is replaced when this phase finishes, including skipped
+    // updates and hook errors, so post-commit writes belong to the NEXT cycle.
     const changedProperties = this._changedProperties;
 
     // --- 1. Mark we're inside an update cycle ---
@@ -862,7 +1001,7 @@ class WebComponentBase extends Base {
         this.willUpdate(changedProperties);
 
         // --- 4. controllers' hostUpdate ---
-        for (const c of this.__controllers) {
+        for (const c of this.__controllers || NO_CONTROLLERS) {
           if (c.hostUpdate) c.hostUpdate();
         }
 
@@ -881,6 +1020,7 @@ class WebComponentBase extends Base {
         // in _commitAsync.
         if (this.__renderAbort) this.__renderAbort.abort();
         this.__renderAbort = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        this.__cycleRendered = true;
         try {
           const r = this.update(changedProperties);
           if (r && typeof r.then === 'function') pendingCommit = r;
@@ -889,26 +1029,17 @@ class WebComponentBase extends Base {
         }
 
         if (!pendingCommit) {
-          // --- 6. controllers' hostUpdated (sync commit) ---
-          for (const c of this.__controllers) {
-            if (c.hostUpdated) c.hostUpdated();
-          }
           didCommit = true;
         }
       }
-      // shouldUpdate=false: preserve _changedProperties so the next
-      // requestUpdate keeps accumulating on top of the entries that
-      // didn't render this cycle.
     } catch (preCommitError) {
       console.error(`[webjs] lifecycle hook threw during update phase:`, preCommitError);
     } finally {
       this._isUpdating = false;
-      // The snapshot is consumed once the commit is DISPATCHED. For an async
-      // render it resets here too, so a property change during the in-flight
-      // fetch starts a fresh cycle (whose render token supersedes this one).
-      if (didCommit || pendingCommit) {
-        this._changedProperties = new Map();
-      }
+      // Consume this phase's snapshot even when shouldUpdate skips it. For an
+      // async render, changes during the fetch start a new cycle whose token
+      // supersedes the in-flight commit.
+      this._changedProperties = new Map();
     }
 
     // --- Async render: finish the cycle when the pending commit settles. ---
@@ -925,10 +1056,6 @@ class WebComponentBase extends Base {
         this.__pendingAsyncCommits--;
         // A newer render superseded this one; let the newer cycle finish.
         if (token !== this.__renderToken) return;
-        // --- 6. controllers' hostUpdated (after the async commit) ---
-        for (const c of this.__controllers) {
-          if (c.hostUpdated) c.hostUpdated();
-        }
         // --- 7-8 + updateComplete ---
         this._postCommit(changedProperties);
       };
@@ -966,16 +1093,21 @@ class WebComponentBase extends Base {
       return;
     }
 
-    // --- 7-8. Post-commit hooks (sync path). Errors are caught so the
-    // updateComplete promise always resolves.
+    // --- 7-8. Post-commit hooks (sync path), returned so they run outside
+    // this phase. Errors are caught so the updateComplete promise always
+    // resolves.
     if (didCommit) {
-      this._postCommit(changedProperties);
+      return () => this._postCommit(changedProperties);
     } else if (!this.__pendingAsyncCommits) {
       // A non-committing cycle resolves updateComplete only when no async
       // commit is in flight; otherwise the pending commit resolves it once it
       // lands, so `await el.updateComplete` never returns before that DOM.
       this._resolveUpdate();
     }
+    // No post-commit phase this cycle: re-arm its watcher, so a change it
+    // was notified of meanwhile does not leave it deaf to the next one.
+    if (!didCommit && /** @type {any} */ (this).__postWatcher) /** @type {any} */ (this).__postWatcher.watch();
+    return undefined;
   }
 
   /**
@@ -986,7 +1118,7 @@ class WebComponentBase extends Base {
    */
   _resolveUpdate() {
     if (this._updateResolve) {
-      const settled = this._changedProperties.size === 0;
+      const settled = !this._scheduled;
       this._updateResolve(settled);
       this._updateResolve = null;
     }
@@ -1018,7 +1150,7 @@ class WebComponentBase extends Base {
     this._isUpdating = true;
     try {
       this.willUpdate(changedProperties);
-      for (const c of this.__controllers) {
+      for (const c of this.__controllers || NO_CONTROLLERS) {
         if (c.hostUpdate) c.hostUpdate();
       }
       this._reflectDeclaredAttributes();
@@ -1048,7 +1180,7 @@ class WebComponentBase extends Base {
     const props = /** @type {any} */ (this.constructor).properties || {};
     for (const name of Object.keys(props)) {
       const decl = props[name];
-      if (!decl || !decl.reflect || decl.state) continue;
+      if (!decl || !decl.reflect) continue;
       this._reflectAttribute(name, this[name], decl);
     }
   }
@@ -1112,16 +1244,14 @@ class WebComponentBase extends Base {
    * @param {Map<string, unknown>} _changedProperties
    */
   update(_changedProperties) {
-    // Track signal reads during render so the component re-renders when
-    // any of them change. The watcher is lazy-allocated on first
-    // render and disposed in disconnectedCallback. observe() clears
-    // prior dep edges before fn(), so each render re-records its own
-    // (possibly different) read set.
-    if (!this.__signalWatcher) {
-      this.__signalWatcher = new Signal.subtle.Watcher(() => {
-        if (this._connected) this.requestUpdate();
-      });
+    const pendingReflection = this.__reflectPending;
+    this.__reflectPending = undefined;
+    for (const name of pendingReflection || []) {
+      const def = this.constructor.properties[name];
+      this._reflectAttribute(name, this[name], def);
     }
+    // The signal reads render() makes are tracked by the watcher
+    // _performRender runs the whole cycle under.
     let tpl;
     // Bind this render's abort signal (#492) around the synchronous part of
     // render() ONLY, so the RPC stub ties an action called there to this
@@ -1134,7 +1264,7 @@ class WebComponentBase extends Base {
     const outer = activeActionSignal();
     setActiveActionSignal(this.__renderAbort ? this.__renderAbort.signal : null);
     try {
-      this.__signalWatcher.observe(() => { tpl = this.render(); });
+      tpl = this.render();
     } finally {
       setActiveActionSignal(outer || null);
     }
@@ -1149,7 +1279,10 @@ class WebComponentBase extends Base {
     if (tpl && typeof (/** @type any */ (tpl).then) === 'function') {
       return this._commitAsync(/** @type {Promise<unknown>} */ (tpl));
     }
-    clientRender(tpl, this._renderRoot);
+    // The commit is untracked: a signal read while the DOM is patched (a
+    // `watch()` part, a child's synchronous work) belongs to whatever read
+    // it, not to this component's next render.
+    Signal.subtle.untrack(() => clientRender(tpl, this._renderRoot, { host: this }));
     return undefined;
   }
 
@@ -1178,7 +1311,7 @@ class WebComponentBase extends Base {
     if (this.__firstRendered && this._overridesRenderFallback()) {
       try {
         const fb = this.renderFallback();
-        if (fb !== undefined) clientRender(fb, this._renderRoot);
+        if (fb !== undefined) Signal.subtle.untrack(() => clientRender(fb, this._renderRoot, { host: this }));
       } catch (e) {
         console.error(`[webjs] renderFallback() threw:`, e);
       }
@@ -1197,7 +1330,7 @@ class WebComponentBase extends Base {
         // The sync path routes an identical throw to the same boundary, so
         // this is what makes the two paths agree.
         try {
-          clientRender(tpl, this._renderRoot);
+          clientRender(tpl, this._renderRoot, { host: this });
         } catch (commitError) {
           this._handleRenderError(
             commitError instanceof Error ? commitError : new Error(String(commitError)),
@@ -1234,7 +1367,7 @@ class WebComponentBase extends Base {
     );
     try {
       const fallback = this.renderError(error);
-      if (fallback !== undefined) clientRender(fallback, this._renderRoot);
+      if (fallback !== undefined) Signal.subtle.untrack(() => clientRender(fallback, this._renderRoot, { host: this }));
     } catch (fallbackError) {
       console.error(`[webjs] renderError() also threw:`, fallbackError);
     }
@@ -1247,16 +1380,21 @@ class WebComponentBase extends Base {
    * @private
    */
   _postCommit(changedProperties) {
+    const resolve = this._updateResolve;
+    this._updateResolve = null;
     try {
-      if (!this.__firstRendered) {
-        this.__firstRendered = true;
-        this.firstUpdated(changedProperties);
-      }
-      this.updated(changedProperties);
+      this._tracked('__postWatcher', () => {
+        for (const c of this.__controllers || NO_CONTROLLERS) c.hostUpdated?.();
+        if (!this.__firstRendered) {
+          this.__firstRendered = true;
+          this.firstUpdated(changedProperties);
+        }
+        this.updated(changedProperties);
+      });
     } catch (postCommitError) {
       console.error(`[webjs] lifecycle hook threw during post-commit phase:`, postCommitError);
     } finally {
-      this._resolveUpdate();
+      resolve?.(!this._scheduled);
     }
   }
 
@@ -1374,7 +1512,7 @@ class WebComponentBase extends Base {
    * @param {ReactiveController} controller
    */
   addController(controller) {
-    this.__controllers.add(controller);
+    (this.__controllers ??= new Set()).add(controller);
     if (this._connected && controller.hostConnected) {
       controller.hostConnected();
     }
@@ -1393,7 +1531,7 @@ class WebComponentBase extends Base {
    * @param {ReactiveController} controller
    */
   removeController(controller) {
-    this.__controllers.delete(controller);
+    if (this.__controllers) this.__controllers.delete(controller);
   }
 
   /**
@@ -1487,6 +1625,28 @@ export function WebComponent(properties) {
   }
 }
 
+/**
+ * Re-assign every own data property of `el` that hides a setter defined on
+ * its class chain below the WebJs base, so the value goes through the
+ * accessor instead of shadowing it.
+ *
+ * @param {any} el
+ */
+function liftShadowedAccessors(el) {
+  for (const key of Object.keys(el)) {
+    for (let p = Object.getPrototypeOf(el); p && p !== WebComponentBase.prototype; p = Object.getPrototypeOf(p)) {
+      const d = Object.getOwnPropertyDescriptor(p, key);
+      if (!d) continue;
+      if (d.set) {
+        const value = el[key];
+        delete el[key];
+        el[key] = value;
+      }
+      break;
+    }
+  }
+}
+
 // Ensure static inheritance and instanceof checks work
 Object.setPrototypeOf(WebComponent, WebComponentBase);
 WebComponent.prototype = WebComponentBase.prototype;

package/src/component/reactive.js

@@ -1,13 +1,13 @@
 import { tagOf } from '../registry.js';
 
 /**
- * Default change detection: strict inequality.
+ * Default change detection: Object.is inequality (NaN is stable; signed zero changes).
  * @param {unknown} a
  * @param {unknown} b
  * @returns {boolean}
  */
 export function defaultHasChanged(a, b) {
-  return a !== b;
+  return !Object.is(a, b);
 }
 
 /**
@@ -108,8 +108,9 @@ export function warnUnserializableReflection(host, propName, attrName, detail) {
  * while staying JSDoc-only and no-build.
  *
  * Subclasses declare:
- *  - `static properties`: attribute/property declarations with type info,
- *    reflection, custom converters, and internal-state mode
+ *  - reactive properties, through the `WebComponent({ ... })` factory:
+ *    attribute/property declarations with type info, reflection and custom
+ *    converters (internal state is an instance signal, not a property)
  *  - `static styles`: CSSResult or array thereof (only meaningful with
  *    `static shadow = true`; light-DOM components inherit global CSS)
  *  - `static shadow`: set `true` to opt in to shadow DOM (default: `false`

package/src/component.d.ts

@@ -85,11 +85,11 @@ interface WebComponentBase extends HTMLElement {
    * Schedule a re-render. Optionally record a property change so lifecycle
    * hooks can branch on what changed via `changedProperties`.
    *
-   * For instance-local state, prefer a reactive property (`WebComponent({
-   * foo: prop({ state: true }) })`) or a signal from
-   * `@webjsdev/core`'s `signal()`. The framework's built-in
-   * SignalWatcher wires every signal read in `render()` to a re-render
-   * automatically; explicit `requestUpdate()` is rarely needed.
+   * For instance-local state, use a reactive property (`WebComponent({
+   * open: prop<boolean>({ state: true }) })`) or a signal from
+   * `@webjsdev/core`'s `signal()`. The framework's built-in SignalWatcher
+   * wires every signal the update cycle reads to a re-render automatically;
+   * explicit `requestUpdate()` is rarely needed.
    */
   requestUpdate(name?: string, oldValue?: unknown): void;
   /** A Promise that resolves after the next render commit. */
@@ -210,6 +210,12 @@ export declare function prop<T>(
   opts?: Omit<PropertyDeclaration<T>, 'type'>
 ): PropertyDeclaration<T>;
 
+// No type constructor and no attribute: nothing says what the value is, so it
+// is `unknown` until narrowed (`prop<boolean>({ state: true })`).
+export declare function prop<T = unknown>(
+  opts: PropertyDeclaration<T> & ({ state: true } | { attribute: false })
+): PropertyDeclaration<T>;
+
 export declare function prop<T = string>(
   opts?: PropertyDeclaration<T>
 ): PropertyDeclaration<T>;