@abloatai/humans 0.37.0

package/src/react/ClientSideSuspense.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import { useEffect, useState, type ReactNode } from 'react';
+import { useSyncStatus } from './useSyncStatus.js';
+
+/**
+ * Nested bootstrap gate for a subtree. `<AbloProvider>` already ships
+ * its own built-in gate (via its `fallback` prop) that handles the
+ * common "wait for first bootstrap" case. Use `ClientSideSuspense`
+ * only when you need a SEPARATE gate inside an already-ready provider —
+ * for example, rendering app chrome immediately while gating a single
+ * heavy product surface on its own query resolving.
+ *
+ * Like the provider-level gate, this component latches open on the
+ * first `connected` / `reconnecting` / `disconnected` transition and
+ * stays open. Subsequent transient `connecting` states (hard reconnect
+ * after offline) do NOT re-show the fallback — the app has already
+ * rendered once and its own reconnect UI should take over.
+ *
+ * v0.3.x implementation is non-Suspense: reads `useSyncStatus()` and
+ * conditionally renders. v0.3.x+ will ship a
+ * the React suspense entry point where `useQuery` / `useOne`
+ * actually throw Promises; this component becomes a thin wrapper around
+ * React's real `<Suspense>` at that point.
+ *
+ * @example
+ * <AbloProvider fallback={<AppSkeleton />}>
+ *   <AppChrome />
+ *   <ClientSideSuspense fallback={<CanvasSkeleton />}>
+ *     <HeavyCanvas />
+ *   </ClientSideSuspense>
+ * </AbloProvider>
+ */
+export interface ClientSideSuspenseProps {
+  /** What to render while the nested subtree is waiting for first bootstrap. */
+  fallback: ReactNode;
+  /** What to render once the subtree is cleared to render. */
+  children: ReactNode;
+}
+
+export function ClientSideSuspense({ fallback, children }: ClientSideSuspenseProps) {
+  const status = useSyncStatus();
+  const [everConnected, setEverConnected] = useState(false);
+
+  useEffect(() => {
+    if (
+      status.name === 'connected' ||
+      status.name === 'reconnecting' ||
+      status.name === 'disconnected'
+    ) {
+      setEverConnected(true);
+    }
+  }, [status.name]);
+
+  const showFallback = !everConnected && status.name === 'connecting';
+  return <>{showFallback ? fallback : children}</>;
+}

package/src/react/DefaultFallback.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+/**
+ * Neutral loading placeholder — the default value of `<AbloProvider>`'s
+ * `fallback` prop. Rendered during the first bootstrap pass when the
+ * consumer hasn't supplied their own skeleton.
+ *
+ * Design goals:
+ *   - Zero design-system dependency. Inline styles only; no CSS file,
+ *     no UI-lib imports, no Tailwind assumptions.
+ *   - Theme-adaptive. Uses `currentColor` for the ring so the spinner
+ *     inherits the text color from whichever ancestor defines it —
+ *     works in light + dark contexts without a prop.
+ *   - Self-centering. Flex-centered in a full-parent container so the
+ *     common case (provider at the layout root) renders a spinner in
+ *     the middle of the viewport. Consumers who need different
+ *     positioning compose their own fallback and pass it explicitly.
+ *   - Minimal bundle footprint. The whole component + keyframe is ~50
+ *     bytes gzipped.
+ *
+ * Consumers wanting a branded loader should pass `fallback={<YourSkeleton />}`
+ * on `<AbloProvider>`. Consumers wanting NO visual during bootstrap
+ * pass `fallback={null}`. Consumers who want to skip the gate entirely
+ * pass `fallback="passthrough"`.
+ */
+export function DefaultFallback() {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      aria-label="Loading"
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: '100%',
+        minHeight: '100vh',
+        color: 'currentColor',
+      }}
+    >
+      <div
+        style={{
+          width: 24,
+          height: 24,
+          border: '2px solid currentColor',
+          borderTopColor: 'transparent',
+          borderRadius: '50%',
+          opacity: 0.6,
+          animation: 'ablo-default-fallback-spin 0.8s linear infinite',
+        }}
+      />
+      {/*
+        Keyframe ships inline so the component has zero external-CSS
+        dependencies. Name is prefixed so it can't collide with
+        consumer-defined animations.
+      */}
+      <style>{`@keyframes ablo-default-fallback-spin { to { transform: rotate(360deg); } }`}</style>
+    </div>
+  );
+}

package/src/react/context.ts

@@ -0,0 +1,89 @@
+'use client';
+
+import { createContext, createElement, useContext, type ReactNode } from 'react';
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import type { SyncStoreContract } from '../local/storeContract.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+
+// `SyncStoreContract` and `LocalMutation` are defined in a React-free module,
+// so code that never touches React can still implement the store. They are
+// re-exported here for the convenience of React consumers.
+export type {
+  SyncStoreContract,
+  LocalMutation,
+} from '../local/storeContract.js';
+
+export interface SyncReactContext {
+  store: SyncStoreContract;
+  /** The organization id used as the default scope for reads and writes. */
+  organizationId: string;
+  /**
+   * An optional schema. When provided, hooks that take a model by name (such as
+   * `useQuery('tasks')`) read that model's metadata from this schema, so
+   * callers don't pass a schema at every call site. When omitted, those hooks
+   * require the schema as an argument instead.
+   *
+   * The field is loosely typed here because a single runtime context value is
+   * shared by every hook. Precise per-model types come from your `Register`
+   * module augmentation
+   * (`declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`),
+   * not from this reference.
+   */
+  schema?: Schema;
+}
+
+export const SyncContext = createContext<SyncReactContext | null>(null);
+
+/**
+ * Reads the sync store context from inside a provider subtree, throwing a clear
+ * error when no provider is mounted above. `<AbloProvider>` supplies this
+ * context by rendering the internal {@link SyncProvider}; you wire
+ * `<AbloProvider client={ablo}>` rather than touching this directly.
+ */
+export function useSyncContext(): SyncReactContext {
+  const ctx = useContext(SyncContext);
+  if (!ctx) {
+    throw new AbloValidationError('Sync hooks must be used within an <AbloProvider>.', {
+      code: 'sync_context_missing_provider',
+    });
+  }
+  return ctx;
+}
+
+/**
+ * Props for SyncProvider.
+ */
+export interface SyncProviderProps {
+  /** The sync store, which must implement {@link SyncStoreContract}. */
+  store: SyncStoreContract;
+  /** The organization id used as the default scope for reads and writes. */
+  organizationId: string;
+  /**
+   * An optional schema. Provide it to enable hooks that take a model by name
+   * (such as `useQuery('tasks')`); the model types also narrow through your
+   * `Register` augmentation. Omit it to pass the schema to those hooks directly
+   * instead.
+   */
+  schema?: Schema;
+  children?: ReactNode;
+}
+
+/**
+ * A low-level provider that places a built sync store on React context so the
+ * data hooks can reach it. This is an internal building block: it is not part
+ * of the package's public entry point. Reach for `<AbloProvider>` instead,
+ * which builds the store from your `Ablo({ schema, apiKey })` client and
+ * renders this provider underneath.
+ */
+export function SyncProvider({
+  store,
+  organizationId,
+  schema,
+  children,
+}: SyncProviderProps) {
+  return createElement(
+    SyncContext.Provider,
+    { value: { store, organizationId, schema } },
+    children
+  );
+}

package/src/react/createAbloReact.ts

@@ -0,0 +1,116 @@
+'use client';
+
+/**
+ * The typed react binding — the schema generic is captured ONCE, at a factory
+ * call in app code, and every hook the factory returns is born typed. This is
+ * a schema-bound shape with no module augmentation or generic parameters at call sites,
+ * and — once the legacy generic erasure retires — no casts anywhere on the
+ * path from context to component.
+ *
+ * The app's one binding file, by convention:
+ *
+ * ```ts
+ * // lib/ablo.ts
+ * import { createAbloReact } from '@abloatai/ablo/react';
+ * import { schema } from './schema';
+ *
+ * export const { AbloProvider, useAblo } = createAbloReact(schema);
+ * ```
+ *
+ * Components then import `useAblo` from `lib/ablo` and never spell a type
+ * argument; `useAblo()` is `Ablo<S> | null`, and a selector's `ablo`
+ * parameter is the reactive-read view of the same `S`.
+ */
+
+import { createContext, createElement, useContext, type ReactElement } from 'react';
+import {
+  AbloProvider,
+  type AbloProviderProps,
+} from './AbloProvider.js';
+import {
+  useAbloImpl,
+  type AbloSelector,
+  type ModelClientSelector,
+  type UseAbloHydratedModelResult,
+  type UseAbloModelOptions,
+  type UseAbloModelResult,
+} from './useAblo.js';
+import type { AbloClient as Ablo } from '../client.js';
+import type { ModelOperations } from '../local/client/createModelProxy.js';
+import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
+
+/** What a binding returns: the provider and the hook, with `S` fixed. */
+export interface AbloReactBinding<S extends SchemaRecord> {
+  /** `AbloProvider` with its `client` prop typed `Ablo<S>` — same component,
+   *  no per-app generics. */
+  AbloProvider: (props: AbloProviderProps<S>) => ReactElement;
+  /** `useAblo` with the schema bound — the same overloads as the global
+   *  hook, minus the type arguments. */
+  useAblo: {
+    (): Ablo<S> | null;
+    <T>(select: AbloSelector<S, T>): T | undefined;
+    <T, C>(
+      modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>,
+      id: string,
+      options: UseAbloModelOptions<T> & { readonly initial: T },
+    ): UseAbloHydratedModelResult<T>;
+    <T, C>(
+      modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>,
+      id: string,
+      options?: UseAbloModelOptions<T>,
+    ): UseAbloModelResult<T>;
+  };
+}
+
+/**
+ * Bind the react surface to one schema. The schema value is taken for
+ * inference — write `createAbloReact(schema)`, never a hand-spelled type
+ * argument — and it is the seam where the binding's own typed context arrives
+ * when the legacy erasure retires (docs/plans/typed-react-binding.md, step 3).
+ */
+export function createAbloReact<S extends SchemaRecord>(
+  schema: Schema<S>,
+): AbloReactBinding<S> {
+  void schema;
+
+  // The binding's own context — created here, AFTER the schema generic is
+  // known, so it is typed `Ablo<S>` from birth. A hook that reads it never rebinds and
+  // never casts; a binding hook mounted under a legacy provider (no bound
+  // provider in the tree) reads `null` here and falls through to the shared
+  // implementation's internal-context fallback.
+  const BoundClientContext = createContext<Ablo<S> | null>(null);
+
+  function BoundAbloProvider(props: AbloProviderProps<S>): ReactElement {
+    return createElement(
+      BoundClientContext.Provider,
+      { value: props.client },
+      createElement(AbloProvider<S>, props),
+    );
+  }
+
+  function useBoundAblo(): Ablo<S> | null;
+  function useBoundAblo<T>(select: AbloSelector<S, T>): T | undefined;
+  function useBoundAblo<T, C>(
+    modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>,
+    id: string,
+    options: UseAbloModelOptions<T> & { readonly initial: T },
+  ): UseAbloHydratedModelResult<T>;
+  function useBoundAblo<T, C>(
+    modelClientOrSelect: ModelOperations<T, C> | ModelClientSelector<S, T, C>,
+    id: string,
+    options?: UseAbloModelOptions<T>,
+  ): UseAbloModelResult<T>;
+  function useBoundAblo<T, C>(
+    modelOrSelect?:
+      | ModelOperations<T, C>
+      | ModelClientSelector<S, T, C>
+      | AbloSelector<S, T>,
+    id?: string,
+    options?: UseAbloModelOptions<T>,
+  ): Ablo<S> | null | UseAbloModelResult<T> | T | undefined {
+    const bound = useContext(BoundClientContext);
+    return useAbloImpl<S, T, C>(bound, modelOrSelect, id, options);
+  }
+
+  return { AbloProvider: BoundAbloProvider, useAblo: useBoundAblo };
+}

package/src/react/internalContext.ts

@@ -0,0 +1,38 @@
+'use client';
+
+import { createContext } from 'react';
+import type { AbloClient as Ablo } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+
+/**
+ * The context that `<AbloProvider>` populates for its own hooks. It is kept
+ * separate from the data-hook context, which carries the store and schema,
+ * because these fields belong to the provider rather than to the store. Read
+ * them through the typed hooks such as `useCurrentUserId` and
+ * `useErrorListener` rather than reaching into this context directly.
+ */
+export interface AbloInternalContextValue {
+  /**
+   * The application user id, when your app passed one to `<AbloProvider>`. Sync
+   * identity is derived on the server from the API key, so this is `null`
+   * unless you set it, and it is not required for sync to work.
+   */
+  currentUserId: string | null;
+  /** Subscribe to provider-level errors: engine errors, bootstrap failures, and session issues. */
+  subscribeError: (listener: (error: Error) => void) => () => void;
+  /** Emit an error to every subscribed listener. The provider calls this for you. */
+  emitError: (error: Error) => void;
+  /**
+   * The typed `Ablo` client for this provider, or `null` until the first sync
+   * bootstrap resolves. It is held here so `useSync()` can return it without
+   * reaching into the store; the client and the store are sibling objects, and
+   * neither is derived from the other.
+   *
+   * It is typed loosely as `Ablo<SchemaRecord>` because generics do not flow
+   * through React context. `useSync<R>()` restores the precise type through its
+   * own generic; the runtime value is the fully typed client.
+   */
+  engine: Ablo<SchemaRecord> | null;
+}
+
+export const AbloInternalContext = createContext<AbloInternalContextValue | null>(null);

package/src/react/useAblo.ts

@@ -0,0 +1,280 @@
+'use client';
+
+import { useContext, useEffect, useState } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import type { AbloClient as Ablo, AbloReads } from '../client.js';
+import type { ModelClaim } from '@abloatai/transaction/coordination';
+import {
+  getModelClientMeta,
+  type ModelOperations,
+} from '../local/client/createModelProxy.js';
+import { Model } from '../local/Model.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import { useReactive } from '../useReactive.js';
+
+/**
+ * The app's resolved schema-record type. It reads your `Register` module
+ * augmentation when you declare one and falls back to the loose
+ * {@link SchemaRecord} otherwise, so `useAblo()` returns a fully typed client
+ * without you passing `<(typeof schema)['models']>` at every call site.
+ */
+type DefaultModels = ResolveSchema extends { models: infer M }
+  ? M extends SchemaRecord
+    ? M
+    : SchemaRecord
+  : SchemaRecord;
+
+const EMPTY_CLAIMS: readonly ModelClaim[] = Object.freeze([]);
+
+/**
+ * Restore the caller's schema generics on the context-held engine. React
+ * context erases generics (see `AbloInternalContextValue.engine`), so this is
+ * the one deliberate rebind point: the runtime value is the fully typed
+ * client, and `R` is the compile-time view the calling hook declared.
+ */
+function rebindEngine<R extends SchemaRecord>(engine: Ablo<SchemaRecord>): Ablo<R> {
+  return engine as Ablo<R>;
+}
+
+/**
+ * The reactive-read view of a client — the identical runtime object, with
+ * model reads typed as snapshot rows, because everything a selector returns
+ * is converted through `snapshotValue` before the hook hands it back. Same
+ * generic in and out, so this compiles with no schema rebinding.
+ */
+function reactiveReads<R extends SchemaRecord>(engine: Ablo<R>): AbloReads<R> {
+  return engine as AbloReads<R>;
+}
+
+// Selectors receive the reactive-read client: model reads are typed as
+// snapshot rows (data fields + computeds, no relation accessors), which is the
+// shape the hook actually returns after `toReactiveSnapshot()`. This makes the
+// selector's inferred result type honest — `row.layers` fails to compile here
+// instead of reading `undefined` at runtime.
+export type ModelClientSelector<R extends SchemaRecord, T, C> =
+  (ablo: AbloReads<R>) => ModelOperations<T, C>;
+export type AbloSelector<R extends SchemaRecord, T> = (ablo: AbloReads<R>) => T;
+
+export interface UseAbloModelOptions<T> {
+  /**
+   * An initial row, usually from a server component or a route loader. The hook
+   * returns it until sync delivers a newer row for the same id.
+   */
+  readonly initial?: T;
+}
+
+export interface UseAbloModelResult<T> {
+  /** The current row for the id, or `initial` until the row has synced. */
+  readonly data: T | undefined;
+  /** The work claims currently held on this row by any participant. */
+  readonly claims: readonly ModelClaim[];
+  /** True while another participant holds a claim — handy for disabling UI. */
+  readonly claimed: boolean;
+}
+
+export type UseAbloHydratedModelResult<T> =
+  Omit<UseAbloModelResult<T>, 'data'> & { readonly data: T };
+
+function readModelResult<R extends SchemaRecord, T, C>(
+  engine: Ablo<R> | null,
+  modelClient: ModelOperations<T, C> | undefined,
+  id: string | undefined,
+  initial: T | undefined,
+): UseAbloModelResult<T> {
+  if (!modelClient || id === undefined) {
+    return { data: initial, claims: EMPTY_CLAIMS, claimed: false };
+  }
+
+  const data = snapshotValue(modelClient.local.get(id) ?? initial);
+  const meta = getModelClientMeta(modelClient);
+  const claims = meta && engine
+    ? engine.claims.list({ model: meta.key, id })
+    : EMPTY_CLAIMS;
+
+  return { data, claims, claimed: claims.length > 0 };
+}
+
+/**
+ * Projects a reactive read into the value that `useReactive` caches and
+ * returns.
+ *
+ * For a `Model`, this reads the row's fields through `toReactiveSnapshot`
+ * rather than returning the instance itself. Property access is what subscribes
+ * the reaction to those fields, so the read has to happen inside this tracked
+ * function; returning the live instance without reading its fields would leave
+ * the component blind to later edits. The fresh object it produces also lets
+ * `useReactive`'s equality check detect an in-place update.
+ */
+function snapshotValue<T>(value: T): T {
+  if (value instanceof Model) {
+    return value.toReactiveSnapshot<T>();
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => snapshotValue(item)) as T;
+  }
+  return value;
+}
+
+/**
+ * Reads Ablo from inside an `<AbloProvider>` subtree. Called with no arguments
+ * it returns the typed client for use in callbacks and effects; called with a
+ * selector it subscribes the component to a reactive read — such as one
+ * `ablo.<model>` row — and re-renders when that read changes.
+ *
+ * You can call it with no type arguments once you declare the `Register` module
+ * augmentation (`declare module '@abloatai/ablo' { interface Register {
+ * Schema: typeof schema } }`); the default type then resolves through your
+ * schema's models, so call sites stay clean:
+ *
+ * **Prefer the binding.** `createAbloReact(schema)` captures the schema once
+ * in your app's binding file and returns a `useAblo` that needs none of the
+ * typing arrangements below — no type argument, no `Register` declaration
+ * (see `react.md`). Passing an explicit schema type argument to THIS hook is
+ * deprecated in favor of that binding; it keeps working for shared packages
+ * that cannot bind a concrete schema.
+ *
+ * ```ts
+ * // With the Register augmentation (recommended):
+ * const ablo = useAblo();
+ * if (!ablo) return <Loading />;
+ * const doc = await ablo.documents.get({ id }); // async server read
+ *
+ * // Reactive selector (a synchronous local snapshot). The selector's reads
+ * // are typed as snapshot rows — data fields + computeds, no relation
+ * // accessors — matching what the hook actually returns:
+ * const doc = useAblo((ablo) => ablo.documents.local.get(id)) ?? serverDoc;
+ * const active = useAblo((ablo) => ablo.documents.claim.state({ id }));
+ *
+ * // Without the augmentation, pass the schema as a type argument:
+ * const ablo = useAblo<(typeof schema)['models']>();
+ * ```
+ *
+ * The no-argument form returns `null` while the engine is still bootstrapping.
+ * Branch on `null` and render a loading state — or gate on `useSyncStatus()`
+ * reaching `'connected'` — before calling model methods.
+ */
+export function useAblo<R extends SchemaRecord = DefaultModels>(): Ablo<R> | null;
+export function useAblo<
+  R extends SchemaRecord = DefaultModels,
+  T = unknown,
+>(
+  select: AbloSelector<R, T>,
+): T | undefined;
+export function useAblo<T, C>(
+  modelClient: ModelOperations<T, C>,
+  id: string,
+  options: UseAbloModelOptions<T> & { readonly initial: T },
+): UseAbloHydratedModelResult<T>;
+export function useAblo<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  select: ModelClientSelector<R, T, C>,
+  id: string,
+  options: UseAbloModelOptions<T> & { readonly initial: T },
+): UseAbloHydratedModelResult<T>;
+export function useAblo<T, C>(
+  modelClient: ModelOperations<T, C>,
+  id: string,
+  options?: UseAbloModelOptions<T>,
+): UseAbloModelResult<T>;
+export function useAblo<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  select: ModelClientSelector<R, T, C>,
+  id: string,
+  options?: UseAbloModelOptions<T>,
+): UseAbloModelResult<T>;
+export function useAblo<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  modelOrSelect?: ModelOperations<T, C> | ModelClientSelector<R, T, C> | AbloSelector<R, T>,
+  id?: string,
+  options?: UseAbloModelOptions<T>,
+): Ablo<R> | null | UseAbloModelResult<T> | T | undefined {
+  return useAbloImpl<R, T, C>(null, modelOrSelect, id, options);
+}
+
+/**
+ * @internal The one implementation behind `useAblo` and the bound hooks a
+ * `createAbloReact` binding returns — written once so the reactive read path
+ * cannot fork between the global hook and a factory's.
+ *
+ * `boundClient` is a binding's own context value — typed `Ablo<S>` at the
+ * factory, so that path never rebinds and never casts. `null` means "no
+ * binding provider in this tree": the global hook always passes it, and a
+ * binding hook mounted under a legacy provider falls through to the erased
+ * internal context, which is what keeps both mounts working while the last
+ * legacy mount migrates.
+ */
+export function useAbloImpl<
+  R extends SchemaRecord,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  boundClient: Ablo<R> | null,
+  modelOrSelect?: ModelOperations<T, C> | ModelClientSelector<R, T, C> | AbloSelector<R, T>,
+  id?: string,
+  options?: UseAbloModelOptions<T>,
+): Ablo<R> | null | UseAbloModelResult<T> | T | undefined {
+  const ctx = useContext(AbloInternalContext);
+  // The bound client wins — it is already `Ablo<R>`, no rebinding. The
+  // fallback is the ONE remaining schema rebind in the SDK; it retires with
+  // the last legacy provider mount (docs/plans/typed-react-binding.md).
+  const engine: Ablo<R> | null =
+    boundClient ?? (ctx?.engine ? rebindEngine<R>(ctx.engine) : null);
+  const initial = options?.initial;
+  const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
+  const modelClient: ModelOperations<T, C> | undefined =
+    typeof modelOrSelect === 'function' && id !== undefined
+      ? engine
+        ? (modelOrSelect(reactiveReads<R>(engine)) as ModelOperations<T, C>)
+        : undefined
+      : typeof modelOrSelect === 'function'
+        ? undefined
+        : 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.
+  const [claimVersion, setClaimVersion] = useState(0);
+  useEffect(() => {
+    if (!engine || id === undefined) return;
+    return engine.claims.onChange(() => { setClaimVersion((version) => version + 1); });
+  }, [engine, id]);
+
+  const selected = useReactive<T | undefined>(
+    () => {
+      if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {
+        return undefined;
+      }
+      // The selector runs against the real engine — reads inside it return the
+      // pool's model instances. `snapshotValue` then converts the RESULT to
+      // plain snapshot rows, which is what the selector's `AbloReads`
+      // parameter type already promised.
+      return snapshotValue(modelOrSelect(reactiveReads<R>(engine)) as T);
+    },
+  );
+
+  const modelResult = useReactive<UseAbloModelResult<T>>(
+    () => {
+      void claimVersion;
+      return readModelResult(engine, modelClient, id, initial);
+    },
+  );
+
+  if (isSelectorOnly) return selected;
+  if (modelOrSelect) return modelResult;
+  return engine;
+}

package/src/react/useCurrentUserId.ts

@@ -0,0 +1,17 @@
+'use client';
+
+import { useContext } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+
+/** Returns the application user id supplied to the nearest AbloProvider. */
+export function useCurrentUserId(): string | null {
+  const context = useContext(AbloInternalContext);
+  if (!context) {
+    throw new AbloValidationError(
+      'useCurrentUserId: no <AbloProvider> mounted above this component.',
+      { code: 'no_ablo_provider' },
+    );
+  }
+  return context.currentUserId;
+}

package/src/react/useErrorListener.ts

@@ -0,0 +1,22 @@
+'use client';
+
+import { useContext, useEffect, useRef } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+
+/** Subscribe to provider-level errors without causing component re-renders. */
+export function useErrorListener(listener: (error: Error) => void): void {
+  const context = useContext(AbloInternalContext);
+  if (!context) {
+    throw new AbloValidationError(
+      'useErrorListener: no <AbloProvider> mounted above this component.',
+      { code: 'no_ablo_provider' },
+    );
+  }
+  const listenerRef = useRef(listener);
+  listenerRef.current = listener;
+  useEffect(
+    () => context.subscribeError((error) => listenerRef.current(error)),
+    [context],
+  );
+}