@abloatai/humans 0.63.1 → 0.64.1

package/src/local/client/status.ts

@@ -0,0 +1,20 @@
+import type { SyncStoreContract } from '../storeContract.js';
+
+/** The client lifecycle, shared by every framework binding. */
+export type ClientStatus =
+  | { readonly name: 'initial' }
+  | { readonly name: 'connecting'; readonly progress: number }
+  | { readonly name: 'connected'; readonly hasUnsyncedChanges: boolean }
+  | { readonly name: 'reconnecting'; readonly reason?: string }
+  | { readonly name: 'disconnected'; readonly reason?: string }
+  | { readonly name: 'needs-auth' };
+
+export function readStatus(store: SyncStoreContract): ClientStatus {
+  const { state, progress, pendingChanges, isSessionError, error } = store.syncStatus;
+  if (isSessionError) return { name: 'needs-auth' };
+  if (state === 'reconnecting') return { name: 'reconnecting', reason: error?.message };
+  if (state === 'offline') return { name: 'disconnected', reason: 'offline' };
+  if (state === 'error') return { name: 'disconnected', reason: error?.message };
+  if (store.isReady) return { name: 'connected', hasUnsyncedChanges: pendingChanges > 0 };
+  return { name: 'connecting', progress };
+}

package/src/local/client/storeLifecycle.ts

@@ -301,7 +301,7 @@ export function startStoreLifecycle<S extends SchemaRecord>(
         //
         // The store.initialize() generator updates store.syncStatus as it
         // progresses (syncing → idle on success, error on failure), so the
-        // consumer's `sync.syncStatus` observable reflects real-time state.
+        // consumer's `ablo.status` projection reflects real-time state.
         // Resolve bootstrap mode: explicit option wins; otherwise
         // agents default to 'none' (transactional participant — see
         // option doc) and everyone else defaults to 'full'.
@@ -386,7 +386,7 @@ export function startStoreLifecycle<S extends SchemaRecord>(
   if (!validationError && internalOptions.autoStart) {
     void ready().catch(() => {
       // Error is captured in store.syncStatus; consumers should check
-      // `sync.syncStatus.state === 'error'` to detect failures.
+      // `ablo.status.name === 'disconnected'` to detect failures.
     });
   }
 

package/src/local/mutators/defineMutators.ts

@@ -1,76 +1,28 @@
-/**
- * Declares a tree of named custom mutators grouped by model key. Each mutator is
- * a plain async function that receives `{ tx, args }` and composes any number of
- * `tx.mutations.*` and `tx.read.*` calls to carry out a named operation, such as
- * `sections.createWithBlocks`.
- *
- * The function is purely a place for types to anchor and returns its input
- * unchanged; the runtime that dispatches a mutator lives elsewhere — the
- * transaction object it receives and the React hook that invokes it. Because
- * `defineMutators(schema, { ... })` returns the exact object you wrote,
- * `typeof mutators` carries every mutator's precise `args` and result types
- * through to wherever they are invoked.
- */
-
+/** Define typed named operations. Pass the schema explicitly across package boundaries. */
 import type { Schema } from '@abloatai/transaction/schema/schema';
 import type { Transaction } from './Transaction.js';
-import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import type { ResolveSchema, RequireRegisteredSchema } from '@abloatai/transaction/types/global';
 
-/**
- * `ResolveSchema` narrowed to satisfy the `Schema` bound — mirrors
- * {@link Ablo.RegisteredSchema}. When nothing is registered, `ResolveSchema`
- * is a loose `{ models }` shape that doesn't extend `Schema`, so we fall back
- * to `Schema` to keep the mutator tree typed rather than collapsing.
- */
 type RegisteredSchema = ResolveSchema extends Schema ? ResolveSchema : Schema;
 
-/**
- * The signature of a single custom mutator. The engine supplies `tx`; you control
- * `args`, in whatever shape you like, and the resolved return value. `TArgs` and
- * `TResult` are bounded by `unknown` rather than `any`, so a mixed tree of
- * mutators can be typed together without falling back to `any`.
- */
 export type MutatorFn<S extends Schema, TArgs, TResult = void> = (
   options: { tx: Transaction<S>; args: TArgs },
 ) => Promise<TResult>;
 
-/**
- * The shape {@link defineMutators} accepts: an optional record per model key
- * whose values are named mutator functions. The `unknown` bounds keep the public
- * boundary type-safe without `any`; when you write your mutators inline,
- * TypeScript still infers the concrete `args` and result of each function, so the
- * `unknown` here is only a ceiling, not what you end up working with.
- */
 export type MutatorDefs<S extends Schema> = {
   [K in keyof S['models']]?: Record<string, MutatorFn<S, never, unknown>>;
 };
 
-/**
- * Returns the mutators object unchanged while constraining its shape against the
- * schema. The `S` generic pins the model keys, and the `M` generic is inferred as
- * a `const`, so each mutator's literal signature survives. There is no runtime
- * work here; the function exists purely as a place for type inference to anchor.
- */
 export function defineMutators<
   S extends Schema,
   const M extends MutatorDefs<S>,
 >(_schema: S, mutators: M): M;
-/**
- * Register-anchored overload: omit the schema value and the tree is typed
- * against `ResolveSchema` (this app's registered schema). Shared product code
- * used across apps that bind different schemas should use this form — it moves
- * with each app's `Register` instead of pinning one concrete schema, so the
- * mutator tree stays assignable at every consumer (which reads the same
- * `Register`). See docs/plans/per-product-schema-projections.md.
- */
 export function defineMutators<const M extends MutatorDefs<RegisteredSchema>>(
-  mutators: M,
+  mutators: RequireRegisteredSchema<M>,
 ): M;
 export function defineMutators(
   schemaOrMutators: Schema | MutatorDefs<Schema>,
   maybeMutators?: MutatorDefs<Schema>,
 ): MutatorDefs<Schema> {
-  // The schema argument is a type anchor only — never read at runtime. With one
-  // argument the mutator tree is in the first slot; with two it's in the second.
   return (maybeMutators ?? schemaOrMutators) as MutatorDefs<Schema>;
 }

package/src/local/storeAccess.ts

@@ -0,0 +1,10 @@
+import type { AbloClient } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { SyncStoreContract } from './storeContract.js';
+
+/** Access the supported local store contract for custom framework adapters,
+ * demand loading, scope management and custom undo infrastructure.
+ */
+export function getAbloStore<S extends SchemaRecord>(client: AbloClient<S>): SyncStoreContract {
+  return client._store;
+}

package/src/local/storeContract.ts

@@ -19,8 +19,7 @@ import type { GroupScope } from './sync/scopeGroups.js';
 /**
  * A snapshot of the client's synchronization state, shaped for binding to UI.
  * {@link SyncStoreContract.syncStatus} exposes a reactive instance of this, and
- * the `useSyncStatus()` hook reads its fields to render connection and progress
- * indicators.
+ * the client projects it into `ablo.status` for connection indicators.
  */
 export interface SyncStatus {
   state: 'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting';
@@ -115,7 +114,7 @@ export interface SyncStoreContract {
    * are backed by observable computeds, so reading them inside a reactive
    * context — an observer component or a reaction — re-runs that context when
    * the state changes. Code that prefers not to work with the reactivity system
-   * directly can read the same values through the `useSyncStatus()` hook.
+   * directly can read the same values through `useAblo(ablo => ablo.status)`.
    */
   readonly isReady: boolean;
   readonly isSyncing: boolean;
@@ -137,7 +136,7 @@ export interface SyncStoreContract {
   pinScope?(scope: GroupScope): Promise<void>;
   unpinScope?(scope: GroupScope): Promise<void>;
   /**
-   * The full reactive {@link SyncStatus} record. The `useSyncStatus()` hook
+   * The full reactive {@link SyncStatus} record. The client status projection
    * reads its fields — `state`, `progress`, `pendingChanges`, `isSessionError`,
    * and `error` — to present the current sync state. It is part of the contract
    * so hooks and test doubles can read or set it directly.

package/src/presence/index.ts

@@ -1,8 +1,10 @@
+import { observable, runInAction } from 'mobx';
 import {
   createPresenceProjection,
   type PresenceProjection,
   type PresenceProjectionEvents,
   type PresenceView,
+  type PresenceQueryOptions,
 } from '@abloatai/transaction/presence';
 import type { PresenceTarget } from '@abloatai/transaction/presence';
 import {
@@ -15,7 +17,7 @@ type PresenceTransport = PresenceProjectionEvents & ReadActivityTransport;
 
 /** Reactive-client presence backed by the client's existing live connection. */
 export interface ReactivePresence extends PresenceView {
-  forModel(model: string, recordId?: string): ReturnType<PresenceProjection['forModel']>;
+  forModel(model: string, recordId?: string, options?: PresenceQueryOptions): ReturnType<PresenceProjection['forModel']>;
   onChange(listener: () => void): () => void;
 }
 
@@ -44,11 +46,13 @@ export function createPresence(
 ): AttachablePresence {
   let projection: PresenceProjection | null = null;
   let attachedTransport: PresenceTransport | null = null;
+  const version = observable.box(0);
   const listeners = new Set<() => void>();
   const reads = new Set<ReadActivityLifetime>();
   let unsubscribe: (() => void) | null = null;
 
   const notify = (): void => {
+    runInAction(() => { version.set(version.get() + 1); });
     for (const listener of listeners) listener();
   };
 
@@ -63,8 +67,8 @@ export function createPresence(
   if (transport !== null) attach(transport);
 
   return {
-    get active() { return projection?.active ?? []; },
-    get others() { return projection?.others ?? []; },
+    get active() { version.get(); return projection?.active ?? []; },
+    get others() { version.get(); return projection?.others ?? []; },
     onChange(listener) {
       listeners.add(listener);
       return () => { listeners.delete(listener); };
@@ -84,8 +88,9 @@ export function createPresence(
         lifetime.stop();
       };
     },
-    forModel(model, recordId) {
-      return projection?.forModel(model, recordId) ?? [];
+    forModel(model, recordId, options) {
+      version.get();
+      return projection?.forModel(model, recordId, options) ?? [];
     },
     dispose() {
       for (const read of reads) read.dispose();