what-core 0.13.3 → 0.13.5

package/src/a11y.js

@@ -53,12 +53,13 @@ export function useFocusRestore() {
 // Keep focus within a container (for modals, dialogs, etc.)
 
 export function useFocusTrap(containerRef) {
+  /** @type {HTMLElement | null} */
   let previousFocus = null;
 
   function activate() {
     if (typeof document === 'undefined') return;
 
-    previousFocus = document.activeElement;
+    previousFocus = /** @type {HTMLElement | null} */ (document.activeElement);
     const container = containerRef.current || containerRef;
 
     if (!container || typeof container.querySelectorAll !== 'function') return;
@@ -131,6 +132,7 @@ export function FocusTrap({ children, active = true }) {
   const containerRef = { current: null };
   const refVersion = signal(0);
   const trap = useFocusTrap(containerRef);
+  /** @type {(() => void) | null | undefined} */
   let trapCleanup = null;
 
   const setRef = (el) => {
@@ -176,6 +178,7 @@ export function FocusTrap({ children, active = true }) {
 
 // --- Screen Reader Announcements ---
 
+/** @type {HTMLDivElement | null} */
 let announcer = null;
 let announcerId = 0;
 

package/src/agent-context.js

@@ -8,7 +8,7 @@ import { getCollectedErrors } from './errors.js';
 // --- Version ---
 // Keep in sync with packages/core/package.json (checked by
 // core/test/guardrails.test.js so it can't silently go stale again).
-const VERSION = '0.13.3';
+const VERSION = '0.13.5';
 
 // --- Component Registry ---
 // Tracks mounted components for agent inspection.

package/src/animation.js

@@ -29,7 +29,9 @@ export function spring(initialValue, options = {}) {
   const velocity = signal(0);
   const isAnimating = signal(false);
 
+  /** @type {number | null} */
   let rafId = null;
+  /** @type {number | null} */
   let lastTime = null;
 
   function tick(time) {
@@ -138,13 +140,16 @@ export function tween(from, to, options = {}) {
   const value = signal(from);
   const isAnimating = signal(true);
 
+  /** @type {number | null} */
   let startTime = null;
+  /** @type {number | null} */
   let rafId = null;
 
   function tick(time) {
     if (startTime === null) startTime = time;
+    const t0 = /** @type {number} */ (startTime);
 
-    const elapsed = time - startTime;
+    const elapsed = time - t0;
     const t = Math.min(elapsed / duration, 1);
     const easedT = easing(t);
     const currentValue = from + (to - from) * easedT;
@@ -269,6 +274,7 @@ export function useGesture(element, handlers = {}) {
   let lastTime = 0;
   let lastX = 0;
   let lastY = 0;
+  /** @type {ReturnType<typeof setTimeout> | null} */
   let longPressTimer = null;
 
   function handleStart(e) {
@@ -377,6 +383,7 @@ export function useGesture(element, handlers = {}) {
   }
 
   // Pinch handling (touch only)
+  /** @type {number | null} */
   let initialPinchDistance = null;
 
   function handlePinchMove(e) {

package/src/components.js

@@ -24,6 +24,7 @@ export function memo(Component, _areEqual) {
 }
 
 // Injected by dom.js
+/** @type {(() => any) | null} */
 let _getCurrentComponent = null;
 export function _injectGetCurrentComponent(fn) { _getCurrentComponent = fn; }
 
@@ -284,6 +285,7 @@ export function Match(props) {
 // Late-bound renderers, injected by render.js. components.js cannot import
 // render.js directly (render -> dom -> components is already a cycle), so the
 // same injection precedent as _injectGetCurrentComponent applies here.
+/** @type {{ hydrate?: Function, insert?: Function } | null} */
 let _islandRuntime = null;
 
 /** @internal */

package/src/data.js

@@ -226,6 +226,7 @@ export function useFetch(url, options = {}) {
   const data = signal(initialData);
   const error = signal(null);
   const isLoading = signal(true);
+  /** @type {AbortController | null} */
   let abortController = null;
 
   async function fetchData() {
@@ -342,6 +343,7 @@ export function useSWR(rawKey, fetcher, options = {}) {
     return empty && fetching;
   });
 
+  /** @type {AbortController | null} */
   let abortController = null;
 
   // `force` is invalidateQueries(): "this data is wrong now". It bypasses the
@@ -603,6 +605,7 @@ export function useQuery(options) {
   // effect's cleanup must leave it alone. One shared controller meant an
   // unrelated re-render cancelled a button click's refetch(), whose promise
   // then resolved with `undefined`.
+  /** @type {{ controller: AbortController, manual: boolean, direction?: string } | null} */
   let inFlight = null;
   let cleanupTimer = null;
 
@@ -895,6 +898,7 @@ export function useInfiniteQuery(options) {
   // The page request in flight and who asked for it. See the matching note in
   // useQuery: an explicit fetchNextPage()/refetch() belongs to the caller, and
   // the effect's cleanup must not cancel one just because it re-ran.
+  /** @type {{ controller: AbortController, manual: boolean, direction?: string } | null} */
   let inFlight = null;
 
   // clearCache() reaches an infinite query through here, because its pages

package/src/dom.js

@@ -198,6 +198,69 @@ export function disposeTree(node) {
   }
 }
 
+// --- _liveRegionNodes(tracked) ---
+//
+// The nodes a reactive region must remove, as the DOM stands NOW rather than as
+// it stood when the region last rendered.
+//
+// A region records what its value produced and reuses that record as the removal
+// set on its next run. For content the region built outright the record stays
+// true, because nothing else edits those nodes. Content that manages ITSELF is
+// not like that: a mapArray list and a nested reactive region both own an effect
+// and keep replacing their own nodes on their own schedule, so by the time the
+// outer region is torn down its record describes a shape that no longer exists.
+//
+// Removing only the recorded nodes therefore stranded everything the inner
+// effect had produced since:
+//
+//   {() => show() && <>{() => items().map(i => <li key={i}>{i}</li>)}<p>z</p></>}
+//
+// mounted with two items and grown to three, then switched off, removed the two
+// rows it had recorded and left the third in the DOM. Switching back on rendered
+// a full fresh list beside that orphan, and the orphan survived every later
+// cycle because it was never in any record.
+//
+// Self-managing content is bracketed by a start/end marker pair for exactly this
+// reason: `<!--list-->`/`<!--/list-->` around an embedded list, `<!--fn-->`/
+// `<!--/fn-->` around a nested region. Everything the inner effect ever inserts
+// lands between the pair, so walking the live range picks up what was added late
+// and passes over what has already gone. `_rangeEnd` on the start marker is the
+// pairing this reads.
+//
+// Only teardown calls this. A region's record stays exactly what it produced,
+// because that is also what decides whether anything changed and what gets
+// repositioned on a re-render, and an inner effect's nodes are its own business
+// in both of those.
+//
+// The walk appends the live range to the record rather than replacing it, so a
+// node still standing is named twice. That is deliberate: every caller already
+// skips a node whose parent is not the one it is clearing, so the second visit
+// costs a pointer compare, and both disposal routes are idempotent by design.
+// Deduplicating would mean a Set on a path that runs for every teardown, to
+// prevent nothing.
+export function _liveRegionNodes(tracked) {
+  /** @type {any[] | null} */
+  let out = null;
+  for (const node of tracked) {
+    const end = /** @type {any} */ (node)._rangeEnd;
+    // Not a range start, or a range whose two ends have been separated by an
+    // earlier teardown: walking that would run past where the range closed and
+    // sweep up whatever comes after it. Two orphaned markers share a null parent
+    // and pass this test, but an orphan has no nextSibling, so the walk below is
+    // empty and the guard does not need to say so a second time.
+    if (!end || end.parentNode !== node.parentNode) continue;
+    if (!out) out = tracked.slice();
+    const buf = /** @type {any[]} */ (out);
+    for (let n = node.nextSibling; n; n = n.nextSibling) {
+      buf.push(n);
+      if (n === end) break;
+    }
+  }
+  // No range in the record — which is the overwhelmingly common case — means no
+  // allocation and the caller iterates exactly what it passed in.
+  return out || tracked;
+}
+
 // Mount a component tree into a DOM container
 export function mount(vnode, container) {
   if (typeof container === 'string') {
@@ -239,11 +302,32 @@ export function createDOM(vnode, parent, isSvg) {
   // function branch below would call vnode() with no parent and throw.
   if (typeof vnode === 'function' && vnode._mapArray) {
     const frag = document.createDocumentFragment();
-    const endMarker = document.createComment('/list-frag');
-    frag.appendChild(endMarker);
-    // The inserter inserts its content before `endMarker` within `frag`; once
-    // `frag` is appended to the real DOM the nodes (and endMarker) carry over.
-    vnode(frag, endMarker);
+    // Open the list with a start marker, the same bracket shape the reactive
+    // region below uses, and for the same reason: whoever embeds this fragment
+    // has to be able to find the list's content LATER, not just now.
+    //
+    // A list reached through here is embedded in some other region's value —
+    // `{cond && <>{items.map(...)}<p/></>}` and every variation of it. That
+    // region records the nodes it inserted and reuses the record as its removal
+    // set on the next run. The record is a snapshot, and the list is not
+    // snapshot-shaped: it owns an effect and goes on inserting and removing rows
+    // for as long as it is mounted. Rows appended after mount were absent from
+    // the record, so switching the region off removed the mount-time rows and
+    // orphaned the rest — and switching it back on rendered a second, complete
+    // list beside the orphans.
+    //
+    // Two markers describe a moving target that a list of nodes cannot:
+    // everything the list ever inserts lands between them, so reconcileInsert
+    // (render.js) can sweep the live range at teardown instead of trusting the
+    // snapshot. `_rangeEnd` is the pairing it reads.
+    const startMarker = document.createComment('list');
+    frag.appendChild(startMarker);
+    // Passing a null marker makes the inserter APPEND its own `/list` end marker
+    // to `frag` (insertBefore(node, null) is an append) and insert every row
+    // before it, so the list closes the range itself and no second bookend is
+    // needed. Once `frag` is appended to the real DOM the markers and the rows
+    // between them carry over together.
+    /** @type {any} */ (startMarker)._rangeEnd = vnode(frag, null);
     return frag;
   }
 
@@ -296,8 +380,11 @@ export function createDOM(vnode, parent, isSvg) {
       const realParent = endMarker.parentNode;
       if (!realParent) return; // not mounted yet — first run handled below
 
-      // Remove old nodes between markers
-      for (const old of currentNodes) {
+      // Remove old nodes between markers. The removal set is the LIVE one: a
+      // list or a nested region inside this one has been replacing its own
+      // nodes since they were recorded, and what it produced late is just as
+      // much this region's to remove as what it produced at mount.
+      for (const old of _liveRegionNodes(currentNodes)) {
         disposeTree(old);
         if (old.parentNode === realParent) realParent.removeChild(old);
       }
@@ -327,6 +414,11 @@ export function createDOM(vnode, parent, isSvg) {
     startMarker._dispose = dispose;
     // Also store dispose on endMarker so disposeTree can find it from either marker
     endMarker._dispose = dispose;
+    // This region manages itself, so an OUTER region that embeds it cannot
+    // describe it with a list of nodes: everything between the markers is
+    // replaced whenever this effect re-runs. Pairing them lets the outer
+    // teardown sweep the live range. See _liveRegionNodes.
+    /** @type {any} */ (startMarker)._rangeEnd = endMarker;
     return frag;
   }
 
@@ -1075,24 +1167,26 @@ function setProp(el, key, value, isSvg) {
   // aria-*/role BEFORE the boolean fast-path: these are enumerated string
   // attributes, so a boolean has to serialize as "true"/"false", never as HTML
   // boolean syntax. See _isAriaAttr.
-  if (_isAriaAttr(key)) {
+  // data-* joins aria-* here rather than falling through to the boolean branch
+  // below. Both are enumerated: `data-open="false"` is a distinct state from an
+  // absent `data-open`, and `[data-open="false"]` is an ordinary CSS selector,
+  // so collapsing false to "remove the attribute" throws information away.
+  // The compiled path in render.js has always stringified these, so keeping the
+  // generic boolean branch first is also what made an SSR page disagree with
+  // its own compiled client on hydration.
+  if (_isAriaAttr(key) || key.startsWith('data-')) {
     el.setAttribute(key, typeof value === 'boolean' ? String(value) : value);
     return;
   }
 
-  // Boolean attributes
+  // Boolean attributes. A genuine HTML boolean like `disabled` is present or
+  // absent; there is no `disabled="false"`.
   if (typeof value === 'boolean') {
     if (value) el.setAttribute(key, '');
     else el.removeAttribute(key);
     return;
   }
 
-  // data-*
-  if (key.startsWith('data-')) {
-    el.setAttribute(key, value);
-    return;
-  }
-
   // SVG
   if (isSvg) {
     if (value === false || value == null) {

package/src/errors.js

@@ -245,6 +245,25 @@ function Row() { return { name: 'a' }; }
 function Row({ name }) { return <li>{name}</li>; }`,
   },
 
+  COMPILED_JSX_IN_SSR: {
+    code: 'ERR_COMPILED_JSX_IN_SSR',
+    severity: 'error',
+    template: 'what-compiler output cannot be server-rendered: {{file}}.',
+    suggestion: 'what-compiler lowers JSX to module-scope _$template() calls that run document.createElement() at import time, and to _$createComponent() which builds DOM. Neither has a server-rendered form, so a module it compiled throws "document is not defined" when a server imports it. Server-rendered views have two supported spellings: author them with h(), or compile them with the automatic JSX runtime (jsxImportSource: "what-framework"), which emits h() calls that renderToString understands. what-compiler stays on the client entry, where the fine-grained output is the point.',
+    codeExample: `// Bad — a server module compiled by what-compiler:
+// vite.config.js: plugins: [what()]  +  vite build --ssr
+export function Page() { return <h1>Hi</h1>; }   // throws on import
+
+// Good — h(), which renderToString understands:
+import { h } from 'what-framework';
+export function Page() { return h('h1', null, 'Hi'); }
+
+// Good — the automatic JSX runtime for the server build:
+// vite.config.js (server): esbuild: { jsx: 'automatic',
+//                            jsxImportSource: 'what-framework' }
+export function Page() { return <h1>Hi</h1>; }   // lowers to h()`,
+  },
+
   FORM_ACTION_NOT_REGISTERED: {
     code: 'ERR_FORM_ACTION_NOT_REGISTERED',
     severity: 'error',
@@ -450,6 +469,7 @@ createWhatError('MISSING_KEY', { component: 'TodoList' });`,
 // into every bundle that imports what-core: it took the counter app from
 // 6.4 KB gzipped to 12.1 KB and tripped check:size. Inside a function, a
 // bundler that drops getErrorDefinition drops the catalogue with it.
+/** @type {Map<string, any> | null} */
 let _codeIndex = null;
 
 /** Look up a catalogue entry by its `ERR_*` code. Returns undefined if unknown. */

package/src/guardrails.js

@@ -161,6 +161,7 @@ export function validateImports(importNames) {
 // Simple Levenshtein-based closest match
 function findClosest(input) {
   const lower = input.toLowerCase();
+  /** @type {string | null} */
   let best = null;
   let bestDist = Infinity;
 

package/src/h.js

@@ -8,6 +8,13 @@
 const EMPTY_OBJ = Object.create(null);
 const EMPTY_ARR = [];
 
+/**
+ * Children are collected from `arguments` rather than a rest param so a
+ * 0-1 child call does not allocate. `@type` (not `@param`) is what TS 7
+ * uses to type that hidden tail; do not turn it into `...children`.
+ *
+ * @type {(tag: any, props?: any, ...children: any[]) => any}
+ */
 export function h(tag, props) {
   props = props || EMPTY_OBJ;
   // Collect children from arguments[2..n] without rest args — avoids array allocation

package/src/helpers.js

@@ -76,6 +76,7 @@ export function throttle(fn, ms) {
 }
 
 // Component context ref — injected by dom.js to avoid circular imports
+/** @type {(() => any) | null} */
 let _getCurrentComponentRef = null;
 export function _setComponentRef(fn) { _getCurrentComponentRef = fn; }
 
@@ -121,6 +122,7 @@ export function useLocalStorage(key, initial) {
   });
 
   // Listen for changes from other tabs
+  /** @type {((e: StorageEvent) => void) | null} */
   let storageHandler = null;
   if (typeof window !== 'undefined') {
     storageHandler = (e) => {

package/src/hooks.js

@@ -400,6 +400,7 @@ export function createResource(fetcher, options = {}) {
   const loading = signal(seeded == null);
   const error = signal(null);
 
+  /** @type {AbortController | null} */
   let controller = null;
 
   const refetch = async (source) => {

package/src/reactive.js

@@ -38,8 +38,11 @@ export function __setDevToolsHooks(hooks) {
   if (__DEV__) __devtools = hooks;
 }
 
+/** @type {WhatEffectNode | null} */
 let currentEffect = null;
+/** @type {WhatOwner | null} */
 let currentRoot = null;
+/** @type {WhatOwner | null} */
 let currentOwner = null;  // Ownership tree: tracks current owner context
 let insideComputed = false; // Track whether we're inside a computed() callback (dev-mode warning)
 let batchDepth = 0;
@@ -55,6 +58,7 @@ let pendingNeedSort = false;  // Track whether pendingEffects actually needs sor
 // to iterative. When a computed fn() reads another dirty computed, instead
 // of recursing, we throw a sentinel that gets caught by the outer loop.
 const NEEDS_UPSTREAM = Symbol('needs_upstream');
+/** @type {any[] | null} */
 let iterativeEvalStack = null;  // array when inside evaluation loop, null otherwise
 
 // --- Signal ---
@@ -75,6 +79,7 @@ export function signal(initial, debugName) {
   // Track the last effect that subscribed — skip redundant tracking when the
   // same effect reads this signal multiple times (common in template bindings).
   // lastTrackedEpoch tracks the effect's cleanup epoch to detect stale caches.
+  /** @type {WhatEffectNode | null} */
   let lastTracked = null;
   let lastTrackedEpoch = 0;
 
@@ -161,6 +166,7 @@ export function signal(initial, debugName) {
 export function computed(fn) {
   let value, dirty = true;
   const subs = new Set();
+  /** @type {WhatEffectNode | null} */
   let lastTracked = null;
   let lastTrackedEpoch = 0;
 
@@ -187,7 +193,14 @@ export function computed(fn) {
   inner._markDirty = () => { dirty = true; };
   inner._isDirty = () => dirty;
 
+  if (currentRoot) {
+    currentRoot.disposals.push(() => _disposeEffect(inner));
+  }
+
   function read() {
+    // Like an owned memo, a disposed computed retains its last value but must
+    // never recreate subscriptions (or enter the dirty-evaluation trampoline).
+    if (inner.disposed) return value;
     const ce = currentEffect;
     if (ce !== null) {
       if (ce !== lastTracked || ce._epoch !== lastTrackedEpoch) {
@@ -210,7 +223,7 @@ export function computed(fn) {
 
   read._signal = true;
   read.peek = () => {
-    if (dirty) _evaluateComputed(inner);
+    if (dirty && !inner.disposed) _evaluateComputed(inner);
     return value;
   };
 
@@ -247,7 +260,7 @@ function _evaluateComputed(computedEffect) {
     while (stack.length > 0) {
       const current = stack[stack.length - 1];
 
-      if (!current._isDirty || !current._isDirty()) {
+      if (current.disposed || !current._isDirty || !current._isDirty()) {
         // Already clean — pop and continue
         stack.pop();
         continue;
@@ -260,7 +273,7 @@ function _evaluateComputed(computedEffect) {
       const deps = current.deps;
       for (let i = 0; i < deps.length; i++) {
         const depOwner = deps[i]._owner;
-        if (depOwner && depOwner._computed && depOwner._isDirty && depOwner._isDirty()) {
+        if (depOwner && !depOwner.disposed && depOwner._computed && depOwner._isDirty && depOwner._isDirty()) {
           stack.push(depOwner);
           pushedUpstream = true;
         }
@@ -325,6 +338,11 @@ export function effect(fn, opts) {
   try {
     const result = e.fn();
     if (typeof result === 'function') e._cleanup = result;
+  } catch (err) {
+    // No disposer is returned when setup throws: undo the partial subscription
+    // graph now, including an update queued during the failed first run.
+    _disposeEffect(e);
+    throw err;
   } finally {
     currentEffect = prev;
   }
@@ -406,7 +424,7 @@ function _runEffect(e) {
 
   // Stable effect fast path: deps don't change, skip cleanup/re-subscribe.
   // This is critical for performance: effects like `() => el.className = sig() ? 'a' : ''`
-  // always read the same signal(s). After auto-promotion, re-runs skip the O(deps)
+  // always read the same signal(s). With explicit opt-in, re-runs skip the O(deps)
   // cleanup + re-subscribe cycle entirely.
   if (e._stable) {
     if (e._cleanup) {
@@ -430,10 +448,6 @@ function _runEffect(e) {
     return;
   }
 
-  // Save the single dep for auto-stable detection (safe: 1-dep effects
-  // have deterministic dep sets — no conditional reads possible).
-  const singleDep = e.deps.length === 1 ? e.deps[0] : null;
-
   cleanup(e);
   // Run effect cleanup from previous run
   if (e._cleanup) {
@@ -459,16 +473,9 @@ function _runEffect(e) {
     currentEffect = prev;
   }
 
-  // Auto-promote to stable: effects with exactly 1 dep that remains the same
-  // after re-run have a fixed dependency graph. Skip cleanup/re-subscribe
-  // on future re-runs. This is safe because a single-dep effect can't have
-  // conditional signal reads that change which signal is tracked.
-  // Guard: don't promote self-triggering effects (those that write to the signal
-  // they read, causing re-queuing). Check e._pending to detect this.
-  if (singleDep !== null && e.deps.length === 1 && e.deps[0] === singleDep
-      && !e._cleanup && !e._pending) {
-    e._stable = true;
-  }
+  // Repeatedly observing one dependency does not prove a stable graph: that
+  // signal may open a branch on a later run. Only explicit { stable: true }
+  // effects may skip dependency tracking.
 
   if (__DEV__ && __devtools?.onEffectRun) __devtools.onEffectRun?.(e);
 }
@@ -502,6 +509,7 @@ function cleanup(e) {
 // call notify() recursively. The queue drains iteratively in the outermost call.
 
 let notifyDepth = 0;        // Tracks recursive notify depth
+/** @type {(Set<any> | null)[] | null} */
 let notifyQueue = null;     // Reusable queue, allocated on first recursive call
 let notifyQueueLen = 0;     // Length of the queue
 
@@ -552,13 +560,15 @@ function notify(subs) {
         _processSubscriber(e);
       }
       // Drain any queued subscriber sets from recursive notify calls
-      if (notifyQueueLen > 0) {
+      if (notifyQueueLen > 0 && notifyQueue) {
         let qi = 0;
+        const q = notifyQueue;
         while (qi < notifyQueueLen) {
-          const queuedSubs = notifyQueue[qi];
-          notifyQueue[qi] = null; // Allow GC
+          const queuedSubs = q[qi];
+          q[qi] = null; // Allow GC
           qi++;
-          for (const e of queuedSubs) {
+          // Slots 0..len-1 are Sets; null is only written after a slot is drained.
+          for (const e of /** @type {Set<any>} */ (queuedSubs)) {
             _processSubscriber(e);
           }
         }
@@ -701,7 +711,12 @@ export function memo(fn) {
 
   e._level = 1;
 
-  _runEffect(e);
+  try {
+    _runEffect(e);
+  } catch (err) {
+    _disposeEffect(e);
+    throw err;
+  }
   _updateLevel(e);
 
   // Register subscriber set owner for level tracking
@@ -797,6 +812,7 @@ export function runWithOwner(owner, fn) {
 export function createRoot(fn) {
   const prevRoot = currentRoot;
   const prevOwner = currentOwner;
+  /** @type {WhatOwner} */
   const root = {
     /** @type {Array<() => void>} */
     disposals: [],
@@ -814,28 +830,7 @@ export function createRoot(fn) {
   currentOwner = root;
 
   try {
-    const dispose = () => {
-      if (root._disposed) return;
-      root._disposed = true;
-
-      // Dispose children first (depth-first, reverse order)
-      for (let i = root.children.length - 1; i >= 0; i--) {
-        _disposeRoot(root.children[i]);
-      }
-      root.children.length = 0;
-
-      // Dispose own effects (reverse order for LIFO cleanup)
-      for (let i = root.disposals.length - 1; i >= 0; i--) {
-        root.disposals[i]();
-      }
-      root.disposals.length = 0;
-
-      // Remove from parent's children list
-      if (root.owner) {
-        const idx = root.owner.children.indexOf(root);
-        if (idx >= 0) root.owner.children.splice(idx, 1);
-      }
-    };
+    const dispose = () => _disposeRoot(root);
     return fn(dispose);
   } finally {
     currentRoot = prevRoot;
@@ -847,18 +842,35 @@ export function createRoot(fn) {
 function _disposeRoot(root) {
   if (root._disposed) return;
   root._disposed = true;
-
-  // Dispose children first
-  for (let i = root.children.length - 1; i >= 0; i--) {
-    _disposeRoot(root.children[i]);
+  let failed = false;
+  let firstError;
+
+  // A user cleanup failure must not strand siblings or earlier effects after
+  // the scope has already become disposed. Finish LIFO cleanup, then rethrow
+  // the first error so callers keep the original useful failure.
+  while (root.children.length > 0) {
+    // Remove before calling user code: a child may dispose another sibling,
+    // mutating this same array. Numeric indexes would then skip or overrun it.
+    const child = root.children.pop();
+    try { _disposeRoot(child); } catch (err) {
+      if (!failed) { failed = true; firstError = err; }
+    }
   }
   root.children.length = 0;
 
   // Dispose own effects
   for (let i = root.disposals.length - 1; i >= 0; i--) {
-    root.disposals[i]();
+    try { root.disposals[i](); } catch (err) {
+      if (!failed) { failed = true; firstError = err; }
+    }
   }
   root.disposals.length = 0;
+
+  if (root.owner) {
+    const idx = root.owner.children.indexOf(root);
+    if (idx >= 0) root.owner.children.splice(idx, 1);
+  }
+  if (failed) throw firstError;
 }
 
 // --- _createItemScope ---
@@ -868,6 +880,7 @@ function _disposeRoot(root) {
 export function _createItemScope(fn) {
   const prevRoot = currentRoot;
   const prevOwner = currentOwner;
+  /** @type {WhatOwner} */
   const scope = {
     /** @type {Array<() => void>} */
     disposals: [],
@@ -880,20 +893,7 @@ export function _createItemScope(fn) {
   currentOwner = scope;
 
   try {
-    const dispose = () => {
-      if (scope._disposed) return;
-      scope._disposed = true;
-      // Dispose children
-      for (let i = scope.children.length - 1; i >= 0; i--) {
-        _disposeRoot(scope.children[i]);
-      }
-      scope.children.length = 0;
-      // Dispose own effects
-      for (let i = scope.disposals.length - 1; i >= 0; i--) {
-        scope.disposals[i]();
-      }
-      scope.disposals.length = 0;
-    };
+    const dispose = () => _disposeRoot(scope);
     return fn(dispose);
   } finally {
     currentRoot = prevRoot;