@luckystack/sync 0.10.2 → 0.12.0

package/dist/streamThrottle.d.ts

@@ -0,0 +1,45 @@
+export interface CreateStreamThrottleOptions {
+    /**
+     * Flush buffered text once it crosses this many characters. Default: 32.
+     * Lower = more updates, more network traffic.
+     * Higher = fewer updates, choppier UI.
+     */
+    flushAtChars?: number;
+    /**
+     * Flush buffered text after this many milliseconds even if the char
+     * threshold hasn't been hit. Default: 50ms — fast enough that the user
+     * perceives "live typing", slow enough that 50–100 tokens batch into a
+     * single message on a fast LLM stream.
+     *
+     * Set to `false` to disable the timer (only flush at char threshold or
+     * on explicit `flush()`).
+     */
+    flushEveryMs?: number | false;
+    /**
+     * Field name on the emitted payload that carries the buffered text.
+     * Default: `'chunk'`. Override if your stream payload uses a different
+     * key (e.g. `'text'`, `'delta'`).
+     */
+    field?: string;
+}
+export interface StreamThrottle {
+    /** Append text to the buffer. May trigger a flush. */
+    push: (text: string, emit: (payload: Record<string, unknown>) => void) => void;
+    /** Force-flush whatever is in the buffer right now. Call after the source loop ends. */
+    flush: (emit: (payload: Record<string, unknown>) => void) => void;
+    /** Drop the buffered text without emitting. Useful on abort. */
+    reset: () => void;
+}
+/**
+ * Build a chunk throttle for streaming use cases. Designed for LLM token
+ * streams where the provider yields very small pieces (3–10 chars) and you
+ * don't want to send a separate socket message for each one.
+ *
+ * @example
+ *   const throttle = createStreamThrottle({ flushEveryMs: 50, flushAtChars: 32 });
+ *   for await (const chunk of openaiStream) {
+ *     throttle.push(chunk.text, broadcastStream);
+ *   }
+ *   throttle.flush(broadcastStream);
+ */
+export declare const createStreamThrottle: (options?: CreateStreamThrottleOptions) => StreamThrottle;

package/dist/syncRequest.d.ts

@@ -0,0 +1,126 @@
+import type { BaseSessionLayout as SessionLayout, StreamPayload, SyncTypeMap, statusContent } from "@luckystack/core/client";
+import { Dispatch, RefObject, SetStateAction } from "react";
+import { Socket } from "socket.io-client";
+export type SyncRequestStreamEvent<T extends StreamPayload = StreamPayload> = T;
+export type SyncRouteStreamEvent<T extends StreamPayload = StreamPayload> = T;
+type DataRequired<T> = Record<string, never> extends T ? false : true;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type SyncRouteRecord = UnionToIntersection<{
+    [P in keyof SyncTypeMap]: {
+        [N in keyof SyncTypeMap[P] as P extends 'root' ? `system/${Extract<N, string>}` : `${Extract<P, string>}/${Extract<N, string>}`]: SyncTypeMap[P][N];
+    };
+}[keyof SyncTypeMap]>;
+type SyncFullName = Extract<keyof SyncRouteRecord, string>;
+type VersionsForFullName<F extends SyncFullName> = Extract<keyof SyncRouteRecord[F], string>;
+type ClientInputForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    clientInput: infer I;
+} ? I : never;
+type ServerOutputForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    serverOutput: infer O;
+} ? O : never;
+type ClientOutputForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    clientOutput: infer O;
+} ? O : never;
+type ServerStreamForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    serverStream: infer O;
+} ? O : never;
+type ClientStreamForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    clientStream: infer O;
+} ? O : never;
+type SyncRequestStreamCallbackForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = [
+    ServerStreamForFullName<F, V>
+] extends [never] ? never : (event: SyncRequestStreamEvent<Prettify<ServerStreamForFullName<F, V> extends StreamPayload ? ServerStreamForFullName<F, V> : StreamPayload>>) => void;
+type CombinedRouteStream<F extends SyncFullName, V extends VersionsForFullName<F>> = (ClientStreamForFullName<F, V> extends never ? never : ClientStreamForFullName<F, V>) | (ServerStreamForFullName<F, V> extends never ? never : ServerStreamForFullName<F, V>);
+type SyncRouteStreamCallbackForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = [
+    CombinedRouteStream<F, V>
+] extends [never] ? never : (params: {
+    stream: SyncRouteStreamEvent<Prettify<CombinedRouteStream<F, V> extends StreamPayload ? CombinedRouteStream<F, V> : StreamPayload>>;
+}) => void;
+type SyncParamsForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = DataRequired<ClientInputForFullName<F, V>> extends true ? {
+    name: F;
+    version: V;
+    data: ClientInputForFullName<F, V>;
+    receiver: string;
+    ignoreSelf?: boolean;
+    onStream?: SyncRequestStreamCallbackForFullName<F, V>;
+    /**
+     * Per-request override of `projectConfig.offlineQueue.dropPolicy`. Lets a
+     * specific sync ("editor cursor move") pick `'drop-oldest'` while the
+     * app default stays `'reject'` for safer sends. When omitted, falls back
+     * to the global config.
+     */
+    offlineDropPolicy?: 'drop-oldest' | 'drop-newest' | 'reject';
+    /**
+     * Optional AbortSignal. When aborted the client emits `syncCancel { cb }`
+     * to the server and resolves locally with
+     * `{ status: 'error', errorCode: 'request.aborted' }`.
+     */
+    signal?: AbortSignal;
+} : {
+    name: F;
+    version: V;
+    data?: ClientInputForFullName<F, V>;
+    receiver: string;
+    ignoreSelf?: boolean;
+    onStream?: SyncRequestStreamCallbackForFullName<F, V>;
+    /** Per-request override (see typed branch). */
+    offlineDropPolicy?: 'drop-oldest' | 'drop-newest' | 'reject';
+    /** Optional AbortSignal — see typed branch. */
+    signal?: AbortSignal;
+};
+interface SyncErrorParam {
+    key: string;
+    value: string | number | boolean;
+}
+interface SyncResponseError {
+    status: 'error';
+    message: string;
+    errorCode: string;
+    errorParams?: SyncErrorParam[];
+    httpStatus?: number;
+}
+type SyncResultForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = [
+    ServerOutputForFullName<F, V>
+] extends [never] ? Record<string, never> : ServerOutputForFullName<F, V>;
+type SyncRequestResponseForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncResponseError | {
+    status: 'success';
+    message: string;
+    result: SyncResultForFullName<F, V>;
+};
+type SyncRequestParamsWithOptions<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncParamsForFullName<F, V>;
+export declare function syncRequest<F extends SyncFullName, V extends VersionsForFullName<F>>(params: SyncRequestParamsWithOptions<F, V>): Promise<Prettify<SyncRequestResponseForFullName<F, V>>>;
+interface TypedCallbackParams<F extends SyncFullName, V extends VersionsForFullName<F>> {
+    clientOutput: ClientOutputForFullName<F, V>;
+    serverOutput: ServerOutputForFullName<F, V>;
+}
+interface UpsertParams<F extends SyncFullName, V extends VersionsForFullName<F>> {
+    name: F;
+    version: V;
+    callback: (params: TypedCallbackParams<F, V>) => void;
+}
+interface UpsertStreamParams<F extends SyncFullName, V extends VersionsForFullName<F>> {
+    name: F;
+    version: V;
+    callback: SyncRouteStreamCallbackForFullName<F, V>;
+}
+export declare const useSyncEvents: () => {
+    upsertSyncEventCallback: <F extends SyncFullName, V extends VersionsForFullName<F>>(params: UpsertParams<F, V>) => (() => void);
+    upsertSyncEventStreamCallback: <F extends SyncFullName, V extends VersionsForFullName<F>>(params: UpsertStreamParams<F, V>) => (() => void);
+};
+export declare const useSyncEventTrigger: () => {
+    triggerSyncEvent: (name: string, clientOutput?: unknown, serverOutput?: unknown) => void;
+    triggerSyncStreamEvent: (name: string, stream: SyncRouteStreamEvent) => void;
+};
+export declare const attachSyncReceiver: (socketInstance: Socket) => void;
+type SocketStatusSetter = Dispatch<SetStateAction<{
+    self: statusContent;
+    [userId: string]: statusContent;
+}>>;
+export declare const initSyncRequest: ({ setSocketStatus, sessionRef }: {
+    setSocketStatus: SocketStatusSetter;
+    sessionRef: RefObject<SessionLayout | null> | null;
+}) => Promise<void>;
+export {};

package/docs/callback-registration.md

@@ -1,257 +1,5 @@
-# callback-registration
+# Sync callback registration
 
-> How recipients subscribe to sync events on the client. Covers `useSyncEvents` (the React hook for component-scoped callbacks), the `upsertSyncEventCallback` / `upsertSyncEventStreamCallback` registration APIs, `useSyncEventTrigger` (manual local fire for testing), and `initSyncRequest` (one-time wiring of socket lifecycle handlers to the socket-status provider).
+Component-scoped subscriptions should clean up only their own callback, not another component's listener for the same event. A session reference must be read at event time; closing over an old session could attribute notifications to a logged-out user. See `../src/client.ts` and `../../core/src/client.ts`.
 
-For the originator side see [`./sync-request.md`](./sync-request.md). For streaming payload shapes see [`./streaming.md`](./streaming.md).
-
----
-
-## 1. `useSyncEvents()` — the component-scoped hook
-
-```ts
-import { useSyncEvents } from '@luckystack/sync/client';
-
-const { upsertSyncEventCallback, upsertSyncEventStreamCallback } = useSyncEvents();
-```
-
-Returns two stable (`useCallback`-wrapped) registrar functions. The hook also installs a cleanup `useEffect` that removes every callback registered through this hook instance on unmount.
-
-Key properties:
-
-- **Component-scoped local registry.** Each `useSyncEvents()` call holds its own `Map<fullName, Callback>` so the cleanup effect only removes callbacks added by that component, not callbacks other components registered for the same route.
-- **Automatic deduplication of same-key re-registration.** Calling `upsertSyncEventCallback` twice with the same name+version from the same component replaces the previous callback (idempotent). Calling it from different components adds independent entries.
-- **`useCallback`-stable identity.** The registrar functions don't change identity between renders, so dependency arrays (`useEffect(..., [upsertSyncEventCallback])`) don't churn.
-
-### Typical usage
-
-```tsx
-import { useEffect } from 'react';
-import { useSyncEvents } from '@luckystack/sync/client';
-
-export const BoardSubscriber = () => {
-  const { upsertSyncEventCallback } = useSyncEvents();
-
-  useEffect(() => {
-    const unsubscribe = upsertSyncEventCallback({
-      name: 'board/moveCard',
-      version: 'v1',
-      callback: ({ serverOutput, clientOutput }) => {
-        if (serverOutput.status !== 'success') return;
-        setCards(prev => moveCardLocally(prev, serverOutput.cardId));
-      },
-    });
-    return unsubscribe;
-  }, [upsertSyncEventCallback]);
-
-  return null;
-};
-```
-
-The returned `unsubscribe` lets you cancel before the component unmounts — useful when the subscription is conditional on props or routing.
-
----
-
-## 2. `upsertSyncEventCallback({ name, version, callback })`
-
-Subscribes to **non-stream** sync payloads — the `{ serverOutput, clientOutput, status: 'success' }` frames that `handleSyncRequest` emits at the end of the per-recipient loop.
-
-```ts
-upsertSyncEventCallback<F, V>(params: {
-  name: F;                                     // SyncFullName literal, typed
-  version: V;                                  // VersionsForFullName<F> literal
-  callback: ({
-    clientOutput: ClientOutputForFullName<F, V>,
-    serverOutput: ServerOutputForFullName<F, V>,
-  }) => void;
-}): () => void  // returns unsubscribe function
-```
-
-### Typed payloads (root contract rule 21, no casts)
-
-Both `clientOutput` and `serverOutput` are typed via the generated `SyncTypeMap`. The framework's discriminated unions surface every possible status:
-
-```ts
-upsertSyncEventCallback({
-  name: 'board/moveCard',
-  version: 'v1',
-  callback: ({ serverOutput, clientOutput }) => {
-    // serverOutput is the typed union (success | error variants) from the generated map.
-    if (serverOutput.status !== 'success') return;
-    // After the narrowing, TS knows the success-shape fields are available.
-    console.log(serverOutput.cardId, serverOutput.movedBy);
-  },
-});
-```
-
-Never cast these to `unknown` or `any` (root `CLAUDE.md` rule 21). If inference fails, run `npm run generateArtifacts`; if generated output is wrong, fix the generator rather than casting around it.
-
-### Validation rules
-
-`upsertSyncEventCallback` rejects (returns the `noop` unsubscriber, logs in dev mode) when:
-
-- `params.version` isn't a string -> `sync.invalidVersion`.
-- `params.callback` isn't a function -> `sync.invalidCallback`.
-- `params.name` isn't a valid service route name -> `routing.invalidServiceRouteName`.
-
-These are dev-time guards. In production the runtime errors surface only if generated types are mis-applied at the call site.
-
-### Multiple components subscribing to the same route
-
-Supported and intentional. Each component's registrar pushes a separate callback into the route's array; `triggerSyncCallbacks` iterates and fires each. Cleanup is per-callback — unmounting Component A doesn't affect Component B's subscription.
-
-### Duplicate callback handling (same reference)
-
-If the **exact same callback function reference** is registered twice (rare — usually a bug where `useEffect` runs without dependency-checking), the registrar warns in dev mode and ignores the second add. The local registry still tracks the callback so the cleanup works. This guards against runaway callback arrays without breaking legitimate multi-component subscriptions.
-
----
-
-## 3. `upsertSyncEventStreamCallback({ name, version, callback })`
-
-Subscribes to **stream chunks** — the `{ status: 'stream', cb, fullName, ...payload }` frames emitted via `broadcastStream`, `streamTo`, or `_client.stream(...)`.
-
-```ts
-upsertSyncEventStreamCallback<F, V>(params: {
-  name: F;
-  version: V;
-  callback: ({ stream }: { stream: SyncRouteStreamEvent<...> }) => void;
-}): () => void
-```
-
-The `stream` parameter type is the union of:
-
-- The route's `serverStream` type (from `broadcastStream` and `streamTo` payloads).
-- The route's `clientStream` type (from per-recipient `_client.stream(payload)`).
-
-If neither side ever streams, the callback type collapses to `never` and TS rejects the registration call at compile time — a compile-time guarantee that you can't subscribe to a non-streaming route.
-
-```ts
-upsertSyncEventStreamCallback({
-  name: 'chat/sendMessage',
-  version: 'v1',
-  callback: ({ stream }) => {
-    if ('chunk' in stream) appendToken(stream.chunk);
-    else if (stream.status === 'started') showTypingIndicator(stream.author);
-    else if (stream.status === 'done') hideTypingIndicator();
-  },
-});
-```
-
-Stream callbacks run for **every chunk** of every fanout to this recipient — there is no per-request scoping. Use `onStream` on `syncRequest` instead when you want per-request scoping for originator-targeted chunks.
-
-The same dedup / multi-subscriber / unsubscribe semantics from `upsertSyncEventCallback` apply.
-
----
-
-## 4. `useSyncEventTrigger()` — manual local fire
-
-```ts
-const { triggerSyncEvent, triggerSyncStreamEvent } = useSyncEventTrigger();
-
-triggerSyncEvent('sync/board/moveCard/v1', { /* clientOutput */ }, { /* serverOutput */ });
-triggerSyncStreamEvent('sync/board/moveCard/v1', { chunk: 'partial' });
-```
-
-Bypasses the wire entirely. The framework's internal `triggerSyncCallbacks` / `triggerSyncStreamCallbacks` are called directly, firing every registered subscriber as if the payload had arrived from the server.
-
-Use cases:
-
-- **Local testing** — fire a fake payload to verify your UI subscriber works without spinning up the server pipeline.
-- **Optimistic local echo** — apply a payload to your own UI without sending it through the network (rare — usually optimistic UI just mutates local state directly, no need to round-trip the sync system).
-- **Storybook / fixtures** — drive subscriber components with deterministic payloads.
-
-The argument names are different from the wire format:
-
-- First argument: the **full route name** (`sync/<page>/<name>/v<N>`). The `sync/` prefix is part of the internal routing key.
-- Second argument: `clientOutput`.
-- Third argument: `serverOutput`.
-
-Note: the parameter order is `(name, clientOutput, serverOutput)` — opposite of what you might expect from reading the wire frame, which lists `serverOutput` first. The internal callback signature is `{ clientOutput, serverOutput }` (object) but the trigger helper passes positionally for ergonomics.
-
----
-
-## 5. `initSyncRequest({ setSocketStatus, sessionRef })`
-
-One-time wiring of socket lifecycle events to a status setter. Called at app boot from `SocketStatusProvider`. Not consumed by app code directly.
-
-```ts
-initSyncRequest({
-  setSocketStatus,    // Dispatch from useState<{ self, [userId]: statusContent }>
-  sessionRef,         // RefObject<SessionLayout | null>
-});
-```
-
-Wires the following Socket.io events:
-
-| Socket event | Action |
-|---|---|
-| `connect` | `setSocketStatus(prev => ({ ...prev, self: { ...self, status: 'CONNECTED' } }))` |
-| `disconnect` | `setSocketStatus(prev => ({ ...prev, self: { ...self, status: 'DISCONNECTED' } }))` |
-| `reconnectAttempt(attempt)` | Status `'RECONNECTING'` with `reconnectAttempt` set to the attempt number. |
-| `userAfk({ userId, endTime })` | If `userId === session.id`, mark `self` disconnected with `endTime`. Otherwise mark the user as disconnected in the per-user map. |
-| `userBack({ userId })` | Mark the user as `'CONNECTED'`, clear `endTime`. |
-| `connect_error(err)` | Mark `self` disconnected, log + notify in dev mode. |
-
-Idempotent: if `initSyncRequest` is called again later, the previous handlers are removed before new ones are attached (the module holds `activeLifecycleHandlers` for this). Safe to call across hot-reloads.
-
-`sessionRef` is a `RefObject` (not a value) because the handlers must always read the **current** session at event-firing time, not the session at handler-construction time. Without the ref, a logout followed by a `userAfk` event would still treat the AFK as if it belonged to the old user.
-
----
-
-## 6. Why callbacks must never cast `serverOutput` / `clientOutput`
-
-Rule 21 in the repository-root `CLAUDE.md`: generated types are mandatory; no `unknown` / `any` casts on typed transports.
-
-Both `upsertSyncEventCallback` and `upsertSyncEventStreamCallback` give you fully typed payloads via the generated `SyncTypeMap`. The framework's discriminated unions handle the status branching cleanly:
-
-```ts
-// GOOD — uses the generated discriminated union
-callback: ({ serverOutput }) => {
-  if (serverOutput.status !== 'success') return;
-  console.log(serverOutput.cardId);   // typed
-}
-
-// BAD — defeats inference, breaks contract evolution
-callback: ({ serverOutput }: any) => {
-  console.log((serverOutput as { cardId: string }).cardId);
-}
-
-// BAD — same problem, different syntax
-const data = serverOutput as unknown as { cardId: string };
-```
-
-When inference fails:
-
-1. Regenerate the type map: `npm run ai:index`.
-2. Verify the `_server_v{N}.ts` return type is well-typed (no `any` in the return path).
-3. If you still hit a wall, fix the typing source — don't paper over with casts at the call site.
-
----
-
-## 7. Subscription cleanup checklist
-
-- `useSyncEvents()` auto-cleans on component unmount (via `useEffect` cleanup). For most cases, just call the registrars in a `useEffect` and return their unsubscribers. That's belt-and-suspenders but cheap.
-- Calling `upsertSyncEventCallback` outside React (e.g. from a `_provider` module-level subscribe) means you own the cleanup. Save the returned function and call it on teardown.
-- Re-registering with the same name+version from the same component (same `useSyncEvents()` instance) replaces the previous callback — no leak.
-- Re-registering from a **different** component adds an independent entry — both fire.
-
----
-
-## 8. Quick reference
-
-| API | Purpose | Scope |
-|---|---|---|
-| `useSyncEvents()` | React hook returning `{ upsertSyncEventCallback, upsertSyncEventStreamCallback }` | Component lifetime — auto-clean on unmount |
-| `upsertSyncEventCallback({ name, version, callback })` | Subscribe to `{ serverOutput, clientOutput }` frames | Returns unsubscribe |
-| `upsertSyncEventStreamCallback({ name, version, callback })` | Subscribe to stream chunks (`broadcastStream`, `streamTo`, `_client.stream`) | Returns unsubscribe |
-| `useSyncEventTrigger()` | React hook returning `{ triggerSyncEvent, triggerSyncStreamEvent }` for local fire | Component-stable identity |
-| `initSyncRequest({ setSocketStatus, sessionRef })` | One-time wire-up of socket lifecycle to status provider | App boot |
-
----
-
-## 9. Related
-
-- Originator API: [`./sync-request.md`](./sync-request.md)
-- Stream payload shapes: [`./streaming.md`](./streaming.md)
-- Server / client handler contracts (what produces the payloads): [`./server-vs-client-handlers.md`](./server-vs-client-handlers.md)
-- Type-generation contract (rule 21): repository-root [`CLAUDE.md`](../../../CLAUDE.md)
-- `SocketStatusProvider` wiring: `src/_providers/SocketStatusProvider.tsx` (installer side)
+Types for server and recipient output come from generated maps; do not cast payloads around a broken generator. Regenerate artifacts, then correct source definitions if inference still fails. Stream subscriptions exist only for routes that actually stream; keep progress delivery separate from the final acknowledgement. See `./streaming.md`, `../../core/AGENTS.md`.