@solidjs/signals 2.0.0-beta.24 → 2.0.0-beta.25

package/dist/dev.js

@@ -2230,7 +2230,21 @@ function recompute(el, create = false) {
       value = inFlightChanged || !isAsyncResult ? fnResult : handleAsync(el, fnResult);
       if (!inFlightChanged && !isAsyncResult) el._inFlight = null;
     }
-    clearStatus(el, create);
+    // On a status-free node clearStatus is a guaranteed no-op: every branch
+    // in its body is gated on one of these fields, and with _statusFlags === 0
+    // the flags write (create or not) stores the 0 already there.
+    if (
+      el._statusFlags !== 0 ||
+      el._notifyStatus !== undefined ||
+      el._error ||
+      el._reask ||
+      el._blocked ||
+      el._pendingSources !== undefined ||
+      el._pendingSignal !== undefined ||
+      el._latestValueComputed !== undefined ||
+      el._child !== null
+    )
+      clearStatus(el, create);
     // _optimisticLane is only ever assigned by engine paths.
     if (el._optimisticLane) GlobalQueue._laneAsyncSettled(el);
   } catch (e) {
@@ -2291,7 +2305,15 @@ function recompute(el, create = false) {
     if (el._error);
     else if (valueChanged) {
       const prevVisible = hasOverride ? el._overrideValue : undefined;
-      if (create || (isEffect && activeTransition !== el._transition) || isOptimisticDirty) {
+      if (
+        create ||
+        // Plain sync flush (no transition on either side) commits effect
+        // values directly — the pending round-trip (queuePendingNode +
+        // commitPendingNodes) exists to sequence transition reveals, and
+        // paying it per effect on the plain path is pure overhead.
+        (isEffect && (activeTransition !== el._transition || activeTransition === null)) ||
+        isOptimisticDirty
+      ) {
         el._value = value;
         // Lane-propagated correction: upstream data is fresh, correct the
         // override unconditionally. The direct _value commit is the lane's
@@ -2311,7 +2333,12 @@ function recompute(el, create = false) {
         if ((activeTransition || el._transition) && GlobalQueue._syncCompanions !== null)
           GlobalQueue._syncCompanions(el, value);
       }
-      if (!hasOverride || isOptimisticDirty || el._overrideValue !== prevVisible)
+      // insertSubs only walks _subs (no scheduling of its own), so a
+      // subscriber-less node has nothing to notify.
+      if (
+        el._subs !== null &&
+        (!hasOverride || isOptimisticDirty || el._overrideValue !== prevVisible)
+      )
         insertSubs(el, isOptimisticDirty || hasOverride);
     } else if (hasOverride) {
       // Unchanged value (equals the override) recomputed while the override
@@ -2610,6 +2637,39 @@ function prepareComputed(comp, refresh) {
     updateIfNecessary(comp);
   }
 }
+/**
+ * Sentinel returned by readNodeFast when the plain-signal fast path does not
+ * apply and the caller must fall back to the full read().
+ */
+const READ_SLOW = Symbol("read-slow");
+/**
+ * read()'s plain-signal fast path as a standalone entry for hot callers
+ * (store traps). Safe to substitute for read() only because the bail
+ * conditions mirror read()'s prelude and fast-path guard exactly: the
+ * latestRead and pendingCheck windows run side-effectful hooks before the
+ * fast path, `_fn` nodes need prepareComputed, and firewall / override /
+ * snapshot / transition / lane / dev-strictRead state all take the full
+ * resolution. Anything slow returns READ_SLOW; the caller then calls read().
+ */
+function readNodeFast(el) {
+  if (
+    latestReadActive ||
+    pendingCheckActive ||
+    el._fn ||
+    el._firewall ||
+    el._overrideValue !== undefined ||
+    el._snapshotValue !== undefined ||
+    activeTransition !== null ||
+    currentOptimisticLane !== null ||
+    snapshotCaptureActive ||
+    strictRead
+  )
+    return READ_SLOW;
+  let c = context;
+  if (c?._root) c = c._parentComputed;
+  if (c && tracking) link(el, c);
+  return !c || el._pendingValue === NOT_PENDING ? el._value : el._pendingValue;
+}
 function read(el) {
   // Handle latest() mode: read from _latestValueComputed
   // Checked before isPending so that isPending(() => latest(x)) checks
@@ -2805,7 +2865,12 @@ function setSignal(el, v) {
   if (!valueChanged) return v;
   if (el._pendingValue === NOT_PENDING) queuePendingNode(el);
   el._pendingValue = v;
-  GlobalQueue._syncCompanions !== null && GlobalQueue._syncCompanions(el, v);
+  // syncCompanions only pokes _pendingSignal/_latestValueComputed — with
+  // neither companion present the call is a guaranteed no-op (companions are
+  // only ever created, never removed, and creating one installs the hook).
+  (el._pendingSignal !== undefined || el._latestValueComputed !== undefined) &&
+    GlobalQueue._syncCompanions !== null &&
+    GlobalQueue._syncCompanions(el, v);
   el._time = clock;
   insertSubs(el);
   schedule();
@@ -3147,7 +3212,11 @@ function optimisticWrite(el, v) {
   // brand, and erasing it makes the write invisible and routes follow-up
   // writes off the optimistic path into permanent commits (#2898).
   el._overrideValue = v === undefined ? OVERRIDE_UNDEFINED : v;
-  GlobalQueue._syncCompanions !== null && GlobalQueue._syncCompanions(el, v);
+  // syncCompanions only pokes _pendingSignal/_latestValueComputed — with
+  // neither companion present the call is a guaranteed no-op.
+  (el._pendingSignal !== undefined || el._latestValueComputed !== undefined) &&
+    GlobalQueue._syncCompanions !== null &&
+    GlobalQueue._syncCompanions(el, v);
   el._time = clock;
   insertSubs(el, true);
   schedule();
@@ -4591,27 +4660,70 @@ function keyedMatch(a, b, keyFn) {
 // and `in` dependencies should follow the new value's membership. Use
 // membership rather than length arithmetic so sparse arrays and named array
 // props behave like normal property reads.
+// Inline key iteration on purpose: these loops run per array target per
+// reconcile pass, and a shared helper means a closure + per-key call in
+// instruction counts. String-only records (the common case) iterate in
+// place; symbol-bearing records take the nodeKeys array path.
 function syncArrayNodeMembership(target, next) {
   let nodes = target[STORE_NODE];
   if (nodes) {
-    const keys = nodeKeys(nodes);
-    for (let i = 0, len = keys.length; i < len; i++) {
-      const key = keys[i];
-      key in next || setSignal(nodes[key], undefined);
+    if (symbolKeyedRecords.has(nodes)) {
+      const keys = nodeKeys(nodes);
+      for (let i = 0, len = keys.length; i < len; i++) {
+        keys[i] in next || setSignal(nodes[keys[i]], undefined);
+      }
+    } else {
+      for (const key in nodes) {
+        key in next || setSignal(nodes[key], undefined);
+      }
     }
   }
   if ((nodes = target[STORE_HAS])) {
-    const keys = nodeKeys(nodes);
-    for (let i = 0, len = keys.length; i < len; i++) {
-      const key = keys[i];
-      setSignal(nodes[key], key in next);
+    if (symbolKeyedRecords.has(nodes)) {
+      const keys = nodeKeys(nodes);
+      for (let i = 0, len = keys.length; i < len; i++) {
+        setSignal(nodes[keys[i]], keys[i] in next);
+      }
+    } else {
+      for (const key in nodes) {
+        setSignal(nodes[key], key in next);
+      }
     }
   }
 }
+// Recurse into a matched wrappable child pair without manufacturing a proxy:
+// resolve the child's target through the lookup and dispatch directly. A
+// lookup miss means the child was never observed — no proxy, no nodes, no
+// subscribers anywhere below — so the parent's swap making `next`
+// authoritative IS the whole update; a later read wraps next's child on
+// demand. This turns the diff from O(previous graph) into O(observed graph)
+// and drops the wrap()/$PROXY/$TARGET round-trip per visited child.
+// Wrap-family stores (projections/optimistic) own child proxy creation and
+// keep the proxy-based recursion.
+function applyStateChild(next, prevRaw, target, keyFn) {
+  if (target[STORE_WRAP] !== undefined) {
+    applyState(next, wrap(prevRaw, target), keyFn);
+    return;
+  }
+  const childTarget = prevRaw[$TARGET] ?? storeLookup.get(prevRaw);
+  if (childTarget === undefined) return;
+  next = unwrap(next);
+  if (childTarget[STORE_SHALLOW]) {
+    applyStateShallow(next, childTarget);
+  } else if (childTarget[STORE_OVERRIDE] || childTarget[STORE_OPTIMISTIC_OVERRIDE]) {
+    applyStateSlow(next, childTarget, keyFn);
+  } else {
+    applyStateFast(next, childTarget, keyFn);
+  }
+}
 // Reconcile a single array slot: recurse into a wrappable pair, otherwise replace
 // the node's value outright (covers object→primitive and primitive→object).
 function applyArrayItem(next, previous, target, node, keyFn) {
-  if (isWrappable(next) && isWrappable(previous)) {
+  if (
+    isWrappable(next) &&
+    isWrappable(previous) &&
+    !(rawValuesUsed && (isRawValue(previous) || isRawValue(next)))
+  ) {
     const wrapped = wrap(previous, target);
     node && setSignal(node, wrapped);
     applyState(next, wrapped, keyFn);
@@ -4631,27 +4743,54 @@ function applyArrayItem(next, previous, target, node, keyFn) {
  */
 function applyDescendants(previous, next, target, nodes, keyFn, override, optOverride) {
   const lookup = target[STORE_LOOKUP] || storeLookup;
-  const keys = (override ? getKeys(previous, override) : Object.keys(previous)).concat(
-    getStoreSymbols(previous, override)
-  );
-  for (let i = 0, len = keys.length; i < len; i++) {
-    const key = keys[i];
+  if (override) {
+    const keys = getKeys(previous, override).concat(getStoreSymbols(previous, override));
+    for (let i = 0, len = keys.length; i < len; i++) {
+      const key = keys[i];
+      if (nodes?.[key]) continue; // main loop already diffed this slot
+      const previousValue = unwrap(getOverrideValue(previous, override, key, optOverride));
+      if (!isWrappable(previousValue)) continue;
+      descendInto(previousValue, next[key], lookup, keyFn);
+    }
+    return;
+  }
+  // No-override path (every applyStateFast call): iterate in place instead of
+  // building keys + symbols + concat arrays per object per pass. The cheap
+  // bails (noded key, primitive value) stay inline — only genuine descent
+  // candidates pay a call.
+  for (const key in previous) {
     if (nodes?.[key]) continue; // main loop already diffed this slot
-    const previousValue = unwrap(
-      override ? getOverrideValue(previous, override, key, optOverride) : previous[key]
-    );
+    const previousValue = unwrap(previous[key]);
     if (!isWrappable(previousValue)) continue;
-    const childTarget = (lookup.get(previousValue) ?? storeLookup.get(previousValue))?.[$TARGET];
-    if (!childTarget?.[STORE_DESC]) continue;
-    const nextValue = unwrap(next[key]);
-    if (
-      previousValue === nextValue ||
-      !isWrappable(nextValue) ||
-      Array.isArray(previousValue) !== Array.isArray(nextValue) ||
-      (keyFn(previousValue) != null && keyFn(previousValue) !== keyFn(nextValue))
-    )
-      continue;
-    applyState(nextValue, wrap(previousValue, target), keyFn);
+    descendInto(previousValue, next[key], lookup, keyFn);
+  }
+  const syms = Object.getOwnPropertySymbols(previous);
+  for (let i = 0, len = syms.length; i < len; i++) {
+    if (Object.prototype.propertyIsEnumerable.call(previous, syms[i])) {
+      if (nodes?.[syms[i]]) continue;
+      const previousValue = unwrap(previous[syms[i]]);
+      if (!isWrappable(previousValue)) continue;
+      descendInto(previousValue, next[syms[i]], lookup, keyFn);
+    }
+  }
+}
+function descendInto(previousValue, rawNext, lookup, keyFn) {
+  const childTarget = lookupTarget(previousValue, lookup);
+  if (!childTarget?.[STORE_DESC]) return;
+  const nextValue = unwrap(rawNext);
+  if (
+    previousValue === nextValue ||
+    !isWrappable(nextValue) ||
+    Array.isArray(previousValue) !== Array.isArray(nextValue) ||
+    (keyFn(previousValue) != null && keyFn(previousValue) !== keyFn(nextValue))
+  )
+    return;
+  if (childTarget[STORE_SHALLOW]) {
+    applyStateShallow(nextValue, childTarget);
+  } else if (childTarget[STORE_OVERRIDE] || childTarget[STORE_OPTIMISTIC_OVERRIDE]) {
+    applyStateSlow(nextValue, childTarget, keyFn);
+  } else {
+    applyStateFast(nextValue, childTarget, keyFn);
   }
 }
 // Dispatcher: every applyState call (including recursion) checks for the
@@ -4665,18 +4804,101 @@ function applyState(next, state, keyFn) {
   next = unwrap(next);
   const target = state?.[$TARGET];
   if (!target) return;
-  if (target[STORE_OVERRIDE] || target[STORE_OPTIMISTIC_OVERRIDE]) {
+  if (target[STORE_SHALLOW]) {
+    applyStateShallow(next, target);
+  } else if (target[STORE_OVERRIDE] || target[STORE_OPTIMISTIC_OVERRIDE]) {
     applyStateSlow(next, target, keyFn);
   } else {
     applyStateFast(next, target, keyFn);
   }
 }
+// Shallow boundary diff: the target's own keys are reactive, its values are
+// raw records replaced by reference — no recursion, no wrapping. Arrays merge
+// positionally (below a shallow boundary the VALUE is the identity; keyed
+// row identity belongs to the consumer, e.g. <For keyed>). Incoming
+// wrappables are sticky-marked raw so they present raw through every store.
+// One pass over a shallow target's node record: replace changed slots with
+// raw next values, null out slots absent from next. Returns whether anything
+// differed.
+function shallowDiffNodes(nodes, next, prevAt, skipLength) {
+  let changed = false;
+  for (const key in nodes) {
+    if (skipLength && key === "length") continue;
+    if (key in next) {
+      const v = next[key];
+      if (v !== prevAt(key)) {
+        changed = true;
+        setSignal(nodes[key], v);
+      }
+    } else {
+      changed = true;
+      setSignal(nodes[key], undefined);
+    }
+  }
+  return changed;
+}
+function applyStateShallow(next, target, keyFn) {
+  const previous = target[STORE_VALUE];
+  const override = target[STORE_OVERRIDE];
+  const optOverride = target[STORE_OPTIMISTIC_OVERRIDE];
+  if (next === previous && !override && !optOverride) return;
+  // Setter-staged writes fold into the diff: previous values resolve through
+  // the override layers (so a replaced slot compares against what readers
+  // saw), and the regular override clears with the swap — reconcile makes
+  // `next` the authoritative base, same as the deep slow path.
+  const prevAt = key => {
+    const v = getOverrideValue(previous, override, key, optOverride);
+    return v === $DELETED ? undefined : v;
+  };
+  target[STORE_OVERRIDE] = undefined;
+  const fam = target[STORE_LOOKUP];
+  fam !== undefined ? fam.set(next, target[$PROXY]) : storeLookup.set(next, target);
+  target[STORE_VALUE] = next;
+  markRawIngest(next);
+  const nodes = target[STORE_NODE];
+  const tracked = nodes && nodes[$TRACK];
+  let changed = false;
+  if (Array.isArray(previous)) {
+    const prevLength = override?.length ?? optOverride?.length ?? previous.length;
+    if (nodes) {
+      changed = shallowDiffNodes(nodes, next, prevAt, true);
+      if (nodes.length && prevLength !== next.length) setSignal(nodes.length, next.length);
+    }
+    if (!changed && (tracked || target[STORE_HAS])) {
+      // Slots without nodes still feed $TRACK enumerators / `in` probes.
+      if (prevLength !== next.length) changed = true;
+      else {
+        for (let i = 0, len = next.length; i < len; i++) {
+          if (prevAt(i) !== next[i]) {
+            changed = true;
+            break;
+          }
+        }
+      }
+    }
+  } else {
+    if (nodes) {
+      changed = shallowDiffNodes(nodes, next, prevAt, false);
+    }
+    if (!changed && (tracked || target[STORE_HAS])) changed = true;
+  }
+  let has = target[STORE_HAS];
+  if (has) {
+    for (const key in has) {
+      setSignal(has[key], key in next);
+    }
+  }
+  changed && notifySelf(target);
+}
 function applyStateFast(next, target, keyFn) {
   const previous = target[STORE_VALUE];
   if (next === previous) return;
   const arrayNodes = target[STORE_NODE];
   // swap
-  (target[STORE_LOOKUP] || storeLookup).set(next, target[$PROXY]);
+  {
+    const fam = target[STORE_LOOKUP];
+    fam !== undefined ? fam.set(next, target[$PROXY]) : storeLookup.set(next, target);
+  }
   target[STORE_VALUE] = next;
   // merge
   if (Array.isArray(previous)) {
@@ -4689,10 +4911,22 @@ function applyStateFast(next, target, keyFn) {
         start < end && keyedMatch((item = previous[start]), next[start], keyFn);
         start++
       ) {
-        isWrappable(item) &&
-          isWrappable(next[start]) &&
-          applyState(next[start], wrap(item, target), keyFn);
+        // keyedMatch established both sides wrappable unless they're the
+        // SAME reference — and an identical slot is a guaranteed no-op
+        // (the child's STORE_VALUE tracks the previous graph), so skip
+        // the recursion dispatch entirely. Raw-marked values are leaves:
+        // replace the slot node instead of recursing.
+        if (item !== next[start]) {
+          if (rawValuesUsed && (isRawValue(item) || isRawValue(next[start]))) {
+            arrayNodes?.[start] && setSignal(arrayNodes[start], wrapValue(next[start], target));
+          } else applyStateChild(next[start], item, target, keyFn);
+        }
       }
+      // Every position key-matched at equal length (the steady-state shape
+      // of a polling tick): membership, length, and order are unchanged —
+      // nothing below could do observable work, so skip the staging
+      // allocations and membership sync outright.
+      if (start === next.length && start === prevLength) return;
       const temp = new Array(next.length),
         newIndices = new Map();
       for (
@@ -4745,9 +4979,13 @@ function applyStateFast(next, target, keyFn) {
     } else if (next.length) {
       for (let i = 0, len = next.length; i < len; i++) {
         const item = previous[i];
-        if (isWrappable(item) && isWrappable(next[i]))
-          applyState(next[i], wrap(item, target), keyFn);
-        else {
+        if (
+          isWrappable(item) &&
+          isWrappable(next[i]) &&
+          !(rawValuesUsed && (isRawValue(item) || isRawValue(next[i])))
+        ) {
+          if (item !== next[i]) applyStateChild(next[i], item, target, keyFn);
+        } else {
           if (item !== next[i]) changed = true;
           arrayNodes?.[i] && setSignal(arrayNodes[i], wrapValue(next[i], target));
         }
@@ -4766,17 +5004,54 @@ function applyStateFast(next, target, keyFn) {
   let tracked;
   if (nodes) {
     tracked = nodes[$TRACK];
+    // The per-key body is duplicated across both loops on purpose: this is
+    // the hottest object-diff site and a shared helper costs a per-key call
+    // in instruction counts (CodSpeed regressed ~7% on deep-tree reconciles
+    // with the extracted form).
     if (tracked || symbolKeyedRecords.has(nodes)) {
       const keys = tracked ? getAllKeys(previous, undefined, next) : nodeKeys(nodes);
       for (let i = 0, len = keys.length; i < len; i++) {
-        diffNodeKey(keys[i], nodes, previous, next, target, tracked, keyFn);
+        const key = keys[i];
+        const node = nodes[key];
+        const previousValue = unwrap(previous[key]);
+        const nextValue = unwrap(next[key]);
+        if (previousValue === nextValue) continue;
+        if (
+          !previousValue ||
+          !isWrappable(previousValue) ||
+          !isWrappable(nextValue) ||
+          // Raw-marked values are leaves replaced by reference — a "wrappable
+          // pair" is only recursable when both sides are actual store children.
+          (rawValuesUsed && (isRawValue(previousValue) || isRawValue(nextValue))) ||
+          Array.isArray(previousValue) !== Array.isArray(nextValue) ||
+          (keyFn(previousValue) != null && keyFn(previousValue) !== keyFn(nextValue))
+        ) {
+          tracked && setSignal(tracked, void 0);
+          node && setSignal(node, isWrappable(nextValue) ? wrap(nextValue, target) : nextValue);
+        } else applyStateChild(nextValue, previousValue, target, keyFn);
       }
     } else {
       // Untracked, string-only node records (the overwhelmingly common case)
       // iterate in place — nodeKeys() allocated a fresh key array per object
       // per pass, which dominates allocation on large-graph reconciles.
       for (const key in nodes) {
-        diffNodeKey(key, nodes, previous, next, target, tracked, keyFn);
+        const node = nodes[key];
+        const previousValue = unwrap(previous[key]);
+        const nextValue = unwrap(next[key]);
+        if (previousValue === nextValue) continue;
+        if (
+          !previousValue ||
+          !isWrappable(previousValue) ||
+          !isWrappable(nextValue) ||
+          // Raw-marked values are leaves replaced by reference — a "wrappable
+          // pair" is only recursable when both sides are actual store children.
+          (rawValuesUsed && (isRawValue(previousValue) || isRawValue(nextValue))) ||
+          Array.isArray(previousValue) !== Array.isArray(nextValue) ||
+          (keyFn(previousValue) != null && keyFn(previousValue) !== keyFn(nextValue))
+        ) {
+          tracked && setSignal(tracked, void 0);
+          node && setSignal(node, isWrappable(nextValue) ? wrap(nextValue, target) : nextValue);
+        } else applyStateChild(nextValue, previousValue, target, keyFn);
       }
     }
   }
@@ -4790,31 +5065,16 @@ function applyStateFast(next, target, keyFn) {
     }
   }
 }
-// One node-key step of the fast object diff — shared by the array-iterating
-// (tracked / symbol-keyed) and for-in (plain) loops in applyStateFast.
-function diffNodeKey(key, nodes, previous, next, target, tracked, keyFn) {
-  const node = nodes[key];
-  const previousValue = unwrap(previous[key]);
-  let nextValue = unwrap(next[key]);
-  if (previousValue === nextValue) return;
-  if (
-    !previousValue ||
-    !isWrappable(previousValue) ||
-    !isWrappable(nextValue) ||
-    Array.isArray(previousValue) !== Array.isArray(nextValue) ||
-    (keyFn(previousValue) != null && keyFn(previousValue) !== keyFn(nextValue))
-  ) {
-    tracked && setSignal(tracked, void 0);
-    node && setSignal(node, isWrappable(nextValue) ? wrap(nextValue, target) : nextValue);
-  } else applyState(nextValue, wrap(previousValue, target), keyFn);
-}
 function applyStateSlow(next, target, keyFn) {
   const previous = target[STORE_VALUE];
   const override = target[STORE_OVERRIDE];
   const optOverride = target[STORE_OPTIMISTIC_OVERRIDE];
   let nodes = target[STORE_NODE];
   // swap
-  (target[STORE_LOOKUP] || storeLookup).set(next, target[$PROXY]);
+  {
+    const fam = target[STORE_LOOKUP];
+    fam !== undefined ? fam.set(next, target[$PROXY]) : storeLookup.set(next, target);
+  }
   target[STORE_VALUE] = next;
   target[STORE_OVERRIDE] = undefined;
   // merge
@@ -4833,9 +5093,11 @@ function applyStateSlow(next, target, keyFn) {
         );
         start++
       ) {
-        isWrappable(item) &&
-          isWrappable(next[start]) &&
-          applyState(next[start], wrap(item, target), keyFn);
+        if (isWrappable(item) && isWrappable(next[start]) && item !== next[start]) {
+          if (rawValuesUsed && (isRawValue(item) || isRawValue(next[start]))) {
+            nodes?.[start] && setSignal(nodes[start], wrapValue(next[start], target));
+          } else applyState(next[start], wrap(item, target), keyFn);
+        }
       }
       const temp = new Array(next.length),
         newIndices = new Map();
@@ -4894,9 +5156,13 @@ function applyStateSlow(next, target, keyFn) {
     } else if (next.length) {
       for (let i = 0, len = next.length; i < len; i++) {
         const item = getOverrideValue(previous, override, i, optOverride);
-        if (isWrappable(item) && isWrappable(next[i]))
-          applyState(next[i], wrap(item, target), keyFn);
-        else {
+        if (
+          isWrappable(item) &&
+          isWrappable(next[i]) &&
+          !(rawValuesUsed && (isRawValue(item) || isRawValue(next[i])))
+        ) {
+          if (item !== next[i]) applyState(next[i], wrap(item, target), keyFn);
+        } else {
           if (item !== next[i]) changed = true;
           nodes?.[i] && setSignal(nodes[i], wrapValue(next[i], target));
         }
@@ -4926,6 +5192,7 @@ function applyStateSlow(next, target, keyFn) {
         !previousValue ||
         !isWrappable(previousValue) ||
         !isWrappable(nextValue) ||
+        (rawValuesUsed && (isRawValue(previousValue) || isRawValue(nextValue))) ||
         Array.isArray(previousValue) !== Array.isArray(nextValue) ||
         (keyFn(previousValue) != null && keyFn(previousValue) !== keyFn(nextValue))
       ) {
@@ -4997,9 +5264,16 @@ function reconcile(value, key = "id") {
 function createProjectionInternal(fn, seed, options) {
   let node;
   const wrappedMap = new WeakMap();
+  // A shallow projection's children are raw and never wrapped, so the
+  // wrapper only ever runs for the root — flagging unconditionally is safe.
+  const shallow = !!options?.shallow;
   const wrapper = s => {
     s[STORE_WRAP] = wrapProjection;
     s[STORE_LOOKUP] = wrappedMap;
+    if (shallow) {
+      s[STORE_SHALLOW] = true;
+      markRawIngest(s[STORE_VALUE]);
+    }
     Object.defineProperty(s, STORE_FIREWALL, {
       get() {
         return node;
@@ -5186,7 +5460,8 @@ const STORE_VALUE = "v",
   STORE_OPTIMISTIC = "p",
   STORE_OPTIMISTIC_OWNERS = "t",
   STORE_PARENT = "u",
-  STORE_DESC = "d";
+  STORE_DESC = "d",
+  STORE_SHALLOW = "s";
 const STORE_SELF_PENDING = Symbol("STORE_SELF_PENDING");
 // Every StoreNode field is initialized up front, in one fixed order, so all
 // targets share a single hidden class. The traps and reconcile read these
@@ -5208,6 +5483,7 @@ function initStoreFields(newTarget) {
   newTarget[STORE_SNAPSHOT_PROPS] = undefined;
   newTarget[STORE_PARENT] = undefined;
   newTarget[STORE_DESC] = undefined;
+  newTarget[STORE_SHALLOW] = undefined;
   newTarget[$PROXY] = null;
 }
 function createStoreProxy(value, traps = storeTraps, extend) {
@@ -5228,24 +5504,98 @@ function createStoreProxy(value, traps = storeTraps, extend) {
   extend && extend(newTarget);
   return (newTarget[$PROXY] = new Proxy(newTarget, traps));
 }
+// The global lookup maps raw value -> StoreNode TARGET (not proxy): reconcile
+// and the unwrap/snapshot walks resolve targets through it constantly, and a
+// target hit is a plain field read away from its proxy while a proxy hit
+// costs a trap to get back to the target. Per-family STORE_LOOKUP maps
+// (projections/optimistic) still map raw -> proxy — their wrap functions own
+// that contract — so mixed-lookup consumers resolve through lookupTarget().
 const storeLookup = new WeakMap();
 // Node records that hold at least one user (non-`$TRACK`) symbol-keyed node.
 // Lets reconcile enumerate symbols only for records that need it (#2851).
 const symbolKeyedRecords = new WeakSet();
+function lookupTarget(value, lookup) {
+  if (lookup !== undefined && lookup !== storeLookup) {
+    const p = lookup.get(value);
+    if (p !== undefined) return p[$TARGET];
+  }
+  return storeLookup.get(value);
+}
+// Values marked raw never acquire a proxy identity: wrap() serves them as-is
+// everywhere — deep stores hold them as leaf values replaced by reference.
+// Once raw, always raw (identity stays single, just unwrapped). Consulted
+// only on wrap-creation and ingest paths; reads never touch it.
+const rawValues = new WeakSet();
+/**
+ * Marks a value as raw: no store will ever wrap it — every store presents it
+ * as-is, tracked by reference at whatever slot holds it and updated by
+ * replacement. Useful for class instances and external objects (editors,
+ * scene graphs, Maps) and for record-shaped data updated wholesale. Sticky
+ * for the value's lifetime.
+ */
+// Flipped on the first mark and exported as a LIVE binding: reconcile
+// consults it on every recursable pair, and importing the boolean directly
+// lets those sites skip even the function call when no shallow store or raw
+// mark exists anywhere in the app.
+let rawValuesUsed = false;
+function isRawValue(value) {
+  return rawValuesUsed && rawValues.has(value);
+}
+function markRawOne(v) {
+  if (isWrappable(v)) {
+    if (storeLookup.has(v))
+      throw new Error(
+        "shallow store: an ingested record is already tracked as a deep store — one value cannot present both wrapped and raw"
+      );
+    rawValuesUsed = true;
+    rawValues.add(v);
+  }
+}
+function markRawIngest(container) {
+  if (Array.isArray(container)) {
+    for (let i = 0, len = container.length; i < len; i++) markRawOne(container[i]);
+  } else {
+    for (const k in container) markRawOne(container[k]);
+  }
+}
 function wrap(value, target) {
+  // Raw is raw in every family: the mark must preempt family wrapping too,
+  // or a shallow projection/optimistic store would proxy its raw records.
+  if (rawValuesUsed && rawValues.has(value)) return value;
   if (target?.[STORE_WRAP]) {
     const p = target[STORE_WRAP](value, target);
     const t = p[$TARGET];
     if (t && !t[STORE_PARENT] && t !== target) t[STORE_PARENT] = target;
     return p;
   }
-  let p = value[$PROXY] || storeLookup.get(value);
+  const t = storeLookup.get(value);
+  if (t !== undefined) return t[$PROXY];
+  let p = value[$PROXY];
   if (!p) {
-    storeLookup.set(value, (p = createStoreProxy(value)));
-    if (target) p[$TARGET][STORE_PARENT] = target;
+    p = createStoreProxy(value);
+    const newTarget = p[$TARGET];
+    storeLookup.set(value, newTarget);
+    if (target) newTarget[STORE_PARENT] = target;
   }
   return p;
 }
+// Shallow store root: the target itself is fully reactive (per-key nodes,
+// membership, $TRACK); its values are served raw. Seed values are marked at
+// creation; reconcile and the set trap mark on ingest.
+function wrapShallow(value) {
+  const existing = storeLookup.get(value);
+  if (existing !== undefined) {
+    if (existing[STORE_SHALLOW]) return existing[$PROXY];
+    throw new Error("createStore({ shallow }): value is already tracked as a deep store");
+  }
+  if (value[$TARGET]) throw new Error("createStore({ shallow }): value is already a store proxy");
+  const p = createStoreProxy(value);
+  const newTarget = p[$TARGET];
+  newTarget[STORE_SHALLOW] = true;
+  storeLookup.set(value, newTarget);
+  markRawIngest(value);
+  return p;
+}
 function isWrappable(obj) {
   if (obj == null || typeof obj !== "object" || Object.isFrozen(obj)) return false;
   // Dynamic Node check (kept dynamic so test/SSR overrides of `globalThis.Node`
@@ -5260,7 +5610,7 @@ function writeOnly(proxy) {
   return writeOverride || !!Writing?.has(proxy);
 }
 function unwrapStoreValue(value, map, lookup) {
-  const target = value?.[$TARGET] || lookup?.get(value)?.[$TARGET];
+  const target = value?.[$TARGET] || lookupTarget(value, lookup);
   if (!target) return value;
   const override = target[STORE_OVERRIDE];
   if (!override) return target[STORE_VALUE];
@@ -5447,7 +5797,7 @@ function walkAffectsScope(
   visited
 ) {
   if (!isWrappable(value)) return;
-  const target = value[$TARGET] || (lookup ?? storeLookup).get(value)?.[$TARGET];
+  const target = value[$TARGET] || lookupTarget(value, lookup);
   const raw = target ? target[STORE_VALUE] : value;
   if (visited.has(raw)) return;
   visited.add(raw);
@@ -5814,8 +6164,25 @@ const storeTraps = {
       const nodes = target[STORE_NODE];
       const node = nodes && nodes[property];
       if (node !== undefined && target[STORE_VALUE][$TARGET] === undefined) {
-        let value = read(node);
+        // readNodeFast is read()'s plain-signal fast path hoisted over the
+        // call; READ_SLOW means a global read window (latest/pending-check/
+        // transition/lane/snapshot capture) or a node layer is active, and
+        // only then does the full read() resolution have anything to do.
+        let value = readNodeFast(node);
+        if (value === READ_SLOW) value = read(node);
         if (value === $DELETED) value = undefined;
+        // Every node-writing site wraps wrappables before setSignal (see the
+        // dev assertion below), so re-wrapping on read is redundant — except
+        // during snapshot capture, where read() can surface a raw captured
+        // value seeded from snapshot props.
+        if (!snapshotCaptureActive) {
+          if (isWrappable(value) && wrap(value, target) !== value) {
+            throw new Error(
+              "store node invariant violated: node held an unwrapped wrappable value"
+            );
+          }
+          return value;
+        }
         return isWrappable(value) ? wrap(value, target) : value;
       }
     }
@@ -5859,6 +6226,11 @@ const storeTraps = {
         tracked && (overridden || !proxySource) ? visibleNodeValue(tracked) : storeValue[property];
       value === $DELETED && (value = undefined);
       if (!isWrappable(value)) return value;
+      // Shallow boundary: records are replaced, never edited in place. Reads
+      // inside a setter serve the raw so read-then-replace, filter/pop and
+      // projection derives all work; in-place mutation of a raw is inert by
+      // construction — the same contract as a markRaw child in a deep store.
+      if (target[STORE_SHALLOW]) return value;
       const wrapped = wrap(value, target);
       Writing?.add(wrapped);
       return wrapped;
@@ -5944,6 +6316,7 @@ const storeTraps = {
           ? prevLayer[property] !== $DELETED
           : property in target[STORE_VALUE];
         const value = unwrapStoreValue(rawValue);
+        if (target[STORE_SHALLOW] && isWrappable(value)) rawValues.add(value);
         // Symbol-keyed writes on arrays are metadata, not index writes — never run
         // them through the numeric index/length machinery (`parseInt` on a symbol
         // throws). #2769
@@ -6160,7 +6533,11 @@ function storeSetter(store, fn) {
 }
 function createStore(first, second, options) {
   const derived = typeof first === "function",
-    wrappedStore = derived ? createProjectionInternal(first, second, options).store : wrap(first);
+    wrappedStore = derived
+      ? createProjectionInternal(first, second, options).store
+      : second?.shallow
+        ? wrapShallow(first)
+        : wrap(first);
   registerGraph(wrappedStore, getOwner());
   return [
     wrappedStore,
@@ -6324,6 +6701,8 @@ function createOptimisticStore(first, second, options) {
   installOptimisticEngine();
   GlobalQueue._clearOptimisticStores ||= clearOptimisticStores;
   const derived = typeof first === "function";
+  // Plain form: the second slot carries options.
+  if (!derived && options === undefined) options = second;
   const initialValue = derived ? second : first;
   const fn = derived ? first : undefined;
   // Create optimistic projection store
@@ -6425,9 +6804,14 @@ function clearOptimisticOverride(target, completing) {
 function createOptimisticProjectionInternal(fn, initialValue, options) {
   let node;
   const wrappedMap = new WeakMap();
+  const shallow = !!options?.shallow;
   const wrapper = s => {
     s[STORE_WRAP] = wrapProjection;
     s[STORE_LOOKUP] = wrappedMap;
+    if (shallow) {
+      s[STORE_SHALLOW] = true;
+      markRawIngest(s[STORE_VALUE]);
+    }
     s[STORE_OPTIMISTIC] = true; // Mark as optimistic store
     Object.defineProperty(s, STORE_FIREWALL, {
       get() {
@@ -6596,7 +6980,7 @@ function snapshotImpl(item, track, map, lookup) {
   if (!isWrappable(item)) return item;
   if (map && map.has(item)) return map.get(item);
   if (!map) map = new Map();
-  if ((target = item[$TARGET] || lookup?.get(item)?.[$TARGET])) {
+  if ((target = item[$TARGET] || lookupTarget(item, lookup))) {
     if (track) {
       trackSelf(target, $TRACK);
       // A tracked walk reads THROUGH the record without touching the proxy
@@ -6634,7 +7018,7 @@ function snapshotImpl(item, track, map, lookup) {
     for (let i = 0; i < len; i++) {
       v = override && i in override ? override[i] : item[i];
       if (v === $DELETED) continue;
-      if (track && isWrappable(v)) wrap(v, target);
+      if (track && isWrappable(v) && !(rawValuesUsed && isRawValue(v))) wrap(v, target);
       if ((unwrapped = snapshotImpl(v, track, map, lookup)) !== v || result) {
         if (!result) map.set(item, (result = [...item]));
         result[i] = unwrapped;
@@ -6648,7 +7032,7 @@ function snapshotImpl(item, track, map, lookup) {
       const desc = getPropertyDescriptor(item, override, prop);
       if (!desc || desc.get) continue;
       v = override && prop in override ? override[prop] : item[prop];
-      if (track && isWrappable(v)) wrap(v, target);
+      if (track && isWrappable(v) && !(rawValuesUsed && isRawValue(v))) wrap(v, target);
       unwrapped = snapshotImpl(v, track, map, lookup);
       if (unwrapped !== v || result) {
         if (!result) map.set(item, (result = Object.assign([...item], item)));
@@ -6670,7 +7054,7 @@ function snapshotImpl(item, track, map, lookup) {
       const desc = Object.getOwnPropertyDescriptor(item, prop);
       if (desc.get) continue;
       v = desc.value;
-      if (track && isWrappable(v)) wrap(v, target);
+      if (track && isWrappable(v) && !(rawValuesUsed && isRawValue(v))) wrap(v, target);
       if ((unwrapped = snapshotImpl(v, track, map, lookup)) !== v || result) {
         if (!result) {
           result = Object.create(Object.getPrototypeOf(item));
@@ -6688,7 +7072,7 @@ function snapshotImpl(item, track, map, lookup) {
       const desc = getPropertyDescriptor(item, override, prop);
       if (desc.get) continue;
       v = prop in override ? override[prop] : item[prop];
-      if (track && isWrappable(v)) wrap(v, target);
+      if (track && isWrappable(v) && !(rawValuesUsed && isRawValue(v))) wrap(v, target);
       if ((unwrapped = snapshotImpl(v, track, map, lookup)) !== item[prop] || result) {
         if (!result) {
           result = Object.create(Object.getPrototypeOf(item));