@abloatai/ablo 0.10.1 → 0.11.0

package/dist/react/index.d.ts

@@ -30,7 +30,7 @@
  *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
  *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
  *   usePresence()             — typed presence view
- *   useIntent(name)           — typed intent dispatcher
+ *   useClaim(name)           — typed claim dispatcher
  *
  * ── Breaking changes from v0.2.x ───────────────────────────────────
  * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
@@ -43,8 +43,8 @@
  * Changed: useSyncStatus() now returns a discriminated union. See the
  *   migration notes in CHANGELOG.md.
  */
-export type { DefaultSyncShape, ResolveSchema, ResolvePresence, ResolveIntents, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
-export { AbloProvider, useParticipant, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseParticipantOptions, type UseParticipantReturn, type MeshParticipantStatus, } from './AbloProvider.js';
+export type { DefaultSyncShape, ResolveSchema, ResolvePresence, ResolveClaims, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
+export { AbloProvider, useParticipant, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseParticipantOptions, type UseParticipantReturn, type MeshParticipantStatus, } from './AbloProvider.js';
 export { SyncGroupProvider, useSyncGroup, type SyncGroupProviderProps, } from './SyncGroupProvider.js';
 export { ClientSideSuspense, type ClientSideSuspenseProps, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
@@ -60,5 +60,5 @@ export { useMutators, type MutatorInvokers, type InvokerFor, type UseMutatorsOpt
 export { useUndoScope, type UseUndoScopeResult } from './useUndoScope.js';
 export { useAblo, type UseAbloHydratedModelResult, type UseAbloModelOptions, type UseAbloModelResult, } from './useAblo.js';
 export { usePresence } from './usePresence.js';
-export { useIntent } from './useIntent.js';
+export { useClaim } from './useClaim.js';
 export { ModelScope } from '../types/index.js';

package/dist/react/index.js

@@ -30,7 +30,7 @@
  *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
  *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
  *   usePresence()             — typed presence view
- *   useIntent(name)           — typed intent dispatcher
+ *   useClaim(name)           — typed claim dispatcher
  *
  * ── Breaking changes from v0.2.x ───────────────────────────────────
  * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
@@ -44,7 +44,7 @@
  *   migration notes in CHANGELOG.md.
  */
 // ── Umbrella provider + lifecycle hooks ────────────────────────────
-export { AbloProvider, useParticipant, useSync, useSyncStore, } from './AbloProvider.js';
+export { AbloProvider, useParticipant, usePeers, useSync, useSyncStore, } from './AbloProvider.js';
 export { SyncGroupProvider, useSyncGroup, } from './SyncGroupProvider.js';
 export { ClientSideSuspense, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
@@ -63,8 +63,8 @@ export { useReactive } from './useReactive.js';
 export { useMutators, } from './useMutators.js';
 export { useUndoScope } from './useUndoScope.js';
 export { useAblo, } from './useAblo.js';
-// ── Presence + intent (typed via Register module augmentation) ─────
+// ── Presence + claim (typed via Register module augmentation) ─────
 export { usePresence } from './usePresence.js';
-export { useIntent } from './useIntent.js';
+export { useClaim } from './useClaim.js';
 // ── ModelScope re-export ───────────────────────────────────────────
 export { ModelScope } from '../types/index.js';

package/dist/react/useAblo.js

@@ -12,7 +12,7 @@ function readModelResult(engine, modelClient, id, initial) {
     const data = snapshotValue(modelClient.get(id) ?? initial);
     const meta = getModelClientMeta(modelClient);
     const claims = meta && engine
-        ? engine.intents.list({ model: meta.key, id })
+        ? engine.claims.list({ model: meta.key, id })
         : EMPTY_CLAIMS;
     return { data, claims, claimed: claims.length > 0 };
 }
@@ -37,18 +37,18 @@ export function useAblo(modelOrSelect, id, options) {
         : typeof modelOrSelect === 'function'
             ? undefined
             : modelOrSelect;
-    // Claims live on a non-MobX event emitter (engine.intents), so the useReactive
+    // Claims live on a non-MobX event emitter (engine.claims), so the useReactive
     // reactions below cannot track them — we bridge changes through a setState bump.
     // ONLY the model-row form (`id !== undefined`) actually reads claims, so gate the
     // subscription on `id`. The selector-only form (`useAblo((a) => a.x.get/getAll)`)
-    // never reads claims; subscribing it to the workspace-global intent stream would
-    // re-render + double-compute it on every intent/presence delta anywhere (a real
+    // never reads claims; subscribing it to the workspace-global claim stream would
+    // re-render + double-compute it on every claim/presence delta anywhere (a real
     // storm during AI editing / live collaboration) for a value that can't change.
     const [claimVersion, setClaimVersion] = useState(0);
     useEffect(() => {
         if (!engine || id === undefined)
             return;
-        return engine.intents.onChange(() => setClaimVersion((version) => version + 1));
+        return engine.claims.onChange(() => setClaimVersion((version) => version + 1));
     }, [engine, id]);
     const selected = useReactive(() => {
         if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {

package/dist/react/{useIntent.d.ts → useClaim.d.ts}

@@ -1,13 +1,13 @@
-import type { ResolveIntents } from '../types/global.js';
+import type { ResolveClaims } from '../types/global.js';
 /**
- * Named-intent invoker, typed via `ResolveIntents[IntentName]`.
+ * Named-claim invoker, typed via `ResolveClaims[ClaimName]`.
  *
- * The consumer declares their intent vocabulary in the global:
+ * The consumer declares their claim vocabulary in the global:
  *
  * ```ts
  * declare module '@abloatai/ablo' {
  *   interface Register {
- *     Intents: {
+ *     Claims: {
  *       editLayer: { slideId: string; layerId: string };
  *       generateWithAI: { entityId: string; tool: string };
  *     };
@@ -15,15 +15,15 @@ import type { ResolveIntents } from '../types/global.js';
  * }
  * ```
  *
- * Then `useIntent('editLayer')` returns a function whose sole argument
+ * Then `useClaim('editLayer')` returns a function whose sole argument
  * is the `editLayer` claim shape — no runtime checks, purely compile-
  * time narrowing.
  *
- * The SDK doesn't own what happens next: the `beginIntent` function on
- * the React context (supplied via `SyncProvider`) is where the intent
+ * The SDK doesn't own what happens next: the `beginClaim` function on
+ * the React context (supplied via `SyncProvider`) is where the claim
  * claim turns into a network effect. A Node-backed consumer wires it
- * through `SyncAgent.beginIntent`; a browser-backed consumer may
+ * through `SyncAgent.beginClaim`; a browser-backed consumer may
  * broadcast it through their own WebSocket. This hook is pure sugar
  * that adds the typed name + claim narrowing.
  */
-export declare function useIntent<Name extends keyof ResolveIntents & string>(intentName: Name): (claim: ResolveIntents[Name]) => unknown;
+export declare function useClaim<Name extends keyof ResolveClaims & string>(claimName: Name): (claim: ResolveClaims[Name]) => unknown;

package/dist/react/useClaim.js

@@ -0,0 +1,42 @@
+'use client';
+import { useCallback } from 'react';
+import { useSyncContext } from './context.js';
+import { AbloValidationError } from '../errors.js';
+/**
+ * Named-claim invoker, typed via `ResolveClaims[ClaimName]`.
+ *
+ * The consumer declares their claim vocabulary in the global:
+ *
+ * ```ts
+ * declare module '@abloatai/ablo' {
+ *   interface Register {
+ *     Claims: {
+ *       editLayer: { slideId: string; layerId: string };
+ *       generateWithAI: { entityId: string; tool: string };
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * Then `useClaim('editLayer')` returns a function whose sole argument
+ * is the `editLayer` claim shape — no runtime checks, purely compile-
+ * time narrowing.
+ *
+ * The SDK doesn't own what happens next: the `beginClaim` function on
+ * the React context (supplied via `SyncProvider`) is where the claim
+ * claim turns into a network effect. A Node-backed consumer wires it
+ * through `SyncAgent.beginClaim`; a browser-backed consumer may
+ * broadcast it through their own WebSocket. This hook is pure sugar
+ * that adds the typed name + claim narrowing.
+ */
+export function useClaim(claimName) {
+    const { beginClaim } = useSyncContext();
+    return useCallback((claim) => {
+        if (!beginClaim) {
+            throw new AbloValidationError(`useClaim: no \`beginClaim\` wired into SyncProvider. Pass ` +
+                `a \`beginClaim\` prop (typically bound to your transport) ` +
+                `to enable claim invocations.`, { code: 'claim_not_wired' });
+        }
+        return beginClaim(claimName, claim);
+    }, [beginClaim, claimName]);
+}

package/dist/schema/index.js

@@ -41,7 +41,7 @@ export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syn
 export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './sync-delta-wire.js';
 // Model builder
 export { model, scopeKindOf, } from './model.js';
-// Intent-first shorthand: `mutable.lazy({...})` and friends. Read the
+// Claim-first shorthand: `mutable.lazy({...})` and friends. Read the
 // safety posture and load shape off the verb tokens; everything else
 // falls back to sensible defaults. See sugar.ts for the full pattern.
 export { mutable, readOnly } from './sugar.js';

package/dist/schema/sugar.d.ts

@@ -1,5 +1,5 @@
 /**
- * Intent-first shorthand for `model(...)` — the Modal-inspired DX layer.
+ * Claim-first shorthand for `model(...)` — the Modal-inspired DX layer.
  *
  * The factory verbs encode the two orthogonal axes that matter for
  * safety and bootstrap behavior:
@@ -12,7 +12,7 @@
  *     `.lazy` loads on first access, `.manual` requires explicit
  *     queries.
  *
- * The two-token form (`mutable.lazy({...})`) reads the safety intent
+ * The two-token form (`mutable.lazy({...})`) reads the safety claim
  * in the first token and the load shape in the second — you know both
  * key facts about the entity before scanning its fields.
  *
@@ -28,7 +28,7 @@
  *   load: 'lazy', lazyObservable: true, computed: tasksComputed,
  * }),
  *
- * // After — intent reads off the verb; options carry only the
+ * // After — claim reads off the verb; options carry only the
  * // fields that actually diverge from defaults
  * tasks: mutable.lazy({ title: z.string() }, {
  *   typename: 'Task', tableName: 'tasks',

package/dist/schema/sugar.js

@@ -1,5 +1,5 @@
 /**
- * Intent-first shorthand for `model(...)` — the Modal-inspired DX layer.
+ * Claim-first shorthand for `model(...)` — the Modal-inspired DX layer.
  *
  * The factory verbs encode the two orthogonal axes that matter for
  * safety and bootstrap behavior:
@@ -12,7 +12,7 @@
  *     `.lazy` loads on first access, `.manual` requires explicit
  *     queries.
  *
- * The two-token form (`mutable.lazy({...})`) reads the safety intent
+ * The two-token form (`mutable.lazy({...})`) reads the safety claim
  * in the first token and the load shape in the second — you know both
  * key facts about the entity before scanning its fields.
  *
@@ -28,7 +28,7 @@
  *   load: 'lazy', lazyObservable: true, computed: tasksComputed,
  * }),
  *
- * // After — intent reads off the verb; options carry only the
+ * // After — claim reads off the verb; options carry only the
  * // fields that actually diverge from defaults
  * tasks: mutable.lazy({ title: z.string() }, {
  *   typename: 'Task', tableName: 'tasks',

package/dist/schema/sync-delta-wire.d.ts

@@ -32,14 +32,14 @@ import { z } from 'zod';
  * `S` groupRemoved.
  */
 export declare const syncDeltaActionSchema: z.ZodEnum<{
-    A: "A";
     I: "I";
     U: "U";
     D: "D";
+    A: "A";
+    V: "V";
     C: "C";
     G: "G";
     S: "S";
-    V: "V";
 }>;
 export type SyncDeltaAction = z.infer<typeof syncDeltaActionSchema>;
 /**
@@ -73,14 +73,14 @@ export type ParticipantRef = z.infer<typeof participantRefSchema>;
 export declare const syncDeltaWireCoreSchema: z.ZodObject<{
     id: z.ZodNumber;
     actionType: z.ZodEnum<{
-        A: "A";
         I: "I";
         U: "U";
         D: "D";
+        A: "A";
+        V: "V";
         C: "C";
         G: "G";
         S: "S";
-        V: "V";
     }>;
     modelName: z.ZodString;
     modelId: z.ZodString;
@@ -98,14 +98,14 @@ export type SyncDeltaWireCore = z.infer<typeof syncDeltaWireCoreSchema>;
 export declare const clientSyncDeltaSchema: z.ZodObject<{
     id: z.ZodNumber;
     actionType: z.ZodEnum<{
-        A: "A";
         I: "I";
         U: "U";
         D: "D";
+        A: "A";
+        V: "V";
         C: "C";
         G: "G";
         S: "S";
-        V: "V";
     }>;
     modelName: z.ZodString;
     modelId: z.ZodString;
@@ -127,14 +127,14 @@ export type ClientSyncDelta = z.infer<typeof clientSyncDeltaSchema>;
 export declare const serverSyncDeltaSchema: z.ZodObject<{
     id: z.ZodNumber;
     actionType: z.ZodEnum<{
-        A: "A";
         I: "I";
         U: "U";
         D: "D";
+        A: "A";
+        V: "V";
         C: "C";
         G: "G";
         S: "S";
-        V: "V";
     }>;
     modelName: z.ZodString;
     modelId: z.ZodString;

package/dist/server/commit.d.ts

@@ -1,7 +1,7 @@
 /**
  * `@abloatai/ablo/server` — the COMMIT contract types.
  *
- * `CommitContext` is the attribution/intent envelope the host's commit executor
+ * `CommitContext` is the attribution/claim envelope the host's commit executor
  * stamps onto every delta a batch produces; `CommitResult` is the receipt. Both
  * are PURE descriptors (no `postgres`, no SQL, no functions), which is why they
  * live in the portable package while the SQL engine that consumes them
@@ -76,7 +76,7 @@ export interface CommitContext {
     confirmationState?: ConfirmationState;
     /**
      * Dormant FK to the agent-task id (`agent_tasks.id`). The SDK no longer
-     * sets it (turns/tasks removed; attribution rides on the claim/intent id
+     * sets it (turns/tasks removed; attribution rides on the claim/claim id
      * + server-stamped actor/capability). Still validated + written onto
      * `caused_by_task_id` when present, but client writes leave it `null`.
      */

package/dist/sync/AreaOfInterestManager.d.ts

@@ -0,0 +1,162 @@
+/**
+ * AreaOfInterestManager — client-side hysteresis + prominence policy over
+ * the `update_subscription` read primitive.
+ *
+ * Game netcode never thrashes its area-of-interest on a boundary: a cell
+ * you walk out of stays subscribed for a margin before it's dropped
+ * (hysteresis), and "important" entities stay relevant from farther away
+ * (prominence). This manager applies both to Ablo sync groups:
+ *
+ *   - `enter(group)` / `leave(group)` move read interest as the user opens
+ *     and closes entities (decks, sheets, docs). A `leave` does NOT
+ *     immediately unsubscribe — the group goes WARM with a TTL and stays
+ *     in the effective set. Re-entering within the window is a no-op
+ *     (already subscribed → no bootstrap), and only when the warm TTL
+ *     lapses does the group actually drop. This is the boundary hysteresis
+ *     that turns deck-tab flipping from a re-bootstrap storm into a
+ *     cache hit.
+ *
+ *   - `pin(group)` / `unpin(group)` express prominence: a group that holds
+ *     an active claim (write-claim) is pinned and never goes warm or
+ *     expires while pinned. The claim machinery is the prominence oracle —
+ *     the row two agents are fighting over stays subscribed regardless of
+ *     navigation.
+ *
+ *   - `baseGroups` are permanent infrastructure scopes (e.g. `org:<id>`,
+ *     `user:<id>`) that are always in the effective set.
+ *
+ * The effective set is recomputed and diffed against what was last sent;
+ * the transport's `update_subscription` is only called when it actually
+ * changes, so hysteresis genuinely suppresses network churn rather than
+ * just deferring it.
+ *
+ * Transport-agnostic: it depends only on {@link SubscriptionTransport},
+ * which `SyncWebSocket` satisfies structurally. `now` and the sweep timer
+ * are injectable so the policy is deterministic under test.
+ */
+/** The single capability this manager needs from the connection. */
+export interface SubscriptionTransport {
+    /**
+     * Replace the connection's read interest with the COMPLETE group set.
+     * Resolves with the server's effective set (which the manager treats as
+     * authoritative for its next diff).
+     */
+    updateSubscription(syncGroups: ReadonlyArray<string>): Promise<{
+        syncGroups: string[];
+    }>;
+}
+export interface AreaOfInterestOptions {
+    /** Connection to drive. `SyncWebSocket` satisfies this structurally. */
+    transport: SubscriptionTransport;
+    /**
+     * Groups always present in the effective set (e.g. `org:<id>`,
+     * `user:<id>`). Never warm, never expired.
+     */
+    baseGroups?: ReadonlyArray<string>;
+    /**
+     * How long a `leave`-ed group stays subscribed before it actually drops.
+     * This is the hysteresis margin. Default 30s.
+     */
+    warmTtlMs?: number;
+    /**
+     * Maximum number of warm (left-but-still-subscribed) groups. Under heavy
+     * navigation — opening and closing many entities quickly — warm groups
+     * would otherwise pile up until each TTL lapses, inflating the connection's
+     * subscription set. When the cap is exceeded, the LEAST-recently-warmed
+     * group is evicted immediately (dropped) instead of waiting for its TTL.
+     * This is the bounded relevant-set discipline from game netcode. Default 16.
+     */
+    maxWarm?: number;
+    /**
+     * Auto-run the warm-expiry sweep on this cadence. Set `0` to disable and
+     * drive {@link AreaOfInterestManager.sweep} yourself (tests do this).
+     * Default = `warmTtlMs` (checks about once per margin).
+     */
+    sweepIntervalMs?: number;
+    /** Clock injection point for deterministic tests. Default `Date.now`. */
+    now?: () => number;
+    /**
+     * Schedule a periodic callback. Default wraps `setInterval`/
+     * `clearInterval`. Injected so tests avoid real timers.
+     */
+    scheduler?: (fn: () => void, intervalMs: number) => () => void;
+}
+export declare class AreaOfInterestManager {
+    private readonly transport;
+    private readonly baseGroups;
+    private readonly warmTtlMs;
+    private readonly maxWarm;
+    private readonly now;
+    /** Groups currently in view (open entities). */
+    private readonly active;
+    /** Claim-pinned groups — prominence; never warm/expire while pinned. */
+    private readonly pinned;
+    /** Left-but-warm groups → epoch-ms at which they drop. */
+    private readonly warm;
+    /** Last set the transport confirmed — the diff baseline. */
+    private lastSent;
+    /** Coalescing state so concurrent mutations collapse into one in-flight call. */
+    private inFlight;
+    private dirty;
+    private readonly cancelSweep;
+    constructor(options: AreaOfInterestOptions);
+    /**
+     * Move a group into the warm set with a fresh TTL, maintaining LRU order
+     * and the `maxWarm` cap. JS `Map` preserves insertion order, so deleting
+     * then re-setting moves the group to the most-recently-warmed position;
+     * eviction then drops from the front (oldest). Base/pinned groups never
+     * warm — callers guard before calling this.
+     */
+    private warmGroup;
+    /** The effective read set: base ∪ active ∪ pinned ∪ (warm not yet expired). */
+    private desiredGroups;
+    /** Bring a group into view. Cancels any warm timer for it. Idempotent. */
+    enter(group: string): Promise<void>;
+    /**
+     * Leave a group. It does not drop immediately — it goes warm for
+     * `warmTtlMs` (unless pinned, in which case it stays via the pin).
+     * Re-entering within the window is free.
+     */
+    leave(group: string): Promise<void>;
+    /** Pin a group (active claim / prominence). Never warm or expires while pinned. */
+    pin(group: string): Promise<void>;
+    /**
+     * Unpin a group. If it's not currently in view, it transitions to warm
+     * (so dropping a claim gets the same hysteresis as closing a tab) rather
+     * than dropping instantly.
+     */
+    unpin(group: string): Promise<void>;
+    /**
+     * Drop warm groups whose TTL has lapsed and reconcile. Auto-invoked on
+     * the sweep timer; call manually (with an injected `now`) in tests.
+     */
+    sweep(): Promise<void>;
+    /** The set the manager believes is subscribed (post-confirmation). */
+    effectiveGroups(): string[];
+    /**
+     * Re-assert the full desired set against the transport, forgetting what
+     * was previously confirmed. Call after a reconnect: a fresh
+     * `SyncWebSocket` instance starts from the connect-time URL groups, so
+     * the manager's `lastSent` diff baseline is stale. Clearing it forces
+     * one `update_subscription` that re-establishes the live interest on the
+     * new socket.
+     *
+     * Resetting `lastSent` makes the next reconcile unconditionally re-push
+     * the current desired set (one `update_subscription` frame) so the fresh
+     * socket's server-side index matches local interest, even if warm/pinned
+     * groups drifted across the disconnect window. The connect-time URL
+     * already carries the last-acked set, so this is a correction frame, not
+     * the primary mechanism.
+     */
+    resync(): Promise<void>;
+    /** Stop the sweep timer. The connection is unaffected. */
+    dispose(): void;
+    /**
+     * Push the desired set to the transport iff it differs from the last
+     * confirmed set. Coalesces concurrent mutations: if a call is already in
+     * flight, mark dirty and let the in-flight loop pick up the newest state
+     * — so a burst of enter/leave collapses into the minimum number of
+     * `update_subscription` round-trips.
+     */
+    private reconcile;
+}