@luckystack/sync 0.6.6 → 0.7.0

package/CLAUDE.md

@@ -1,122 +1,122 @@
-# @luckystack/sync
-
-> AI summary + function INDEX. For deep specs see `docs/` next to this file.
-
-## What this package does
-
-Real-time sync transport for LuckyStack. Provides type-safe, room-based fanout over Socket.io with an HTTP/SSE fallback. Each sync event is a file-based route with a mandatory `_server_v{N}.ts` (runs once, validates, produces `serverOutput`) and an optional `_client_v{N}.ts` (runs once per recipient socket for per-target filtering or auth). Streaming primitives (`stream`, `broadcastStream`, `streamTo`) support live LLM tokens, collab-editor diffs, and per-recipient progress. An offline queue with configurable drop policy keeps optimistic sends from being lost when the socket reconnects.
-
-## When to USE this package
-
-- Real-time room-based fanout (collab editors, chat, multiplayer state)
-- Streaming AI/LLM tokens with throttled chunking
-- Per-recipient customization (filter / translate / brand) without a second round-trip
-- Optimistic offline sends that should replay when the socket reconnects
-- Server-validated mutations that must be broadcast to every peer in a room
-
-## When to NOT suggest this (yet)
-
-- Request/response with no fanout — use `@luckystack/api` (`apiRequest`)
-- Pure presence/online-status broadcasts — use `@luckystack/presence`
-- Cross-instance fanout without a Redis adapter — wire the adapter first (see `/docs/ARCHITECTURE_SOCKET.md`)
-- One-off background jobs unrelated to a client room
-- HTTP-only environments without a long-lived connection AND no SSE — the package needs at minimum the HTTP/SSE fallback
-
-## Function Index
-
-### Server entry (`@luckystack/sync`)
-
-| Export | One-liner | Deep doc |
-|---|---|---|
-| `handleSyncRequest({ msg, socket, token })` | Socket.io sync entry — auth, rate-limit, validate, run `_server`, fanout, run `_client` per recipient, emit results, dispatch hooks. | → `docs/server-vs-client-handlers.md` |
-| `handleHttpSyncRequest(req, res)` | HTTP/SSE fallback for sync requests when websockets are blocked. | → `docs/sync-request.md` |
-| `createStreamThrottle({ flushEveryMs?, flushAtChars?, field? })` | Coalesce tiny stream pieces (LLM tokens) into bigger chunks before emit. | → `docs/streaming.md` |
-| Type: `HttpSyncStreamEvent` | SSE event shape emitted by the HTTP fallback. | → `docs/sync-request.md` |
-| Type: `StreamThrottle` / `CreateStreamThrottleOptions` | Throttle handle + options. | → `docs/streaming.md` |
-
-### Client entry (`@luckystack/sync/client`)
-
-| Export | One-liner | Deep doc |
-|---|---|---|
-| `syncRequest({ name, version, data?, receiver, ignoreSelf?, onStream?, offlineDropPolicy? })` | Fire a typed sync event into a room; resolves with the server result envelope. | → `docs/sync-request.md` |
-| `useSyncEvents()` | React hook returning `{ upsertSyncEventCallback, upsertSyncEventStreamCallback }` scoped to the component lifetime. | → `docs/callback-registration.md` |
-| `useSyncEventTrigger()` | React hook returning `{ triggerSyncEvent, triggerSyncStreamEvent }` for manually invoking registered callbacks (testing / local echo). | → `docs/callback-registration.md` |
-| `initSyncRequest({ setSocketStatus, sessionRef })` | One-time wiring of socket lifecycle handlers (connect/disconnect/reconnectAttempt/userAfk/userBack/connectError) into the socket-status provider. | → `docs/callback-registration.md` |
-| Type: `SyncRequestStreamEvent<T>` | Payload shape passed to `onStream` on the originator side. | → `docs/streaming.md` |
-| Type: `SyncRouteStreamEvent<T>` | Payload shape passed to `upsertSyncEventStreamCallback` on recipients. | → `docs/streaming.md` |
-
-### Streaming primitives (received inside `_server_v{N}.ts` params)
-
-| Primitive | Audience | Deep doc |
-|---|---|---|
-| `stream(payload)` | Originator socket only (cheapest). | → `docs/streaming.md` |
-| `broadcastStream(payload)` | Every socket in `roomCode`, across all instances (`io.to(room).emit` via the Redis adapter). | → `docs/streaming.md` |
-| `streamTo(tokens, payload)` | Selective fanout to specific session tokens. | → `docs/streaming.md` |
-| `stream(payload)` in `_client_v{N}.ts` | Per-recipient, runs after `_server` finishes. | → `docs/streaming.md` |
-
-### Hooks dispatched by the server handler
-
-| Hook | When | Deep doc |
-|---|---|---|
-| `preSocketMessage` | At the very top of the socket message handler (before auth/route resolution). Stop to reject the message. Transport-level seam mirroring `preHttpRequest`; `channel: 'sync'`. | → `docs/server-vs-client-handlers.md` |
-| `preSyncAuthorize` | After basic `AuthProps` check, before rate-limit + input validation. Stop to reject. | → `docs/server-vs-client-handlers.md` |
-| `postSyncAuthorize` | Observational — after the request passes auth + custom policy, before rate-limit + validation. | → `docs/server-vs-client-handlers.md` |
-| `preSyncValidate` | Before runtime input validation. Stop to reject (mirrors `preApiValidate`). | → `docs/server-vs-client-handlers.md` |
-| `postSyncValidate` | After validation, carrying `{ validation }` (mirrors `postApiValidate`). | → `docs/server-vs-client-handlers.md` |
-| `preSyncExecute` | Before the `_server` handler runs. Stop to short-circuit (mirrors `preApiExecute`). | → `docs/server-vs-client-handlers.md` |
-| `postSyncExecute` | After `_server` resolves OR throws, carrying `{ result, error, durationMs }`. Fires on the FAILURE path too (mirrors `postApiExecute`). | → `docs/server-vs-client-handlers.md` |
-| `preSyncFanout` | After `_server` runs, before any recipient receives the payload. Stop to abort fanout. | → `docs/room-fanout.md` |
-| `preSyncRecipient` | Per recipient, before that ONE socket receives the payload. Carries `{ routeName, receiver, recipientSocketId, recipientUserId, serverOutput }`. A stop signal SKIPS just that recipient (the loop continues; it is not counted as delivered) — it does NOT abort the whole fanout. `recipientUserId` is null on the hot path. | → `docs/room-fanout.md` |
-| `postSyncFanout` | After all recipients have been emitted to. Receives `recipientCount`. | → `docs/room-fanout.md` |
-| `preSyncStream` | Per stream chunk, before it is emitted (`stream` / `broadcastStream` / `streamTo`). Carries `{ routeName, chunk, recipient }` (`recipient` = `'originator'`, the room, or a token). Observational. | → `docs/streaming.md` |
-| `postSyncStream` | Per stream chunk, after emit. Adds a 1-based per-stream `chunkIndex` to the `preSyncStream` payload. Observational. | → `docs/streaming.md` |
-| `rateLimitExceeded` | When the per-route or per-IP bucket rejects a sync. | → `docs/error-states.md` |
-
-## Config keys
-
-### `registerProjectConfig({ sync, offlineQueue })`
-
-- `sync.streamThrottle.flushAtChars` — char threshold before a buffered throttle flushes. Default `32`.
-- `sync.streamThrottle.flushEveryMs` — timer-based flush interval; `false` disables the timer. Default `50`.
-- `sync.streamThrottle.field` — payload key carrying the buffered text. Default `'chunk'`.
-- `sync.fanoutYieldEvery` — yield to the event loop every N recipients during a giant fanout. Clamped to `>= 1` (a configured `0` would make the modulo `NaN` and never yield).
-- `sync.fanoutYieldMs` — duration of the yield `setTimeout`.
-- `sync.requestTimeoutMs` — client-side ack-timeout for `syncRequest` (CORE-06). After this elapses with no acknowledgement the promise settles with `{ status:'error', errorCode:'sync.requestTimeout', httpStatus:504 }` instead of hanging. `false` disables. Default `30000`.
-- `sync.allowClientReceiverAll` — when `false`, a client requesting the broadcast receiver `'all'` is rejected (`sync.receiverNotAllowed`, 403) on both transports (SYNC-07). **Default `false` (0.2.0 secure-default flip — was `true`); opt back into cluster-wide broadcast explicitly or approve via `preSyncAuthorize`.**
-- `sync.requireRoomMembership` — when `true`, a client may only target a room it has actually joined; an unjoined room is rejected (`sync.notRoomMember`, 403). Enforced on BOTH transports: the SOCKET path checks `socket.rooms`, the HTTP/SSE path derives membership from the session's persisted `roomCodes`. An anonymous HTTP caller (no session) has undeterminable membership and is rejected (fail-closed) — the flag is no longer silently bypassable over the HTTP fallback. **Default `true` (0.2.0 secure-default flip — was `false`); set `false` for the legacy any-room behavior.**
-- `sync.flushPressure.maxBufferedBytes` — default drain threshold for the `flushPressure` backpressure helper when no per-call `thresholdBytes` is given (SYNC-15). Default `5_242_880` (5 MiB).
-- `sync.flushPressure.highWaterMarkChunks` — upper bound (in packets) on the derived flush-pressure threshold. Default `1000`. (`lowWaterMarkChunks` is surfaced in core but full chunk-watermark hysteresis is a residual — see fix report.)
-
-### Per-route `_server` exports
-
-- `export const rateLimit: number | false` — per-route rate limit (mirrors `@luckystack/api`). Overrides `rateLimiting.defaultApiLimit` for this sync route's per-requester bucket; `false` disables it (the global per-IP bucket still applies); omit to fall back to `defaultApiLimit`. Honored by both transports.
-- `offlineQueue.maxSize` — cap on the client-side offline queue.
-- `offlineQueue.dropPolicy` — `'reject'` (default — overflow returns `offline.queueFull`), `'drop-oldest'`, or `'drop-newest'`. Per-request override via `syncRequest({ offlineDropPolicy })`. SYNC-09: when a request that was already QUEUED is later evicted (drop-oldest by a newer enqueue, or age expiry) its awaiting promise now settles with `{ status:'error', errorCode:'offline.dropped' }` (was: hung forever).
-
-### Logging toggles
-
-- `logging.devLogs`, `logging.devNotifications`, `logging.socketStatus`, `logging.stream` — drive the dev-only log lines in this package.
-
-### Env vars
-
-None directly. Inherits socket transport config from `@luckystack/server` and Redis adapter config from `@luckystack/core`.
-
-## Peer dependencies
-
-- **Required**: `@luckystack/core`, `@luckystack/error-tracking`. **`@luckystack/login` is NOT a dependency** (0.2.0 decoupling) — sessions resolve through core's `readSession` / session-provider registry (`handleSyncRequest` imports `readSession` from `@luckystack/core`), with login as the default *provider* (optional package), not a hard runtime dep.
-- **Peer (canonical ranges, 2026-05-07)**:
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
-  - `react@^19.2.0` (only the `/client` subpath)
-  - `socket.io@^4.8.0` (server entry)
-  - `socket.io-client@^4.8.0` (client entry)
-- Redis adapter (required for cross-instance fanout) wired by `@luckystack/server`; see `/docs/ARCHITECTURE_SOCKET.md`.
-
-## Related
-
-- Architecture deep-dive: `/docs/ARCHITECTURE_SYNC.md`
-- Socket setup + Redis adapter: `/docs/ARCHITECTURE_SOCKET.md`
-- Multi-instance model + pitfalls (regular `syncRequest` fan-out reaches across instances via `io.in(room).fetchSockets()` + `RemoteSocket.emit()`; streaming via `broadcastStream`/`streamTo`): `/docs/ARCHITECTURE_MULTI_INSTANCE.md`
-- File-based `_sync/` routing: `/docs/ARCHITECTURE_ROUTING.md`
-- Streaming primitives (`stream` / `streamTo` / `broadcastStream` / `_client`) + throttle: `/docs/ARCHITECTURE_SYNC.md#streaming`
-- README (consumer quickstart): `./README.md`
-- Sibling packages: `@luckystack/api`, `@luckystack/presence`, `@luckystack/server`
+# @luckystack/sync
+
+> AI summary + function INDEX. For deep specs see `docs/` next to this file.
+
+## What this package does
+
+Real-time sync transport for LuckyStack. Provides type-safe, room-based fanout over Socket.io with an HTTP/SSE fallback. Each sync event is a file-based route with a mandatory `_server_v{N}.ts` (runs once, validates, produces `serverOutput`) and an optional `_client_v{N}.ts` (runs once per recipient socket for per-target filtering or auth). Streaming primitives (`stream`, `broadcastStream`, `streamTo`) support live LLM tokens, collab-editor diffs, and per-recipient progress. An offline queue with configurable drop policy keeps optimistic sends from being lost when the socket reconnects.
+
+## When to USE this package
+
+- Real-time room-based fanout (collab editors, chat, multiplayer state)
+- Streaming AI/LLM tokens with throttled chunking
+- Per-recipient customization (filter / translate / brand) without a second round-trip
+- Optimistic offline sends that should replay when the socket reconnects
+- Server-validated mutations that must be broadcast to every peer in a room
+
+## When to NOT suggest this (yet)
+
+- Request/response with no fanout — use `@luckystack/api` (`apiRequest`)
+- Pure presence/online-status broadcasts — use `@luckystack/presence`
+- Cross-instance fanout without a Redis adapter — wire the adapter first (see `/docs/ARCHITECTURE_SOCKET.md`)
+- One-off background jobs unrelated to a client room
+- HTTP-only environments without a long-lived connection AND no SSE — the package needs at minimum the HTTP/SSE fallback
+
+## Function Index
+
+### Server entry (`@luckystack/sync`)
+
+| Export | One-liner | Deep doc |
+|---|---|---|
+| `handleSyncRequest({ msg, socket, token })` | Socket.io sync entry — auth, rate-limit, validate, run `_server`, fanout, run `_client` per recipient, emit results, dispatch hooks. | → `docs/server-vs-client-handlers.md` |
+| `handleHttpSyncRequest(req, res)` | HTTP/SSE fallback for sync requests when websockets are blocked. | → `docs/sync-request.md` |
+| `createStreamThrottle({ flushEveryMs?, flushAtChars?, field? })` | Coalesce tiny stream pieces (LLM tokens) into bigger chunks before emit. | → `docs/streaming.md` |
+| Type: `HttpSyncStreamEvent` | SSE event shape emitted by the HTTP fallback. | → `docs/sync-request.md` |
+| Type: `StreamThrottle` / `CreateStreamThrottleOptions` | Throttle handle + options. | → `docs/streaming.md` |
+
+### Client entry (`@luckystack/sync/client`)
+
+| Export | One-liner | Deep doc |
+|---|---|---|
+| `syncRequest({ name, version, data?, receiver, ignoreSelf?, onStream?, offlineDropPolicy? })` | Fire a typed sync event into a room; resolves with the server result envelope. | → `docs/sync-request.md` |
+| `useSyncEvents()` | React hook returning `{ upsertSyncEventCallback, upsertSyncEventStreamCallback }` scoped to the component lifetime. | → `docs/callback-registration.md` |
+| `useSyncEventTrigger()` | React hook returning `{ triggerSyncEvent, triggerSyncStreamEvent }` for manually invoking registered callbacks (testing / local echo). | → `docs/callback-registration.md` |
+| `initSyncRequest({ setSocketStatus, sessionRef })` | One-time wiring of socket lifecycle handlers (connect/disconnect/reconnectAttempt/userAfk/userBack/connectError) into the socket-status provider. | → `docs/callback-registration.md` |
+| Type: `SyncRequestStreamEvent<T>` | Payload shape passed to `onStream` on the originator side. | → `docs/streaming.md` |
+| Type: `SyncRouteStreamEvent<T>` | Payload shape passed to `upsertSyncEventStreamCallback` on recipients. | → `docs/streaming.md` |
+
+### Streaming primitives (received inside `_server_v{N}.ts` params)
+
+| Primitive | Audience | Deep doc |
+|---|---|---|
+| `stream(payload)` | Originator socket only (cheapest). | → `docs/streaming.md` |
+| `broadcastStream(payload)` | Every socket in `roomCode`, across all instances (`io.to(room).emit` via the Redis adapter). | → `docs/streaming.md` |
+| `streamTo(tokens, payload)` | Selective fanout to specific session tokens. | → `docs/streaming.md` |
+| `stream(payload)` in `_client_v{N}.ts` | Per-recipient, runs after `_server` finishes. | → `docs/streaming.md` |
+
+### Hooks dispatched by the server handler
+
+| Hook | When | Deep doc |
+|---|---|---|
+| `preSocketMessage` | At the very top of the socket message handler (before auth/route resolution). Stop to reject the message. Transport-level seam mirroring `preHttpRequest`; `channel: 'sync'`. | → `docs/server-vs-client-handlers.md` |
+| `preSyncAuthorize` | After basic `AuthProps` check, before rate-limit + input validation. Stop to reject. | → `docs/server-vs-client-handlers.md` |
+| `postSyncAuthorize` | Observational — after the request passes auth + custom policy, before rate-limit + validation. | → `docs/server-vs-client-handlers.md` |
+| `preSyncValidate` | Before runtime input validation. Stop to reject (mirrors `preApiValidate`). | → `docs/server-vs-client-handlers.md` |
+| `postSyncValidate` | After validation, carrying `{ validation }` (mirrors `postApiValidate`). | → `docs/server-vs-client-handlers.md` |
+| `preSyncExecute` | Before the `_server` handler runs. Stop to short-circuit (mirrors `preApiExecute`). | → `docs/server-vs-client-handlers.md` |
+| `postSyncExecute` | After `_server` resolves OR throws, carrying `{ result, error, durationMs }`. Fires on the FAILURE path too (mirrors `postApiExecute`). | → `docs/server-vs-client-handlers.md` |
+| `preSyncFanout` | After `_server` runs, before any recipient receives the payload. Stop to abort fanout. | → `docs/room-fanout.md` |
+| `preSyncRecipient` | Per recipient, before that ONE socket receives the payload. Carries `{ routeName, receiver, recipientSocketId, recipientUserId, serverOutput }`. A stop signal SKIPS just that recipient (the loop continues; it is not counted as delivered) — it does NOT abort the whole fanout. `recipientUserId` is null on the hot path. | → `docs/room-fanout.md` |
+| `postSyncFanout` | After all recipients have been emitted to. Receives `recipientCount`. | → `docs/room-fanout.md` |
+| `preSyncStream` | Per stream chunk, before it is emitted (`stream` / `broadcastStream` / `streamTo`). Carries `{ routeName, chunk, recipient }` (`recipient` = `'originator'`, the room, or a token). Observational. | → `docs/streaming.md` |
+| `postSyncStream` | Per stream chunk, after emit. Adds a 1-based per-stream `chunkIndex` to the `preSyncStream` payload. Observational. | → `docs/streaming.md` |
+| `rateLimitExceeded` | When the per-route or per-IP bucket rejects a sync. | → `docs/error-states.md` |
+
+## Config keys
+
+### `registerProjectConfig({ sync, offlineQueue })`
+
+- `sync.streamThrottle.flushAtChars` — char threshold before a buffered throttle flushes. Default `32`.
+- `sync.streamThrottle.flushEveryMs` — timer-based flush interval; `false` disables the timer. Default `50`.
+- `sync.streamThrottle.field` — payload key carrying the buffered text. Default `'chunk'`.
+- `sync.fanoutYieldEvery` — yield to the event loop every N recipients during a giant fanout. Clamped to `>= 1` (a configured `0` would make the modulo `NaN` and never yield).
+- `sync.fanoutYieldMs` — duration of the yield `setTimeout`.
+- `sync.requestTimeoutMs` — client-side ack-timeout for `syncRequest` (CORE-06). After this elapses with no acknowledgement the promise settles with `{ status:'error', errorCode:'sync.requestTimeout', httpStatus:504 }` instead of hanging. `false` disables. Default `30000`.
+- `sync.allowClientReceiverAll` — when `false`, a client requesting the broadcast receiver `'all'` is rejected (`sync.receiverNotAllowed`, 403) on both transports (SYNC-07). **Default `false` (0.2.0 secure-default flip — was `true`); opt back into cluster-wide broadcast explicitly or approve via `preSyncAuthorize`.**
+- `sync.requireRoomMembership` — when `true`, a client may only target a room it has actually joined; an unjoined room is rejected (`sync.notRoomMember`, 403). Enforced on BOTH transports: the SOCKET path checks `socket.rooms`, the HTTP/SSE path derives membership from the session's persisted `roomCodes`. An anonymous HTTP caller (no session) has undeterminable membership and is rejected (fail-closed) — the flag is no longer silently bypassable over the HTTP fallback. **Default `true` (0.2.0 secure-default flip — was `false`); set `false` for the legacy any-room behavior.**
+- `sync.flushPressure.maxBufferedBytes` — default drain threshold for the `flushPressure` backpressure helper when no per-call `thresholdBytes` is given (SYNC-15). Default `5_242_880` (5 MiB).
+- `sync.flushPressure.highWaterMarkChunks` — upper bound (in packets) on the derived flush-pressure threshold. Default `1000`. (`lowWaterMarkChunks` is surfaced in core but full chunk-watermark hysteresis is a residual — see fix report.)
+
+### Per-route `_server` exports
+
+- `export const rateLimit: number | false` — per-route rate limit (mirrors `@luckystack/api`). Overrides `rateLimiting.defaultApiLimit` for this sync route's per-requester bucket; `false` disables it (the global per-IP bucket still applies); omit to fall back to `defaultApiLimit`. Honored by both transports.
+- `offlineQueue.maxSize` — cap on the client-side offline queue.
+- `offlineQueue.dropPolicy` — `'reject'` (default — overflow returns `offline.queueFull`), `'drop-oldest'`, or `'drop-newest'`. Per-request override via `syncRequest({ offlineDropPolicy })`. SYNC-09: when a request that was already QUEUED is later evicted (drop-oldest by a newer enqueue, or age expiry) its awaiting promise now settles with `{ status:'error', errorCode:'offline.dropped' }` (was: hung forever).
+
+### Logging toggles
+
+- `logging.devLogs`, `logging.devNotifications`, `logging.socketStatus`, `logging.stream` — drive the dev-only log lines in this package.
+
+### Env vars
+
+None directly. Inherits socket transport config from `@luckystack/server` and Redis adapter config from `@luckystack/core`.
+
+## Peer dependencies
+
+- **Required**: `@luckystack/core`, `@luckystack/error-tracking`. **`@luckystack/login` is NOT a dependency** (0.2.0 decoupling) — sessions resolve through core's `readSession` / session-provider registry (`handleSyncRequest` imports `readSession` from `@luckystack/core`), with login as the default *provider* (optional package), not a hard runtime dep.
+- **Peer (canonical ranges, 2026-05-07)**:
+  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
+  - `react@^19.2.0` (only the `/client` subpath)
+  - `socket.io@^4.8.0` (server entry)
+  - `socket.io-client@^4.8.0` (client entry)
+- Redis adapter (required for cross-instance fanout) wired by `@luckystack/server`; see `/docs/ARCHITECTURE_SOCKET.md`.
+
+## Related
+
+- Architecture deep-dive: `/docs/ARCHITECTURE_SYNC.md`
+- Socket setup + Redis adapter: `/docs/ARCHITECTURE_SOCKET.md`
+- Multi-instance model + pitfalls (regular `syncRequest` fan-out reaches across instances via `io.in(room).fetchSockets()` + `RemoteSocket.emit()`; streaming via `broadcastStream`/`streamTo`): `/docs/ARCHITECTURE_MULTI_INSTANCE.md`
+- File-based `_sync/` routing: `/docs/ARCHITECTURE_ROUTING.md`
+- Streaming primitives (`stream` / `streamTo` / `broadcastStream` / `_client`) + throttle: `/docs/ARCHITECTURE_SYNC.md#streaming`
+- README (consumer quickstart): `./README.md`
+- Sibling packages: `@luckystack/api`, `@luckystack/presence`, `@luckystack/server`

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Mathijs van Melick
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Mathijs van Melick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,155 +1,155 @@
-# @luckystack/sync
-
-> Real-time sync transport for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). Type-safe room-based fanout, server + per-client validation, streaming, optimistic offline queue. Server entry plus a browser-safe `./client` subpath for React.
-
-## Install
-
-```bash
-npm install @luckystack/sync @luckystack/core @luckystack/login @luckystack/error-tracking react socket.io socket.io-client
-```
-
-## Quickstart
-
-A sync event is two files (one mandatory, one optional):
-
-```ts
-// src/board/_sync/moveCard_server_v1.ts  — runs ONCE per request, validates and produces serverOutput
-export const auth = { login: true };
-
-export interface SyncParams {
-  data: { cardId: string; toLane: string };
-  user: SessionLayout;
-  receiver: string; // room code
-  functions: Functions;
-}
-
-export const main = async ({ data, user, receiver }: SyncParams) => {
-  await prisma.card.update({ where: { id: data.cardId }, data: { laneId: data.toLane } });
-  return { status: 'success', serverOutput: { cardId: data.cardId, movedBy: user.id } };
-};
-```
-
-Add a `_client_v1.ts` only when you need per-client filtering, per-target auth, or a custom `clientOutput`. If it would just `return { status: 'success' }`, leave it out.
-
-### Client side
-
-```tsx
-import { syncRequest, upsertSyncEventCallback } from '@luckystack/sync/client';
-
-upsertSyncEventCallback({
-  name: 'board/moveCard',
-  version: 'v1',
-  callback: ({ serverOutput, clientOutput }) => {
-    if (serverOutput.status !== 'success') return;
-    setCards(prev => moveCardLocally(prev, serverOutput.cardId));
-  },
-});
-
-await syncRequest({
-  name: 'board/moveCard',
-  version: 'v1',
-  data: { cardId, toLane },
-  receiver: roomCode,
-  ignoreSelf: true,
-});
-```
-
-## Subpaths
-
-- `@luckystack/sync` — server-only transport adapters (`handleSyncRequest`, `handleHttpSyncRequest`). Wired by `@luckystack/server`.
-- `@luckystack/sync/client` — browser-safe hooks (`syncRequest`, `useSyncEvents`, `upsertSyncEventCallback`). React 19 required.
-
-## How it integrates
-
-1. **Validates** server payload, then runs `_server_v{N}.ts` once.
-2. **Dispatches** the `preSyncFanout` hook (may abort).
-3. **Resolves** the room receiver list, optionally running `_client_v{N}.ts` once per recipient socket for per-client filtering or auth.
-4. **Emits** the merged `{ serverOutput, clientOutput }` payload to each socket.
-5. **Dispatches** `postSyncFanout` with the recipient count.
-
-## Streaming
-
-Sync handlers receive **four** stream primitives in their `_server` params, each picking a different audience and cost profile:
-
-| Primitive | Audience | Use when |
-| --- | --- | --- |
-| `stream(payload)` | Originator only (cheapest) | Per-user progress nobody else cares about |
-| `broadcastStream(payload)` | Everyone in `roomCode`, across all instances (Redis adapter) | Live AI chat tokens, collab editor diffs |
-| `streamTo(tokens, payload)` | Specific session tokens | Selective subscribers (admin viewers, etc.) |
-| `_client_v{N}.ts` `stream(...)` | Per-recipient (after `_server` finishes) | Per-target customization (filter / translate / brand) |
-
-Plus `createStreamThrottle({ flushEveryMs, flushAtChars })` for coalescing tiny LLM tokens into bigger chunks — cuts message count by 10–100× without losing the "live" feel.
-
-```ts
-// src/chat/_sync/sendMessage_server_v1.ts — AI chat with live broadcast
-import { createStreamThrottle } from '@luckystack/sync';
-
-export const main = async ({ clientInput, broadcastStream }: SyncParams) => {
-  const throttle = createStreamThrottle({ flushEveryMs: 50, flushAtChars: 32 });
-
-  let full = '';
-  for await (const piece of openaiStream) {
-    full += piece.text;
-    throttle.push(piece.text, broadcastStream);
-  }
-  throttle.flush(broadcastStream);
-
-  return { status: 'success', message: full };
-};
-```
-
-Recipients consume both `broadcastStream` and `streamTo` chunks via the same `upsertSyncEventCallback` they already use:
-
-```ts
-upsertSyncEventCallback({
-  name: 'chat/sendMessage',
-  version: 'v1',
-  callback: ({ stream, status }) => {
-    if (status === 'stream' && stream?.chunk) appendToken(stream.chunk);
-  },
-});
-```
-
-Full decision tree, performance notes, and additional examples live in [`docs/ARCHITECTURE_SYNC.md`](../../docs/ARCHITECTURE_SYNC.md#streaming).
-
-## Public API
-
-Server entry (`@luckystack/sync`):
-
-| Export | Purpose |
-| --- | --- |
-| `handleSyncRequest(socket, msg, ack)` | Socket.io sync handler (default export). |
-| `handleHttpSyncRequest(req, res)` | HTTP/SSE fallback. |
-| `createStreamThrottle(options)` | Coalesce small stream pieces into bigger chunks (LLM-token-friendly). |
-| Type: `HttpSyncStreamEvent` | SSE event shape. |
-| Type: `StreamThrottle` / `CreateStreamThrottleOptions` | Throttle helper types. |
-
-Configure stream throttling and offline-queue policy via `registerProjectConfig({ sync, offlineQueue })`. The shapes are exported from `@luckystack/core` as **`SyncConfig`** (with nested `SyncStreamThrottleConfig`) and **`OfflineQueueConfig`** — they cover the throttle defaults, fanout iteration tuning, and the queue's max-size + drop policy (`'reject'` triggers the `offline.queueFull` error code on overflow).
-
-Client entry (`@luckystack/sync/client`):
-
-| Export | Purpose |
-| --- | --- |
-| `syncRequest(opts)` | Fire a typed sync event, optionally with `ignoreSelf` and `receiver`. |
-| `upsertSyncEventCallback({ name, version, callback })` | Subscribe to inbound sync payloads. |
-| `useSyncEvents(...)` | React hook for component-scoped subscriptions. |
-
-## Related architecture docs
-
-- [`docs/ARCHITECTURE_SYNC.md`](../../docs/ARCHITECTURE_SYNC.md) — full sync lifecycle, streaming decision tree, performance notes.
-- [`docs/ARCHITECTURE_SOCKET.md`](../../docs/ARCHITECTURE_SOCKET.md) — Socket.io + Redis adapter (required for cross-instance fanout).
-- [`docs/ARCHITECTURE_ROUTING.md`](../../docs/ARCHITECTURE_ROUTING.md) — `_sync/` file conventions and `_server` / `_client` split.
-- [`docs/ARCHITECTURE_SYNC.md#streaming`](../../docs/ARCHITECTURE_SYNC.md#streaming) — the streaming primitives (`stream` / `streamTo` / `broadcastStream` / `_client`), `createStreamThrottle`, and SSE.
-
-## Dependencies
-
-- Runtime: `@luckystack/core`, `@luckystack/login`, `@luckystack/error-tracking`
-- Peer (canonical ranges, standardized 2026-05-07):
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
-  - `react@^19.2.0` (`/client` entry only)
-  - `socket.io@^4.8.0`
-  - `socket.io-client@^4.8.0`
-
-## License
-
-MIT — see [LICENSE](../../LICENSE).
+# @luckystack/sync
+
+> Real-time sync transport for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). Type-safe room-based fanout, server + per-client validation, streaming, optimistic offline queue. Server entry plus a browser-safe `./client` subpath for React.
+
+## Install
+
+```bash
+npm install @luckystack/sync @luckystack/core @luckystack/login @luckystack/error-tracking react socket.io socket.io-client
+```
+
+## Quickstart
+
+A sync event is two files (one mandatory, one optional):
+
+```ts
+// src/board/_sync/moveCard_server_v1.ts  — runs ONCE per request, validates and produces serverOutput
+export const auth = { login: true };
+
+export interface SyncParams {
+  data: { cardId: string; toLane: string };
+  user: SessionLayout;
+  receiver: string; // room code
+  functions: Functions;
+}
+
+export const main = async ({ data, user, receiver }: SyncParams) => {
+  await prisma.card.update({ where: { id: data.cardId }, data: { laneId: data.toLane } });
+  return { status: 'success', serverOutput: { cardId: data.cardId, movedBy: user.id } };
+};
+```
+
+Add a `_client_v1.ts` only when you need per-client filtering, per-target auth, or a custom `clientOutput`. If it would just `return { status: 'success' }`, leave it out.
+
+### Client side
+
+```tsx
+import { syncRequest, upsertSyncEventCallback } from '@luckystack/sync/client';
+
+upsertSyncEventCallback({
+  name: 'board/moveCard',
+  version: 'v1',
+  callback: ({ serverOutput, clientOutput }) => {
+    if (serverOutput.status !== 'success') return;
+    setCards(prev => moveCardLocally(prev, serverOutput.cardId));
+  },
+});
+
+await syncRequest({
+  name: 'board/moveCard',
+  version: 'v1',
+  data: { cardId, toLane },
+  receiver: roomCode,
+  ignoreSelf: true,
+});
+```
+
+## Subpaths
+
+- `@luckystack/sync` — server-only transport adapters (`handleSyncRequest`, `handleHttpSyncRequest`). Wired by `@luckystack/server`.
+- `@luckystack/sync/client` — browser-safe hooks (`syncRequest`, `useSyncEvents`, `upsertSyncEventCallback`). React 19 required.
+
+## How it integrates
+
+1. **Validates** server payload, then runs `_server_v{N}.ts` once.
+2. **Dispatches** the `preSyncFanout` hook (may abort).
+3. **Resolves** the room receiver list, optionally running `_client_v{N}.ts` once per recipient socket for per-client filtering or auth.
+4. **Emits** the merged `{ serverOutput, clientOutput }` payload to each socket.
+5. **Dispatches** `postSyncFanout` with the recipient count.
+
+## Streaming
+
+Sync handlers receive **four** stream primitives in their `_server` params, each picking a different audience and cost profile:
+
+| Primitive | Audience | Use when |
+| --- | --- | --- |
+| `stream(payload)` | Originator only (cheapest) | Per-user progress nobody else cares about |
+| `broadcastStream(payload)` | Everyone in `roomCode`, across all instances (Redis adapter) | Live AI chat tokens, collab editor diffs |
+| `streamTo(tokens, payload)` | Specific session tokens | Selective subscribers (admin viewers, etc.) |
+| `_client_v{N}.ts` `stream(...)` | Per-recipient (after `_server` finishes) | Per-target customization (filter / translate / brand) |
+
+Plus `createStreamThrottle({ flushEveryMs, flushAtChars })` for coalescing tiny LLM tokens into bigger chunks — cuts message count by 10–100× without losing the "live" feel.
+
+```ts
+// src/chat/_sync/sendMessage_server_v1.ts — AI chat with live broadcast
+import { createStreamThrottle } from '@luckystack/sync';
+
+export const main = async ({ clientInput, broadcastStream }: SyncParams) => {
+  const throttle = createStreamThrottle({ flushEveryMs: 50, flushAtChars: 32 });
+
+  let full = '';
+  for await (const piece of openaiStream) {
+    full += piece.text;
+    throttle.push(piece.text, broadcastStream);
+  }
+  throttle.flush(broadcastStream);
+
+  return { status: 'success', message: full };
+};
+```
+
+Recipients consume both `broadcastStream` and `streamTo` chunks via the same `upsertSyncEventCallback` they already use:
+
+```ts
+upsertSyncEventCallback({
+  name: 'chat/sendMessage',
+  version: 'v1',
+  callback: ({ stream, status }) => {
+    if (status === 'stream' && stream?.chunk) appendToken(stream.chunk);
+  },
+});
+```
+
+Full decision tree, performance notes, and additional examples live in [`docs/ARCHITECTURE_SYNC.md`](../../docs/ARCHITECTURE_SYNC.md#streaming).
+
+## Public API
+
+Server entry (`@luckystack/sync`):
+
+| Export | Purpose |
+| --- | --- |
+| `handleSyncRequest(socket, msg, ack)` | Socket.io sync handler (default export). |
+| `handleHttpSyncRequest(req, res)` | HTTP/SSE fallback. |
+| `createStreamThrottle(options)` | Coalesce small stream pieces into bigger chunks (LLM-token-friendly). |
+| Type: `HttpSyncStreamEvent` | SSE event shape. |
+| Type: `StreamThrottle` / `CreateStreamThrottleOptions` | Throttle helper types. |
+
+Configure stream throttling and offline-queue policy via `registerProjectConfig({ sync, offlineQueue })`. The shapes are exported from `@luckystack/core` as **`SyncConfig`** (with nested `SyncStreamThrottleConfig`) and **`OfflineQueueConfig`** — they cover the throttle defaults, fanout iteration tuning, and the queue's max-size + drop policy (`'reject'` triggers the `offline.queueFull` error code on overflow).
+
+Client entry (`@luckystack/sync/client`):
+
+| Export | Purpose |
+| --- | --- |
+| `syncRequest(opts)` | Fire a typed sync event, optionally with `ignoreSelf` and `receiver`. |
+| `upsertSyncEventCallback({ name, version, callback })` | Subscribe to inbound sync payloads. |
+| `useSyncEvents(...)` | React hook for component-scoped subscriptions. |
+
+## Related architecture docs
+
+- [`docs/ARCHITECTURE_SYNC.md`](../../docs/ARCHITECTURE_SYNC.md) — full sync lifecycle, streaming decision tree, performance notes.
+- [`docs/ARCHITECTURE_SOCKET.md`](../../docs/ARCHITECTURE_SOCKET.md) — Socket.io + Redis adapter (required for cross-instance fanout).
+- [`docs/ARCHITECTURE_ROUTING.md`](../../docs/ARCHITECTURE_ROUTING.md) — `_sync/` file conventions and `_server` / `_client` split.
+- [`docs/ARCHITECTURE_SYNC.md#streaming`](../../docs/ARCHITECTURE_SYNC.md#streaming) — the streaming primitives (`stream` / `streamTo` / `broadcastStream` / `_client`), `createStreamThrottle`, and SSE.
+
+## Dependencies
+
+- Runtime: `@luckystack/core`, `@luckystack/login`, `@luckystack/error-tracking`
+- Peer (canonical ranges, standardized 2026-05-07):
+  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
+  - `react@^19.2.0` (`/client` entry only)
+  - `socket.io@^4.8.0`
+  - `socket.io-client@^4.8.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).