teamplay 0.4.0-alpha.3 → 0.4.0-alpha.31

package/orm/Compat/README.md

@@ -94,9 +94,11 @@ $.users.user1.name.parent(2)   // $.users
 Legacy path navigation. Accepts:
 - string with dot path (`'a.b.c'`)
 - integer index for arrays (`0`)
+- multiple path segments (`'a', 'b', 0`)
 
 ```js
 $.users.user1.at('profile.name')
+$.users.user1.at('profile', 'name')
 $.items.at(0)
 ```
 
@@ -106,6 +108,7 @@ Resolve a path from root, ignoring the current signal path.
 
 ```js
 $.users.user1.scope('users.user2')
+$.users.user1.scope('users', 'user2')
 ```
 
 ### ref(target) / ref(subpath, target)
@@ -171,6 +174,49 @@ $alias.get() === $user.get()       // false
 - No event emissions specific to refs.
 - No support for racer-style ref meta/options beyond the basic signature.
 
+### start(targetPath, ...deps, getter)
+
+Legacy computed binding API from Racer/StartupJS.
+Creates a reactive computation and writes its result into `targetPath`.
+Source of truth is root API (`$root.start(...)`), but non-root calls are supported as sugar:
+- `$scope.start('a.b', ...deps, getter)` → `$root.start('<scopePath>.a.b', ...deps, getter)`
+
+- `targetPath`: string path where computed value is written.
+- `deps`: dependencies used by `getter`.
+- `getter`: function called as `getter(...resolvedDeps)`.
+
+Dependency resolution:
+- Signal-like dep (`$doc`, `$session.user`) → `dep.get()`.
+- String dep (`'settings.theme'`) → `$root.get(dep)`.
+- Any other dep → passed as-is.
+
+```js
+$root.start('_virtual.lesson', $.lessons[lessonId], '_session.userId', (lesson, userId) => {
+  if (!lesson) return undefined
+  return { stageIds: lesson.stageIds, userId }
+})
+```
+
+Behavior:
+- Calling `start()` again for the same `targetPath` replaces previous reaction.
+- `undefined` result applies compat delete semantics at target path.
+- `null` result is stored as `null`.
+- Returns target signal.
+- If any dependency temporarily suspends (throws a Promise/thenable), compat skips the whole tick (getter is not called and target is not written).
+- If `getter` throws a Promise, compat skips that tick and retries on next reactive update.
+
+### stop(targetPath)
+
+Stops a computation created with `start(targetPath, ...)`.
+No-op if there is no active computation for the path.
+Source of truth is root API (`$root.stop(...)`), but non-root calls are supported as sugar:
+- `$scope.stop('a.b')` → `$root.stop('<scopePath>.a.b')`
+- `$scope.stop()` → `$root.stop('<scopePath>')`
+
+```js
+$root.stop('_virtual.lesson')
+```
+
 ### query(collection, query, options?)
 
 Creates a query signal **without** subscribing. Supports shorthand params:
@@ -236,6 +282,7 @@ Returns the current value and tracks reactivity.
 const name = $.users.user1.name.get()
 $root.get('$render.url')
 $user.get('profile.name')
+$user.get('profile', 'name')
 ```
 
 ### peek(subpath?)
@@ -245,6 +292,7 @@ Returns the current value **without** tracking reactivity.
 ```js
 const name = $.users.user1.name.peek()
 $user.peek('profile.name')
+$user.peek('profile', 'name')
 ```
 
 ### getCopy(subpath)
@@ -306,6 +354,20 @@ for (const $doc of $query) {
 }
 ```
 
+### Mutator Semantics (Core vs Compat)
+
+Compatibility mode intentionally aligns mutators with Racer. This differs from core `Signal` behavior.
+
+| API | Core (`Signal`) | Compat (`SignalCompat`) |
+| --- | --- | --- |
+| `set` | Uses deep-diff path (`dataTree.set` + internal `setDiffDeep`). | Path-targeted replace semantics, Racer-like. `undefined` keeps delete semantics. |
+| `setEach` | Not a special API in core mutators. | Per-key compat `set` (not `assign` merge/delete behavior). |
+| `setDiffDeep` | Deep-diff engine (`utils/setDiffDeep.js`). | Recursive Racer-like diff implemented via compat mutators (`set` / `del`) on nested paths. |
+| `setDiff` | N/A as compat shim. | Alias to compat `set` for both signatures: `setDiff(value)` and `setDiff(path, value)`. |
+
+Migration note: compat behavior is intentionally Racer-aligned and may differ from core mutators.
+Composite compat mutators (`setEach`, `setDiffDeep`) apply updates atomically for Teamplay-scheduled observers via the runtime batch scheduler.
+
 ### set(value) and set(path, value)
 
 `SignalCompat` accepts both:
@@ -315,7 +377,14 @@ $.users.user1.name.set('Alice')
 $.users.user1.set('profile.name', 'Alice')
 ```
 
-In compat mode, `set` replaces values at the target path.
+In compat mode, `set` replaces the value at the target path.
+- `set(path, null)` stores `null`.
+- `set(path, undefined)` applies current delete semantics.
+
+```js
+await $.users.user1.set('profile', { name: 'Ann', role: 'student' })
+await $.users.user1.set('profile', { name: 'Kate' }) // role is removed
+```
 
 ### setNull(path?, value)
 
@@ -327,26 +396,47 @@ $.config.setNull('theme', 'light')
 
 ### setDiffDeep(path?, value)
 
-Applies a diff-deep update (uses base `Signal.set` internally).
+Applies a recursive Racer-like diff using compat mutators (`set` / `del`) on subpaths.
+This is intentionally a compat implementation detail and differs from core deep-diff internals.
 
 ```js
-$.users.user1.setDiffDeep({ profile: { name: 'Alice' } })
+await $.users.user1.set({ profile: { name: 'Ann', role: 'student' } })
+await $.users.user1.setDiffDeep({ profile: { name: 'Kate' } }) // deep-diff path
 ```
 
 ### setDiff(path?, value)
 
-Alias for `set()` in compat. Accepts the same arguments and semantics.
+Alias for compat `set` in both forms:
+- `setDiff(value)` -> same as `set(value)`
+- `setDiff(path, value)` -> same as `set(path, value)`
 
 ```js
-$.users.user1.setDiff({ profile: { name: 'Alice' } })
+await $.users.user1.setDiff({ profile: { name: 'Kate' } })
+await $.users.user1.setDiff('profile', { name: 'Bob' })
 ```
 
 ### setEach(path?, object)
 
-Shorthand for assign. Sets or deletes fields from an object.
+Racer-like per-key set. `setEach` iterates keys and applies compat `set` for each key.
+- `setEach({ k: null })` stores `null`.
+- `setEach({ k: undefined })` applies current delete semantics.
 
 ```js
-$.users.user1.setEach({ name: 'Bob', age: 30 })
+await $.users.user1.setEach({ name: 'Bob', age: null })
+```
+
+### Null / Undefined Matrix (Compat)
+
+| Call | Result |
+| --- | --- |
+| `set(path, null)` | stores `null` at `path` |
+| `set(path, undefined)` | applies delete semantics at `path` |
+| `setEach({ k: null })` | stores `null` for `k` |
+| `setEach({ k: undefined })` | applies delete semantics for `k` |
+
+```js
+await $.users.user1.set('status', null) // status === null
+await $.users.user1.setEach({ status: undefined }) // status deleted
 ```
 
 ### assign(object)
@@ -672,10 +762,12 @@ This matches StartupJS and makes updates easy:
 $users[userId].name.set('New Name')
 ```
 
-`useQuery$` returns the collection signal as well:
+`useQuery$` returns the **query signal**:
 
 ```js
-const $users = useQuery$('users', { active: true })
+const $query = useQuery$('users', { active: true })
+const ids = $query.getIds()
+const docs = $query.get()
 ```
 
 If `query == null`, a warning is logged and `{ _id: '__NON_EXISTENT__' }` is used.
@@ -758,6 +850,8 @@ const Component = observer(() => {
 ```js
 const Component = observer(() => {
   const [users, $users] = useQuery('users', { active: true })
+  const $query = useQuery$('users', { active: true })
+  const ids = $query.getIds()
   return (
     <>
       {users.map(u => <div key={u._id}>{u.name}</div>)}

package/orm/Compat/SignalCompat.js

@@ -8,15 +8,14 @@ import {
   isPublicCollectionSignal,
   isPublicDocumentSignal
 } from '../SignalBase.js'
-import { getRoot } from '../Root.js'
+import { getRoot, ROOT } from '../Root.js'
 import { publicOnly, fetchOnly, setFetchOnly } from '../connection.js'
 import { docSubscriptions } from '../Doc.js'
 import { IS_QUERY, getQuerySignal, querySubscriptions } from '../Query.js'
 import { IS_AGGREGATION, aggregationSubscriptions, getAggregationSignal } from '../Aggregation.js'
-import { getIdFieldsForSegments, isIdFieldPath, normalizeIdFields } from '../idFields.js'
+import { getIdFieldsForSegments, isIdFieldPath, normalizeIdFields, isPlainObject } from '../idFields.js'
 import {
   setReplace as _setReplace,
-  setPublicDocReplace as _setPublicDocReplace,
   incrementPublic as _incrementPublic,
   arrayPush as _arrayPush,
   arrayUnshift as _arrayUnshift,
@@ -40,11 +39,17 @@ import {
 import { on as onCustomEvent, removeListener as removeCustomEventListener } from './eventsCompat.js'
 import { normalizePattern, onModelEvent, removeModelListener } from './modelEvents.js'
 import { setRefLink, removeRefLink } from './refRegistry.js'
+import { REF_TARGET, resolveRefSignalSafe } from './refFallback.js'
+import { runInBatch } from '../batchScheduler.js'
 
 class SignalCompat extends Signal {
   static ID_FIELDS = ['_id', 'id']
   static [GETTERS] = [...DEFAULT_GETTERS, 'getCopy', 'getDeepCopy']
 
+  get root () {
+    return this.scope()
+  }
+
   path (subpath) {
     if (arguments.length > 1) throw Error('Signal.path() expects a single argument')
     if (arguments.length === 0) return super.path()
@@ -54,8 +59,9 @@ class SignalCompat extends Signal {
   }
 
   at (subpath) {
-    if (arguments.length > 1) throw Error('Signal.at() expects a single argument')
-    const segments = parseAtSubpath(subpath, arguments.length, 'Signal.at()')
+    const segments = arguments.length > 1
+      ? parseAtSegments(arguments, 'Signal.at()')
+      : parseAtSubpath(subpath, arguments.length, 'Signal.at()')
     if (segments.length === 0) return this
     let $cursor = this
     for (const segment of segments) {
@@ -118,8 +124,18 @@ class SignalCompat extends Signal {
   }
 
   get () {
-    if (arguments.length > 1) throw Error('Signal.get() expects zero or one argument')
+    if (arguments.length > 1) {
+      const segments = parseAtSegments(arguments, 'Signal.get()')
+      const $base = resolveRefSignal(this)
+      const $target = resolveSignal($base, segments)
+      return Signal.prototype.get.call($target)
+    }
     if (arguments.length === 1) {
+      if (arguments[0] == null) {
+        const $target = resolveRefSignal(this)
+        if ($target !== this) return Signal.prototype.get.apply($target, [])
+        return Signal.prototype.get.apply(this, [])
+      }
       const segments = parseAtSubpath(arguments[0], 1, 'Signal.get()')
       const $base = resolveRefSignal(this)
       const $target = resolveSignal($base, segments)
@@ -131,8 +147,18 @@ class SignalCompat extends Signal {
   }
 
   peek () {
-    if (arguments.length > 1) throw Error('Signal.peek() expects zero or one argument')
+    if (arguments.length > 1) {
+      const segments = parseAtSegments(arguments, 'Signal.peek()')
+      const $base = resolveRefSignal(this)
+      const $target = resolveSignal($base, segments)
+      return Signal.prototype.peek.call($target)
+    }
     if (arguments.length === 1) {
+      if (arguments[0] == null) {
+        const $target = resolveRefSignal(this)
+        if ($target !== this) return Signal.prototype.peek.apply($target, [])
+        return Signal.prototype.peek.apply(this, [])
+      }
       const segments = parseAtSubpath(arguments[0], 1, 'Signal.peek()')
       const $base = resolveRefSignal(this)
       const $target = resolveSignal($base, segments)
@@ -154,7 +180,24 @@ class SignalCompat extends Signal {
       value = path
     }
     const $target = resolveSignal(this, segments)
-    return Signal.prototype.set.call($target, value)
+    if (value === undefined) return Signal.prototype.set.call($target, value)
+    return setReplaceOnSignal($target, value)
+  }
+
+  async add (collectionOrValue, value) {
+    const isRoot = this[SEGMENTS].length === 0
+    const isRootCollectionCall = isRoot && typeof collectionOrValue === 'string'
+
+    if (isRootCollectionCall) {
+      if (arguments.length !== 2) throw Error('Signal.add() expects (collection, object)')
+      if (!value || typeof value !== 'object') throw Error('Signal.add() expects an object argument')
+      const $root = getRoot(this) || this
+      const $collection = resolveSignal($root, [collectionOrValue])
+      return $collection.add(value)
+    }
+
+    if (arguments.length > 1) throw Error('Signal.add() expects a single argument')
+    return Signal.prototype.add.call(this, collectionOrValue)
   }
 
   async setNull (path, value) {
@@ -183,7 +226,7 @@ class SignalCompat extends Signal {
       value = path
     }
     const $target = resolveSignal(this, segments)
-    return Signal.prototype.set.call($target, value)
+    return runInBatch(() => setDiffDeepOnSignal($target, value))
   }
 
   async setDiff (path, value) {
@@ -191,7 +234,7 @@ class SignalCompat extends Signal {
     if (forwarded) return forwarded
     if (arguments.length > 2) throw Error('Signal.setDiff() expects one or two arguments')
     if (arguments.length === 1) {
-      return Signal.prototype.set.call(this, path)
+      return this.set(path)
     }
     return this.set(path, value)
   }
@@ -207,7 +250,17 @@ class SignalCompat extends Signal {
       object = path
     }
     const $target = resolveSignal(this, segments)
-    return Signal.prototype.assign.call($target, object)
+    if (!object) return
+    if (typeof object !== 'object') {
+      throw Error('Signal.setEach() expects an object argument, got: ' + typeof object)
+    }
+    return runInBatch(async () => {
+      const promises = []
+      for (const key of Object.keys(object)) {
+        promises.push(SignalCompat.prototype.set.call($target[key], object[key]))
+      }
+      await Promise.all(promises)
+    })
   }
 
   async del (path) {
@@ -509,11 +562,11 @@ class SignalCompat extends Signal {
   }
 
   scope (path) {
-    if (arguments.length > 1) throw Error('Signal.scope() expects a single argument')
     const $root = getRoot(this) || this
     if (arguments.length === 0) return $root
-    if (typeof path !== 'string') throw Error('Signal.scope() expects a string argument')
-    const segments = path.split('.').filter(Boolean)
+    const segments = arguments.length > 1
+      ? parseAtSegments(arguments, 'Signal.scope()')
+      : parseAtSubpath(path, arguments.length, 'Signal.scope()')
     if (segments.length === 0) return $root
     let $cursor = $root
     for (const segment of segments) {
@@ -524,7 +577,6 @@ class SignalCompat extends Signal {
 }
 
 const REFS = Symbol('compat refs')
-const REF_TARGET = Symbol('compat ref target')
 
 function getRefStore ($signal) {
   const $root = getRoot($signal) || $signal
@@ -559,14 +611,7 @@ function trackDeep (value, seen = new Set()) {
 }
 
 function resolveRefSignal ($signal) {
-  let current = $signal
-  const seen = new Set()
-  while (current && current[REF_TARGET]) {
-    if (seen.has(current)) break
-    seen.add(current)
-    current = current[REF_TARGET]
-  }
-  return current
+  return resolveRefSignalSafe($signal) || $signal
 }
 
 function forwardRef ($signal, methodName, args) {
@@ -583,6 +628,10 @@ function isSignalLike (value) {
   return value && typeof value.path === 'function' && typeof value.get === 'function'
 }
 
+function isReactLike (value) {
+  return !!(value && typeof value === 'object' && typeof value.$$typeof === 'symbol')
+}
+
 function resolveRefTarget ($signal, target, methodName) {
   if (isSignalLike(target)) return target
   if (typeof target === 'string') {
@@ -600,6 +649,23 @@ function parseAtSubpath (subpath, argsLength, methodName) {
   throw Error(`${methodName} expects a string or integer argument`)
 }
 
+function parseAtSegments (args, methodName) {
+  const segments = []
+  for (const arg of Array.from(args)) {
+    if (typeof arg === 'string') {
+      const parts = arg.split('.').filter(Boolean)
+      segments.push(...parts)
+      continue
+    }
+    if (typeof arg === 'number' && Number.isFinite(arg) && Number.isInteger(arg)) {
+      segments.push(arg)
+      continue
+    }
+    throw Error(`${methodName} expects string or integer path segments`)
+  }
+  return segments
+}
+
 function resolveSignal ($signal, segments) {
   let $cursor = $signal
   for (const segment of segments) {
@@ -608,6 +674,89 @@ function resolveSignal ($signal, segments) {
   return $cursor
 }
 
+async function setDiffDeepOnSignal ($target, value) {
+  if ($target[SEGMENTS].length === 0) throw Error('Can\'t set the root signal data')
+  const before = $target.get()
+  await diffDeepCompat($target, before, value)
+}
+
+async function diffDeepCompat ($signal, before, after) {
+  if (before === after) return
+
+  if (Array.isArray(before) && Array.isArray(after)) {
+    if (deepEqualCompat(before, after)) return
+    const changedIndexes = getChangedArrayIndexes(before, after)
+    if (before.length === after.length && changedIndexes.length === 1) {
+      const index = changedIndexes[0]
+      await diffDeepCompat(getChildSignal($signal, index), before[index], after[index])
+      return
+    }
+    await SignalCompat.prototype.set.call($signal, after)
+    return
+  }
+
+  if (isDiffableObject(before, after)) {
+    for (const key of Object.keys(before)) {
+      if (Object.prototype.hasOwnProperty.call(after, key)) continue
+      await SignalCompat.prototype.del.call(getChildSignal($signal, key))
+    }
+    for (const key of Object.keys(after)) {
+      await diffDeepCompat(getChildSignal($signal, key), before[key], after[key])
+    }
+    return
+  }
+
+  await SignalCompat.prototype.set.call($signal, after)
+}
+
+function isDiffableObject (before, after) {
+  if (!isPlainObject(before) || !isPlainObject(after)) return false
+  if (isReactLike(before) || isReactLike(after)) return false
+  return true
+}
+
+function getChangedArrayIndexes (before, after) {
+  if (!Array.isArray(before) || !Array.isArray(after)) return []
+  const maxLength = Math.max(before.length, after.length)
+  const changed = []
+  for (let i = 0; i < maxLength; i++) {
+    if (!deepEqualCompat(before[i], after[i])) changed.push(i)
+  }
+  return changed
+}
+
+function getChildSignal ($parent, key) {
+  const $child = new SignalCompat([...$parent[SEGMENTS], key])
+  const $root = getRoot($parent)
+  if ($root) $child[ROOT] = $root
+  return $child
+}
+
+function deepEqualCompat (left, right) {
+  if (left === right) return true
+  if (left == null || right == null) return false
+  if (typeof left !== 'object' || typeof right !== 'object') return false
+  if (Array.isArray(left) !== Array.isArray(right)) return false
+
+  if (Array.isArray(left)) {
+    if (left.length !== right.length) return false
+    for (let i = 0; i < left.length; i++) {
+      if (!deepEqualCompat(left[i], right[i])) return false
+    }
+    return true
+  }
+
+  if (!isPlainObject(left) || !isPlainObject(right)) return false
+  const leftKeys = Object.keys(left)
+  const rightKeys = Object.keys(right)
+  if (leftKeys.length !== rightKeys.length) return false
+  for (const key of leftKeys) {
+    if (!Object.prototype.hasOwnProperty.call(right, key)) return false
+    if (!deepEqualCompat(left[key], right[key])) return false
+  }
+  return true
+}
+
 function getSignalValueAt ($signal, segments) {
   const $target = resolveSignal($signal, segments)
   return $target.get()
@@ -622,7 +771,7 @@ async function setReplaceOnSignal ($signal, value) {
     value = normalizeIdFields(value, idFields, segments[1])
   }
   if (isPublicCollection(segments[0])) {
-    return _setPublicDocReplace(segments, value)
+    return Signal.prototype.set.call($signal, value)
   }
   if (publicOnly) throw Error(ERRORS.publicOnly)
   return _setReplace(segments, value)

package/orm/Compat/hooksCompat.js

@@ -1,6 +1,7 @@
 import { getRootSignal, GLOBAL_ROOT_ID } from '../Root.js'
 import useSub, { useAsyncSub } from '../../react/useSub.js'
 import universal$ from '../../react/universal$.js'
+import * as promiseBatcher from '../../react/promiseBatcher.js'
 
 const $root = getRootSignal({ rootId: GLOBAL_ROOT_ID, rootFunction: universal$ })
 
@@ -72,8 +73,10 @@ export function usePage (path) {
   return useLocal(prefixLocalPath('_page', path))
 }
 
-// Placeholder for startupjs batching API. No-op in teamplay.
-export function useBatch () {}
+export function useBatch () {
+  const promise = promiseBatcher.getPromiseAll()
+  if (promise) throw promise
+}
 
 export function useDoc$ (collection, id, options) {
   const $doc = getDocSignal(collection, id, 'useDoc')
@@ -86,13 +89,16 @@ export function useDoc (collection, id, options) {
   return [$doc.get(), $doc]
 }
 
-// Batch variants are aliases to non-batch versions (no batching in teamplay).
 export function useBatchDoc (collection, id, options) {
-  return useDoc(collection, id, options)
+  const $doc = useBatchDoc$(collection, id, options)
+  if (!$doc) return [undefined, undefined]
+  return [$doc.get(), $doc]
 }
 
-export function useBatchDoc$ (collection, id, options) {
-  return useDoc$(collection, id, options)
+export function useBatchDoc$ (collection, id, _options) {
+  const $doc = getDocSignal(collection, id, 'useBatchDoc')
+  const options = _options ? { ..._options, ...BATCH_SUB_OPTIONS } : BATCH_SUB_OPTIONS
+  return useSub($doc, undefined, options)
 }
 
 export function useAsyncDoc$ (collection, id, options) {
@@ -109,8 +115,8 @@ export function useAsyncDoc (collection, id, options) {
 export function useQuery$ (collection, query, options) {
   const $collection = getCollectionSignal(collection, query, 'useQuery')
   const normalizedOptions = options ? { ...options, async: false } : options
-  useSub($collection, normalizeQuery(query, 'useQuery'), normalizedOptions)
-  return $collection
+  const $query = useSub($collection, normalizeQuery(query, 'useQuery'), normalizedOptions)
+  return $query
 }
 
 export function useQuery (collection, query, options) {
@@ -122,8 +128,8 @@ export function useQuery (collection, query, options) {
 
 export function useAsyncQuery$ (collection, query, options) {
   const $collection = getCollectionSignal(collection, query, 'useAsyncQuery')
-  useAsyncSub($collection, normalizeQuery(query, 'useAsyncQuery'), options)
-  return $collection
+  const $query = useAsyncSub($collection, normalizeQuery(query, 'useAsyncQuery'), options)
+  return $query
 }
 
 export function useAsyncQuery (collection, query, options) {
@@ -133,13 +139,17 @@ export function useAsyncQuery (collection, query, options) {
   return [$query.get(), $collection]
 }
 
-// Batch variants are aliases to non-batch versions (no batching in teamplay).
-export function useBatchQuery$ (collection, query, options) {
-  return useQuery$(collection, query, options)
+export function useBatchQuery$ (collection, query, _options) {
+  const $collection = getCollectionSignal(collection, query, 'useBatchQuery')
+  const options = _options ? { ..._options, ...BATCH_SUB_OPTIONS } : BATCH_SUB_OPTIONS
+  return useSub($collection, normalizeQuery(query, 'useBatchQuery'), options)
 }
 
 export function useBatchQuery (collection, query, options) {
-  return useQuery(collection, query, options)
+  const $collection = getCollectionSignal(collection, query, 'useBatchQuery')
+  const $query = useBatchQuery$(collection, query, options)
+  if (!$query) return [undefined, $collection]
+  return [$query.get(), $collection]
 }
 
 export function useQueryIds (collection, ids = [], options = {}) {
@@ -157,7 +167,17 @@ export function useQueryIds (collection, ids = [], options = {}) {
 }
 
 export function useBatchQueryIds (collection, ids = [], options = {}) {
-  return useQueryIds(collection, ids, options)
+  const list = Array.isArray(ids) ? ids.slice() : []
+  if (options?.reverse) list.reverse()
+  const [docs, $collection] = useBatchQuery(collection, { _id: { $in: list } }, options)
+  if (!docs) return [docs, $collection]
+  const docsById = new Map()
+  for (const doc of docs) {
+    const id = doc?._id ?? doc?.id
+    if (id != null) docsById.set(id, doc)
+  }
+  const items = list.map(id => docsById.get(id)).filter(Boolean)
+  return [items, $collection]
 }
 
 export function useAsyncQueryIds (collection, ids = [], options = {}) {
@@ -194,11 +214,23 @@ export function useQueryDoc$ (collection, query, options) {
 }
 
 export function useBatchQueryDoc (collection, query, options) {
-  return useQueryDoc(collection, query, options)
+  const normalized = normalizeQuery(query, 'useBatchQueryDoc')
+  const queryDoc = {
+    ...normalized,
+    $limit: 1,
+    $sort: normalized.$sort || { createdAt: -1 }
+  }
+  const [docs, $collection] = useBatchQuery(collection, queryDoc, options)
+  if (!docs) return [undefined, undefined]
+  const doc = docs && docs[0]
+  const docId = doc?._id ?? doc?.id
+  const $doc = docId != null ? $collection[docId] : undefined
+  return [doc, $doc]
 }
 
 export function useBatchQueryDoc$ (collection, query, options) {
-  return useQueryDoc$(collection, query, options)
+  const [, $doc] = useBatchQueryDoc(collection, query, options)
+  return $doc
 }
 
 export function useAsyncQueryDoc (collection, query, options) {
@@ -276,3 +308,11 @@ function normalizeQuery (query, hookName) {
   }
   return query
 }
+
+const BATCH_SUB_OPTIONS = Object.freeze({
+  async: false,
+  batch: true,
+  // Batch hooks are a hard suspense barrier. Deferred params can skip the barrier
+  // on route transitions and cause immediate reads from stale/empty local nodes.
+  defer: false
+})

package/orm/Compat/modelEvents.js

@@ -1,4 +1,5 @@
 import { getRefLinks } from './refRegistry.js'
+import { isCompatEnv } from '../compatEnv.js'
 
 const modelListeners = {
   change: new Map(),
@@ -6,10 +7,7 @@ const modelListeners = {
 }
 
 export function isModelEventsEnabled () {
-  return (
-    globalThis?.teamplayCompatibilityMode ??
-    (typeof process !== 'undefined' && process?.env?.TEAMPLAY_COMPAT === '1')
-  )
+  return isCompatEnv()
 }
 
 export function normalizePattern (pattern, methodName) {