@abloatai/humans 0.63.0 → 0.63.1

package/dist/react/AbloProvider.d.ts

@@ -4,24 +4,8 @@ import type { AbloClient as Ablo } from '../client.js';
 import type { PresenceSession } from '@abloatai/transaction/presence';
 import type { GroupScope } from '../local/sync/scopeGroups.js';
 import { type SyncStoreContract } from './context.js';
-/**
- * Ablo umbrella provider — owns the sync engine, multiplayer, and
- * the full lifecycle (Strict-Mode-safe singleton, `beforeunload`,
- * session-expiry handling, post-bootstrap hooks).
- *
- * Design goals:
- *
- *   - **One component, one import.** Consumers write the provider
- *     once at the root; nothing else needs to plumb the engine.
- *   - **Multiplayer is default.** React consumers share the client's scoped
- *     groups, presence stream, and model surface without another join step.
- *   - **Declarative props for app glue.** `preventUnsavedChanges`,
- *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
- *     absorbs a class of integration code that previously lived in
- *     userland.
- *   - **Singleton safety.** The engine lives in a ref and rotates
- *     only when `userId` / account scope / `url` change. React
- *     Strict Mode double-mount does not leak a second WebSocket.
+/** Reactive binding over an application-owned client. Starts readiness,
+ * forwards errors and gates bootstrap; the application owns client disposal.
  */
 /**
  * Props for `<AbloProvider>`.

package/dist/react/AbloProvider.js

@@ -44,7 +44,7 @@ export function AbloProvider(props) {
     const schema = engine.schema;
     // Account scope isn't a prop — read it from `_store.orgId` once `ready()`
     // resolves the identity from the client's auth.
-    const [resolvedAccountScope, setResolvedAccountScope] = useState(null);
+    const [resolvedScope, setResolvedScope] = useState(null);
     // ── Error emitter (provider-instance scoped) ─────────────────────
     const errorEmitterRef = useRef(null);
     if (!errorEmitterRef.current) {
@@ -98,7 +98,10 @@ export function AbloProvider(props) {
             .then(() => {
             if (stale)
                 return;
-            setResolvedAccountScope(engine._store.orgId ?? null);
+            setResolvedScope({
+                engine,
+                account: engine._store.orgId ?? null,
+            });
         })
             .catch((err) => {
             if (stale)
@@ -133,7 +136,7 @@ export function AbloProvider(props) {
     // unknown until `ready()` resolves identity — so `syncValue` is null until
     // then, which drives the initial fallback below.
     const syncValue = useMemo(() => {
-        const currentAccountScope = resolvedAccountScope ??
+        const currentAccountScope = (resolvedScope?.engine === engine ? resolvedScope.account : null) ??
             engine._store.orgId;
         if (!currentAccountScope)
             return null;
@@ -142,7 +145,7 @@ export function AbloProvider(props) {
             organizationId: currentAccountScope,
             schema,
         };
-    }, [engine, resolvedAccountScope, schema]);
+    }, [engine, resolvedScope, schema]);
     // ── Internal context (currentUserId + error subscription) ────────
     const internalValue = useMemo(() => ({
         currentUserId: userId ?? null,
@@ -152,28 +155,10 @@ export function AbloProvider(props) {
     }), [userId, errorEmitter, engine]);
     // ── Render ───────────────────────────────────────────────────────
     //
-    // Two-phase gate (see `BootstrapGate` below for the latch logic):
-    //
-    //   1. Engine is null on first render (constructed in the effect
-    //      above, not in render). We render `fallback` directly — there
-    //      is no SyncContext to read status from, and by definition the
-    //      engine hasn't started bootstrapping.
-    //   2. Engine exists. Mount SyncContext. `BootstrapGate` then reads
-    //      `useSyncStatus()` and shows `fallback` only during the very
-    //      first `connecting` transition; children render on every
-    //      subsequent state change, including reconnects and auth
-    //      failures (the app's own UI handles those).
-    //
-    // `fallback === 'passthrough'` short-circuits both branches — children
-    // render immediately without any gate, restoring pre-gate behavior
-    // for consumers who need debug helpers / error boundaries / analytics
-    // to mount before the engine is ready.
+    // Keep the context tree stable during startup so passthrough children retain
+    // their component state when authenticated row scope becomes available.
     const passthrough = fallback === 'passthrough';
-    const initialFallback = passthrough ? children : fallback;
-    if (!syncValue) {
-        return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: initialFallback }));
-    }
-    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineKey)) }) }));
+    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : syncValue ? (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineKey)) : fallback }) }));
 }
 /**
  * Internal gate that renders `fallback` only during the very first
@@ -183,8 +168,7 @@ export function AbloProvider(props) {
  * re-show the fallback, because by then the app has already rendered
  * once and its own reconnect UI should take over.
  *
- * Re-keyed on `engineState.key` in the parent so engine rotations
- * (userId/org/url change) reset the latch — a new engine genuinely IS
+ * Re-keyed when the client instance changes so account rotations reset the latch — a new engine genuinely IS
  * a new "first bootstrap" cycle.
  */
 function BootstrapGate({ fallback, children, }) {

package/dist/react/useAblo.d.ts

@@ -60,7 +60,7 @@ export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'>
  * // are typed as snapshot rows — data fields + computeds, no relation
  * // accessors — matching what the hook actually returns:
  * const doc = useAblo((ablo) => ablo.records.local.get(id)) ?? serverDoc;
- * const active = useAblo((ablo) => ablo.records.claim.state({ id }));
+ * const { claimed } = useAblo((ablo) => ablo.records, id);
  *
  * // Without the augmentation, pass the schema as a type argument:
  * const ablo = useAblo<(typeof schema)['models']>();

package/dist/react/useAblo.js

@@ -82,12 +82,9 @@ export function useAbloImpl(boundClient, modelOrSelect, id, options) {
             : modelOrSelect;
     // Claims arrive through an event emitter (engine.claims), not through MobX, so
     // the useReactive reactions below cannot track them; we bridge changes with a
-    // setState bump instead. Only the model-row form (`id !== undefined`) reads
-    // claims, so we subscribe only when `id` is set. The selector-only form never
-    // reads claims, and subscribing it to the workspace-wide claim stream would
-    // re-render and recompute it on every claim or presence change anywhere — a
-    // real storm during AI editing or live collaboration — for a value that cannot
-    // change.
+    // setState bump instead. Subscribe the model-row form (`id !== undefined`)
+    // to claims. Selector-only reads track MobX model data; callers displaying
+    // ownership use the row form's `claims` / `claimed` result.
     const [claimVersion, setClaimVersion] = useState(0);
     useEffect(() => {
         if (!engine || id === undefined)

package/dist/react/useSyncStatus.js

@@ -1,10 +1,21 @@
 'use client';
-import { useCallback } from 'react';
-import { useSyncContext, } from './context.js';
+import { useCallback, useContext } from 'react';
+import { SyncContext, } from './context.js';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useReactive } from '../useReactive.js';
 /** Reactively exposes the local store's connection and confirmation status. */
 export function useSyncStatus() {
-    const { store } = useSyncContext();
+    const provider = useContext(AbloInternalContext);
+    const sync = useContext(SyncContext);
+    // Status does not require authenticated row scope. The client exists before
+    // ready() resolves, including inside passthrough children and custom fallbacks.
+    const store = provider?.engine?._store ?? sync?.store;
+    if (!store) {
+        throw new AbloValidationError('Sync hooks must be used within an <AbloProvider>.', {
+            code: 'sync_context_missing_provider',
+        });
+    }
     const compute = useCallback(() => deriveStatus(store), [store]);
     return useReactive(compute, sameSnapshot);
 }

package/dist/useReactive.js

@@ -11,7 +11,6 @@ export function useReactive(compute, equals = defaultEquals) {
     const computeRef = useRef(compute);
     const equalsRef = useRef(equals);
     const snapshotRef = useRef(null);
-    const versionRef = useRef(0);
     equalsRef.current = equals;
     if (snapshotRef.current === null) {
         snapshotRef.current = { value: compute() };
@@ -20,7 +19,6 @@ export function useReactive(compute, equals = defaultEquals) {
         const next = compute();
         if (!equals(snapshotRef.current.value, next)) {
             snapshotRef.current = { value: next };
-            versionRef.current++;
         }
     }
     computeRef.current = compute;
@@ -30,7 +28,7 @@ export function useReactive(compute, equals = defaultEquals) {
             snapshotRef.current = { value: next };
             onChange();
         }
-    }), [versionRef.current]);
+    }), [compute]);
     const getSnapshot = useCallback(() => snapshotRef.current.value, []);
     return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.63.0",
+  "version": "0.63.1",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.63.0",
+    "@abloatai/transaction": "^0.63.1",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/react/AbloProvider.tsx

@@ -22,24 +22,8 @@ import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
 import { presenceOfClient } from '../presence/index.js';
 
-/**
- * Ablo umbrella provider — owns the sync engine, multiplayer, and
- * the full lifecycle (Strict-Mode-safe singleton, `beforeunload`,
- * session-expiry handling, post-bootstrap hooks).
- *
- * Design goals:
- *
- *   - **One component, one import.** Consumers write the provider
- *     once at the root; nothing else needs to plumb the engine.
- *   - **Multiplayer is default.** React consumers share the client's scoped
- *     groups, presence stream, and model surface without another join step.
- *   - **Declarative props for app glue.** `preventUnsavedChanges`,
- *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
- *     absorbs a class of integration code that previously lived in
- *     userland.
- *   - **Singleton safety.** The engine lives in a ref and rotates
- *     only when `userId` / account scope / `url` change. React
- *     Strict Mode double-mount does not leak a second WebSocket.
+/** Reactive binding over an application-owned client. Starts readiness,
+ * forwards errors and gates bootstrap; the application owns client disposal.
  */
 
 // ── Props ────────────────────────────────────────────────────────────
@@ -182,7 +166,7 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
 
   // Account scope isn't a prop — read it from `_store.orgId` once `ready()`
   // resolves the identity from the client's auth.
-  const [resolvedAccountScope, setResolvedAccountScope] = useState<string | null>(null);
+  const [resolvedScope, setResolvedScope] = useState<{ engine: typeof engine; account: string | null } | null>(null);
 
   // ── Error emitter (provider-instance scoped) ─────────────────────
   const errorEmitterRef = useRef<ReturnType<typeof createErrorEmitter> | null>(null);
@@ -240,9 +224,10 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
       .ready()
       .then(() => {
         if (stale) return;
-        setResolvedAccountScope(
-          (engine._store as SyncStoreContract & { orgId?: string }).orgId ?? null,
-        );
+        setResolvedScope({
+          engine,
+          account: (engine._store as SyncStoreContract & { orgId?: string }).orgId ?? null,
+        });
       })
       .catch((err) => {
         if (stale) return;
@@ -280,7 +265,7 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
   // then, which drives the initial fallback below.
   const syncValue = useMemo(() => {
     const currentAccountScope =
-      resolvedAccountScope ??
+      (resolvedScope?.engine === engine ? resolvedScope.account : null) ??
       (engine._store as SyncStoreContract & { orgId?: string }).orgId;
     if (!currentAccountScope) return null;
     return {
@@ -288,7 +273,7 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
       organizationId: currentAccountScope,
       schema,
     };
-  }, [engine, resolvedAccountScope, schema]);
+  }, [engine, resolvedScope, schema]);
 
   // ── Internal context (currentUserId + error subscription) ────────
 
@@ -301,44 +286,20 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
 
   // ── Render ───────────────────────────────────────────────────────
   //
-  // Two-phase gate (see `BootstrapGate` below for the latch logic):
-  //
-  //   1. Engine is null on first render (constructed in the effect
-  //      above, not in render). We render `fallback` directly — there
-  //      is no SyncContext to read status from, and by definition the
-  //      engine hasn't started bootstrapping.
-  //   2. Engine exists. Mount SyncContext. `BootstrapGate` then reads
-  //      `useSyncStatus()` and shows `fallback` only during the very
-  //      first `connecting` transition; children render on every
-  //      subsequent state change, including reconnects and auth
-  //      failures (the app's own UI handles those).
-  //
-  // `fallback === 'passthrough'` short-circuits both branches — children
-  // render immediately without any gate, restoring pre-gate behavior
-  // for consumers who need debug helpers / error boundaries / analytics
-  // to mount before the engine is ready.
-
+  // Keep the context tree stable during startup so passthrough children retain
+  // their component state when authenticated row scope becomes available.
   const passthrough = fallback === 'passthrough';
-  const initialFallback = passthrough ? children : fallback;
-
-  if (!syncValue) {
-    return (
-      <AbloInternalContext.Provider value={internalValue}>
-        {initialFallback}
-      </AbloInternalContext.Provider>
-    );
-  }
 
   return (
     <AbloInternalContext.Provider value={internalValue}>
       <SyncContext.Provider value={syncValue}>
         {passthrough ? (
           children
-        ) : (
+        ) : syncValue ? (
           <BootstrapGate key={engineKey} fallback={fallback}>
             {children}
           </BootstrapGate>
-        )}
+        ) : fallback}
       </SyncContext.Provider>
     </AbloInternalContext.Provider>
   );
@@ -352,8 +313,7 @@ export function AbloProvider<R extends SchemaRecord = SchemaRecord>(
  * re-show the fallback, because by then the app has already rendered
  * once and its own reconnect UI should take over.
  *
- * Re-keyed on `engineState.key` in the parent so engine rotations
- * (userId/org/url change) reset the latch — a new engine genuinely IS
+ * Re-keyed when the client instance changes so account rotations reset the latch — a new engine genuinely IS
  * a new "first bootstrap" cycle.
  */
 function BootstrapGate({

package/src/react/useAblo.ts

@@ -144,7 +144,7 @@ function snapshotValue<T>(value: T): T {
  * // are typed as snapshot rows — data fields + computeds, no relation
  * // accessors — matching what the hook actually returns:
  * const doc = useAblo((ablo) => ablo.records.local.get(id)) ?? serverDoc;
- * const active = useAblo((ablo) => ablo.records.claim.state({ id }));
+ * const { claimed } = useAblo((ablo) => ablo.records, id);
  *
  * // Without the augmentation, pass the schema as a type argument:
  * const ablo = useAblo<(typeof schema)['models']>();
@@ -237,12 +237,9 @@ export function useAbloImpl<
 
   // Claims arrive through an event emitter (engine.claims), not through MobX, so
   // the useReactive reactions below cannot track them; we bridge changes with a
-  // setState bump instead. Only the model-row form (`id !== undefined`) reads
-  // claims, so we subscribe only when `id` is set. The selector-only form never
-  // reads claims, and subscribing it to the workspace-wide claim stream would
-  // re-render and recompute it on every claim or presence change anywhere — a
-  // real storm during AI editing or live collaboration — for a value that cannot
-  // change.
+  // setState bump instead. Subscribe the model-row form (`id !== undefined`)
+  // to claims. Selector-only reads track MobX model data; callers displaying
+  // ownership use the row form's `claims` / `claimed` result.
   const [claimVersion, setClaimVersion] = useState(0);
   useEffect(() => {
     if (!engine || id === undefined) return;

package/src/react/useSyncStatus.ts

@@ -1,10 +1,12 @@
 'use client';
 
-import { useCallback } from 'react';
+import { useCallback, useContext } from 'react';
 import {
-  useSyncContext,
+  SyncContext,
   type SyncStoreContract,
 } from './context.js';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
 import { useReactive } from '../useReactive.js';
 
 export type SyncStatusSnapshot =
@@ -17,7 +19,16 @@ export type SyncStatusSnapshot =
 
 /** Reactively exposes the local store's connection and confirmation status. */
 export function useSyncStatus(): SyncStatusSnapshot {
-  const { store } = useSyncContext();
+  const provider = useContext(AbloInternalContext);
+  const sync = useContext(SyncContext);
+  // Status does not require authenticated row scope. The client exists before
+  // ready() resolves, including inside passthrough children and custom fallbacks.
+  const store = provider?.engine?._store ?? sync?.store;
+  if (!store) {
+    throw new AbloValidationError('Sync hooks must be used within an <AbloProvider>.', {
+      code: 'sync_context_missing_provider',
+    });
+  }
   const compute = useCallback(() => deriveStatus(store), [store]);
   return useReactive(compute, sameSnapshot);
 }

package/src/useReactive.ts

@@ -16,7 +16,6 @@ export function useReactive<T>(
   const computeRef = useRef(compute);
   const equalsRef = useRef(equals);
   const snapshotRef = useRef<{ value: T } | null>(null);
-  const versionRef = useRef(0);
 
   equalsRef.current = equals;
   if (snapshotRef.current === null) {
@@ -25,7 +24,6 @@ export function useReactive<T>(
     const next = compute();
     if (!equals(snapshotRef.current.value, next)) {
       snapshotRef.current = { value: next };
-      versionRef.current++;
     }
   }
   computeRef.current = compute;
@@ -39,7 +37,7 @@ export function useReactive<T>(
         onChange();
       }
     },
-  ), [versionRef.current]);
+  ), [compute]);
   const getSnapshot = useCallback(() => snapshotRef.current!.value, []);
   return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }