@abloatai/humans 0.37.0

package/dist/react/useUndoScope.d.ts

@@ -0,0 +1,34 @@
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import { type UndoScope, type UndoScopeOptions } from '../local/mutators/UndoManager.js';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+/**
+ * Provides per-surface undo and redo for mutator invocations. Each named scope
+ * owns an independent undo/redo stack, so different parts of your app — a main
+ * editor, a sidebar form — can undo separately without stepping on each other.
+ *
+ * Wire the returned `scope` into `useMutators(schema, mutators, { undoScope:
+ * scope })` and those invocations become recorded. `undo()` and `redo()` replay
+ * the captured inverses and forwards as new transactions that do not record
+ * themselves; the manager moves the entry between the two stacks explicitly.
+ *
+ * @example
+ * const { undo, redo, canUndo, canRedo, scope } = useUndoScope('report-editor');
+ * const mutate = useMutators(schema, reportMutators, { undoScope: scope });
+ *
+ * // Cmd+Z handler
+ * useHotkey('mod+z', () => { if (canUndo) void undo(); });
+ */
+export interface UseUndoScopeResult<S extends Schema> {
+    /** Pass to `useMutators(..., { undoScope })` to enable recording. */
+    scope: UndoScope<S>;
+    undo: () => Promise<void>;
+    redo: () => Promise<void>;
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Drop history. Use after sync errors / auth context changes. */
+    clear: () => void;
+}
+/** Per-surface undo/redo (explicit schema arg). */
+export declare function useUndoScope<S extends Schema>(schema: S, name: string, options?: UndoScopeOptions): UseUndoScopeResult<S>;
+/** Per-surface undo/redo via the `Register` module augmentation. */
+export declare function useUndoScope(name: string, options?: UndoScopeOptions): UseUndoScopeResult<ResolveSchema extends Schema ? ResolveSchema : Schema>;

package/dist/react/useUndoScope.js

@@ -0,0 +1,73 @@
+'use client';
+import { useEffect, useMemo, useState } from 'react';
+import { UndoManager, } from '../local/mutators/UndoManager.js';
+import { useSyncContext } from './context.js';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+// Module-level weak registry: `SyncStoreContract` → `UndoManager`.
+// A single app wiring through one SyncProvider shares one manager across
+// every useUndoScope call, so scopes with the same name are identity-equal.
+// The hook implementation already operates on the runtime-wide `Schema` type;
+// its overloads restore the caller's precise schema type at the public boundary,
+// so the registry can keep that same non-generic runtime representation.
+const managers = new WeakMap();
+function getManager(key, factory) {
+    let m = managers.get(key);
+    if (!m) {
+        const created = factory();
+        managers.set(key, created);
+        m = created;
+    }
+    return m;
+}
+export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
+    const { store, organizationId, schema: ctxSchema } = useSyncContext();
+    const isExplicit = typeof schemaOrName !== 'string';
+    const schema = isExplicit ? (schemaOrName) : ctxSchema;
+    const name = isExplicit ? nameOrOptions : schemaOrName;
+    const options = (isExplicit ? maybeOptions : nameOrOptions);
+    if (!schema) {
+        throw new AbloValidationError('useUndoScope: no schema available. Pass the schema as the first arg, ' +
+            'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
+            'zero-arg overload can read it from context.', { code: 'undo_scope_schema_missing' });
+    }
+    const scope = useMemo(() => {
+        // Store is the identity for the manager — one per SyncProvider.
+        const manager = getManager(store, () => new UndoManager(schema, store, organizationId));
+        return manager.getScope(name, options);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store, organizationId, name]);
+    // Local tick forces re-render after undo/redo/clear so canUndo/canRedo
+    // reflect the new stack sizes. The scope itself doesn't emit React-
+    // friendly notifications; callers that want cross-component reactivity
+    // can wire a mobx observable or custom event bus on top.
+    const [, setTick] = useState(0);
+    // Reset tick when scope identity changes (new store / new orgId).
+    useEffect(() => {
+        setTick(0);
+    }, [scope]);
+    // Re-render on any stack change — including entries recorded from the local-
+    // mutation stream, which don't otherwise trigger a React update. Without this
+    // `canUndo`/`canRedo` go stale in every consumer that didn't itself call
+    // undo/redo (e.g. a keyboard handler whose Cmd+Z gate then never fires).
+    useEffect(() => {
+        return scope.onChange(() => { setTick((t) => t + 1); });
+    }, [scope]);
+    const size = scope.size();
+    return {
+        scope,
+        undo: async () => {
+            await scope.undo();
+            setTick((t) => t + 1);
+        },
+        redo: async () => {
+            await scope.redo();
+            setTick((t) => t + 1);
+        },
+        canUndo: size.undo > 0,
+        canRedo: size.redo > 0,
+        clear: () => {
+            scope.clear();
+            setTick((t) => t + 1);
+        },
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,18 @@
+/** React bindings for the optional human-facing local-state package. */
+export { useReactive } from './useReactive.js';
+export { useCurrentUserId } from './react/useCurrentUserId.js';
+export { useErrorListener } from './react/useErrorListener.js';
+export { useSyncStatus, type SyncStatusSnapshot } from './react/useSyncStatus.js';
+export { useMutationFailureListener, type MutationFailurePayload, } from './react/useMutationFailureListener.js';
+export { AbloProvider, useJoin, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseJoinOptions, type UseJoinReturn, } from './react/AbloProvider.js';
+export { ClientSideSuspense, type ClientSideSuspenseProps, } from './react/ClientSideSuspense.js';
+export { DefaultFallback } from './react/DefaultFallback.js';
+export { createAbloReact, type AbloReactBinding, } from './react/createAbloReact.js';
+export { useAblo, type UseAbloHydratedModelResult, type UseAbloModelOptions, type UseAbloModelResult, } from './react/useAblo.js';
+export { useMutators, type InvokerFor, type MutatorInvokers, type UseMutatorsOptions, } from './react/useMutators.js';
+export { useUndoScope, type UseUndoScopeResult, } from './react/useUndoScope.js';
+export type { DefaultSyncShape, ResolveSchema, ResolveUserMeta, ResolveClaimMeta, ResolveModelKey, } from '@abloatai/transaction/types/global';
+export { ModelScope } from '@abloatai/transaction/types';
+export type { SyncStoreContract } from './react/context.js';
+export type { MutateActions } from './local/mutators/mutateActions.js';
+export type { ReaderActions, ReaderFindOptions, } from './local/mutators/readerActions.js';

package/dist/react.js

@@ -0,0 +1,14 @@
+/** React bindings for the optional human-facing local-state package. */
+export { useReactive } from './useReactive.js';
+export { useCurrentUserId } from './react/useCurrentUserId.js';
+export { useErrorListener } from './react/useErrorListener.js';
+export { useSyncStatus } from './react/useSyncStatus.js';
+export { useMutationFailureListener, } from './react/useMutationFailureListener.js';
+export { AbloProvider, useJoin, usePeers, useSync, useSyncStore, } from './react/AbloProvider.js';
+export { ClientSideSuspense, } from './react/ClientSideSuspense.js';
+export { DefaultFallback } from './react/DefaultFallback.js';
+export { createAbloReact, } from './react/createAbloReact.js';
+export { useAblo, } from './react/useAblo.js';
+export { useMutators, } from './react/useMutators.js';
+export { useUndoScope, } from './react/useUndoScope.js';
+export { ModelScope } from '@abloatai/transaction/types';

package/dist/reactRuntime.d.ts

@@ -0,0 +1,4 @@
+export { AbloInternalContext, type AbloInternalContextValue, } from './react/internalContext.js';
+export { useSyncContext, type SyncReactContext, } from './react/context.js';
+export type { SyncStoreContract } from './local/storeContract.js';
+export type { QueuedMutation } from './local/transactions/mutations/MutationQueue.js';

package/dist/reactRuntime.js

@@ -0,0 +1,2 @@
+export { AbloInternalContext, } from './react/internalContext.js';
+export { useSyncContext, } from './react/context.js';

package/dist/surface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A machine-checked manifest of this package's public API surface. It lists,
+ * as string tuples, the method names on `ablo.<model>`, the keys accepted by
+ * the list-style read options, and the keys of the client constructor
+ * options. Each tuple is proven equal to the keys of its source interface at
+ * compile time, so the lists cannot drift from the real types: add or remove
+ * a name on either side without updating the matching tuple and this file
+ * fails to compile, in both directions — no name the interface lacks, and no
+ * interface key the tuple omits.
+ *
+ * Documentation tooling reads these tuples to describe the surface, which
+ * guarantees a generated summary never names a method or option that does
+ * not exist. The names are verified here; their prose descriptions are
+ * written by hand, since prose cannot be type-checked.
+ */
+/**
+ * The names of every method available on `ablo.<model>`, matching the keys of
+ * the {@link ModelOperations} interface. Documentation tooling reads this
+ * tuple, so it is the one list of model-verb names a generated summary can
+ * describe.
+ */
+export declare const PUBLIC_MODEL_VERBS: readonly ["get", "retrieve", "list", "local", "create", "update", "delete", "claim", "track", "join", "onChange"];
+/**
+ * The option keys accepted by `local.list` and `onChange`, matching the
+ * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
+ * `state`, not `scope`.
+ */
+export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
+/**
+ * The keys of the client constructor options, {@link AbloOptions}. Only
+ * `schema` is required; every other key is optional.
+ */
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "authEndpoint", "authTimeoutMs", "allowCrossOriginAuthEndpoint", "persistence", "durableWrites", "commitOutbox", "commitOutboxScope", "debug", "logLevel", "logger", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser", "collaborationEvents", "plugins", "wait"];
+export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
+export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
+export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -0,0 +1,77 @@
+/**
+ * A machine-checked manifest of this package's public API surface. It lists,
+ * as string tuples, the method names on `ablo.<model>`, the keys accepted by
+ * the list-style read options, and the keys of the client constructor
+ * options. Each tuple is proven equal to the keys of its source interface at
+ * compile time, so the lists cannot drift from the real types: add or remove
+ * a name on either side without updating the matching tuple and this file
+ * fails to compile, in both directions — no name the interface lacks, and no
+ * interface key the tuple omits.
+ *
+ * Documentation tooling reads these tuples to describe the surface, which
+ * guarantees a generated summary never names a method or option that does
+ * not exist. The names are verified here; their prose descriptions are
+ * written by hand, since prose cannot be type-checked.
+ */
+// ── the per-`ablo.<model>` verb surface ────────────────────────────────────
+/**
+ * The names of every method available on `ablo.<model>`, matching the keys of
+ * the {@link ModelOperations} interface. Documentation tooling reads this
+ * tuple, so it is the one list of model-verb names a generated summary can
+ * describe.
+ */
+export const PUBLIC_MODEL_VERBS = [
+    'get',
+    'retrieve',
+    'list',
+    'local',
+    'create',
+    'update',
+    'delete',
+    'claim',
+    'track',
+    'join',
+    'onChange',
+];
+// ── the read/list query option surface ─────────────────────────────────────
+/**
+ * The option keys accepted by `local.list` and `onChange`, matching the
+ * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named
+ * `state`, not `scope`.
+ */
+export const PUBLIC_LIST_OPTION_KEYS = [
+    'where',
+    'filter',
+    'orderBy',
+    'limit',
+    'offset',
+    'state',
+];
+// ── the `Ablo({ … })` constructor option surface ───────────────────────────
+/**
+ * The keys of the client constructor options, {@link AbloOptions}. Only
+ * `schema` is required; every other key is optional.
+ */
+export const PUBLIC_ABLO_OPTION_KEYS = [
+    'schema',
+    'apiKey',
+    'authEndpoint',
+    'authTimeoutMs',
+    'allowCrossOriginAuthEndpoint',
+    'persistence',
+    'durableWrites',
+    'commitOutbox',
+    'commitOutboxScope',
+    'debug',
+    'logLevel',
+    'logger',
+    'authToken',
+    'baseURL',
+    'fetch',
+    'defaultHeaders',
+    'defaultQuery',
+    'dangerouslyAllowBrowser',
+    'collaborationEvents',
+    'plugins',
+    'wait',
+];

package/dist/useReactive.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Subscribe a React component to a MobX computation with a cached snapshot.
+ * This is the framework-level reactive primitive owned by @abloatai/humans;
+ * store/model hooks are layered above it.
+ */
+export declare function useReactive<T>(compute: () => T, equals?: (a: T, b: T) => boolean): T;

package/dist/useReactive.js

@@ -0,0 +1,43 @@
+'use client';
+import { useCallback, useRef } from 'react';
+import { useSyncExternalStore } from 'react';
+import { reaction } from 'mobx';
+/**
+ * Subscribe a React component to a MobX computation with a cached snapshot.
+ * This is the framework-level reactive primitive owned by @abloatai/humans;
+ * store/model hooks are layered above it.
+ */
+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() };
+    }
+    else if (computeRef.current !== compute) {
+        const next = compute();
+        if (!equals(snapshotRef.current.value, next)) {
+            snapshotRef.current = { value: next };
+            versionRef.current++;
+        }
+    }
+    computeRef.current = compute;
+    const subscribe = useCallback((onChange) => reaction(() => computeRef.current(), (next) => {
+        const current = snapshotRef.current.value;
+        if (!equalsRef.current(current, next)) {
+            snapshotRef.current = { value: next };
+            onChange();
+        }
+    }), [versionRef.current]);
+    const getSnapshot = useCallback(() => snapshotRef.current.value, []);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function defaultEquals(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+        return false;
+    return a.every((value, index) => Object.is(value, b[index]));
+}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@abloatai/humans",
+  "version": "0.37.0",
+  "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
+    "./react-runtime": {
+      "types": "./dist/reactRuntime.d.ts",
+      "import": "./dist/reactRuntime.js",
+      "default": "./dist/reactRuntime.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
+    "./surface": {
+      "types": "./dist/surface.d.ts",
+      "import": "./dist/surface.js",
+      "default": "./dist/surface.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js",
+      "default": "./dist/core.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/local/testing/**",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "prepack": "npm run build && node ../ablo/scripts/strip-source-condition.mjs",
+    "postpack": "node ../ablo/scripts/restore-source-condition.mjs",
+    "pack:check": "node ../ablo/scripts/pack-check.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "jest",
+    "test:unit": "jest --testPathPatterns=__tests__/unit",
+    "test:contract": "jest --testPathPatterns=__tests__/contract",
+    "test:property": "jest --testPathPatterns=__tests__/property",
+    "test:migrated-integration": "jest --testPathPatterns=__tests__/integration",
+    "test:e2e": "E2E_TEST=true jest --config jest.e2e.config.ts",
+    "lint:eslint": "eslint . --cache",
+    "check:boundary": "node scripts/check-boundary.mjs",
+    "test:integration": "npm run build && node scripts/check-package-integration.mjs",
+    "lint:pkg": "publint"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abloatai/ablo.git",
+    "directory": "packages/humans"
+  },
+  "dependencies": {
+    "@abloatai/transaction": "^0.37.0",
+    "mobx": "^6.13.7",
+    "uuid": "^11.1.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "react": "^19.2.8"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.0.0",
+    "eslint-plugin-react-hooks": "^7.0.0",
+    "fake-indexeddb": "^6.0.0",
+    "fast-check": "^3.0.0",
+    "globals": "^16.5.0",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "jest-environment-node": "^30.2.0",
+    "publint": "^0.3.17",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "ts-jest": "^29.4.5",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "ws": "^8.18.3"
+  }
+}