react-ws-context 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-08-30
+
+### Added
+
+- Export `LivenessOptions` from the package entry
+
+### Changed
+
+- README (EN / zh-TW): align structure and wording; fix immutable-config URL guidance; clarify render isolation, stall parsing, and `WsProvider` lifecycle
+- JSDoc (`CreateWsContextOptions`, `WsContextValue`): clearer field descriptions; fix `autoConnect` wording
+
 ## [0.4.0] - 2026-08-29
 
 ### Fixed

package/README.md

@@ -5,7 +5,7 @@
 
 > **繁體中文：** [README.zh-TW.md](./README.zh-TW.md)
 
-A React **WebSocket connection layer**. It separates connection lifecycle, subscribable state, and message events so status updates or high-frequency messages do not re-render your entire component tree.
+A React **WebSocket connection-layer** package. It separates connection lifecycle, subscribable state, and message events so connection status or high-frequency messages do not re-render your entire component tree.
 
 > **Maintainer:** [GaiaYang](https://github.com/GaiaYang)  
 > **Source:** [github.com/GaiaYang/react-ws](https://github.com/GaiaYang/react-ws) (package path: `packages/react-ws`)
@@ -14,7 +14,7 @@ A React **WebSocket connection layer**. It separates connection lifecycle, subsc
 
 - **Zero runtime dependencies** — only `react >= 18` as a peer dependency
 - **Frozen config** — `url`, `reconnectMs`, etc. are fixed at `createWsContext`; use `connect` / `disconnect` at runtime
-- **Render isolation** — connection-layer state (health / queue / reconnect) lives in an external store; messages go through an event emitter, not React Context
+- **Render isolation** — connection-layer state (health / queue / reconnect) lives in an external store; messages are delivered through an event emitter and subscribed via `useWsEvents` (not written into React state)
 - **Optional liveness** — periodic ping / pong; closes the socket on timeout to trigger reconnect
 - **Optional outbound queue** — buffers messages while not OPEN, flushes on connect
 
@@ -87,13 +87,13 @@ function Chat() {
 createWsContext(options)
         │
         ├── WsProvider      WebSocket instance, reconnect, liveness, outbound queue
-        ├── useWsActions()  send / connect / disconnect — no re-renders
+        ├── useWsActions()  send / connect / disconnect / getStatus — no re-renders
         ├── useWsStore()    connection-layer state: health / queue / reconnect
         └── useWsEvents()   open / message / error / close
 ```
 
 - **Call `createWsContext` multiple times** for independent connections (e.g. app WS + notification WS).
-- **Provider instances** — `useWsStoreApi` (store), `useWsEventsApi` (emitter); actions are assembled in `WsProvider` via `useMemo` and passed through Context.
+- **Provider internals** — each `WsProvider` owns a separate store and event emitter (not public API); actions are assembled in `WsProvider` via `useMemo` and passed through Context.
 - **`WsState` holds low-frequency connection data only** — health (`status`, `phase`), outbound queue (e.g. future `pendingCount`), reconnect (`reconnectAttempt`). **Not** message payloads or app data.
 - **Messages and errors** — use `useWsEvents`; keep message history in your own state, cache, or store.
 - **Connection errors are not a `WsStatus`** — use `useWsEvents("error")`; native `error` is usually followed by `close`.
@@ -108,16 +108,16 @@ Creates a `WsProvider` and hooks bound to the same connection config.
 
 #### `CreateWsContextOptions`
 
-| Field              | Type                                      | Default    | Description                                                                                                                   |
-| ------------------ | ----------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `url`              | `string`                                  | (required) | WebSocket URL                                                                                                                 |
-| `protocols`        | `string \| string[]`                      | —          | Passed to `new WebSocket(url, protocols)`                                                                                     |
-| `autoConnect`      | `boolean`                                 | `true`     | Call `connect()` after `WsProvider` mounts                                                                                    |
-| `reconnectMs`      | `number`                                  | `0`        | Reconnect delay (ms) after unintentional close; `0` disables reconnect                                                        |
-| `reconnectMax`     | `number`                                  | `0`        | Max auto-reconnects after unintentional close (excludes initial connect); `0` unlimited. `reconnectAttempt` resets on open, manual `connect()`, or `disconnect()` |
-| `outgoingQueueMax` | `number`                                  | `0`        | Max outbound queue size while not OPEN; `0` disables the queue                                                                |
-| `parse`            | `(data: MessageEvent["data"]) => unknown` | see below  | Transform raw `MessageEvent.data`                                                                                             |
-| `liveness`         | `LivenessOptions`                         | —          | Liveness / heartbeat config; omit to disable                                                                                  |
+| Field              | Type                                      | Default    | Description                                                                               |
+| ------------------ | ----------------------------------------- | ---------- | ----------------------------------------------------------------------------------------- |
+| `url`              | `string`                                  | (required) | WebSocket URL                                                                             |
+| `protocols`        | `string \| string[]`                      | —          | Passed to `new WebSocket(url, protocols)`                                                 |
+| `autoConnect`      | `boolean`                                 | `true`     | Auto-connect when `WsProvider` loads                                                      |
+| `reconnectMs`      | `number`                                  | `0`        | Reconnect delay (ms) after unintentional close; `0` disables reconnect                    |
+| `reconnectMax`     | `number`                                  | `0`        | Max auto-reconnects after unintentional close; `0` unlimited (requires `reconnectMs > 0`) |
+| `outgoingQueueMax` | `number`                                  | `0`        | Max outbound queue size while not OPEN; `0` disables the queue                            |
+| `parse`            | `(data: MessageEvent["data"]) => unknown` | see below  | Transform raw `MessageEvent.data`                                                         |
+| `liveness`         | `LivenessOptions`                         | —          | Liveness / heartbeat config; omit to disable                                              |
 
 **Default `parse`:**
 
@@ -139,13 +139,13 @@ Creates a `WsProvider` and hooks bound to the same connection config.
 
 Creates, owns, and tears down the native `WebSocket`.
 
-| Behavior                    | Description                                                                                                                       |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| mount + `autoConnect: true` | Calls `connect()`                                                                                                                 |
-| unmount                     | Cancels reconnect, stops liveness, clears outbound queue; syncs store to `status: "closed"`, `phase: "idle"`; closes socket and emits `close` (reason: `"provider unmount"`) |
-| `disconnect()`              | Same store reset as unmount (`phase: "idle"`, `status: "closed"`), no auto-reconnect; emits `close` (reason: `"client disconnect"`)                                            |
-| reconnect                   | Fixed interval when `reconnectMs > 0` and close was not intentional (no exponential backoff); stops after `reconnectMax` if `> 0` |
-| before reconnect            | Closes existing socket and emits `close` (reason: `"reconnect"`)                                                                  |
+| Behavior                                 | Description                                                                                                                                                                                                                      |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WsProvider` loads + `autoConnect: true` | Auto-connects                                                                                                                                                                                                                    |
+| unmount                                  | Cancels reconnect (`reconnectAttempt` and `reconnectExhausted` reset), stops liveness, clears outbound queue; syncs store to `status: "closed"`, `phase: "idle"`; closes socket and emits `close` (reason: `"provider unmount"`) |
+| `disconnect()`                           | Same cleanup and store reset as unmount, no auto-reconnect; emits `close` (reason: `"client disconnect"`)                                                                                                                        |
+| reconnect                                | Fixed interval when `reconnectMs > 0` and close was not intentional (no exponential backoff); stops after `reconnectMax` if `> 0`                                                                                                |
+| `connect()` with existing socket         | Closes the previous socket and emits `close` (reason: `"reconnect"`) before opening a new one (manual connect or auto-reconnect)                                                                                                 |
 
 ---
 
@@ -153,27 +153,29 @@ Creates, owns, and tears down the native `WebSocket`.
 
 Must be used inside the matching `WsProvider`. Return value is memoized and **does not** re-render on store or message updates.
 
-| Method       | Signature                    | Description                                                                  |
-| ------------ | ---------------------------- | ---------------------------------------------------------------------------- |
-| `send`       | `(data) => boolean`          | Send raw data. Sends immediately when OPEN; otherwise enqueues if configured |
-| `sendJson`   | `(data: unknown) => boolean` | `JSON.stringify` then `send`                                                 |
-| `connect`    | `() => void`                 | Open connection; closes any existing socket first                            |
-| `disconnect` | `() => void`                 | Intentional close; sets store to `phase: "idle"`, `status: "closed"`; no auto-reconnect; clears outbound queue |
-| `getStatus`  | `() => WsStatus`             | Read current status; no subscription, no re-render                           |
+| Method       | Signature                    | Description                                                                                                          |
+| ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `send`       | `(data) => boolean`          | Send raw data (`string`, `ArrayBuffer`, `Blob`, etc.). Sends immediately when OPEN; otherwise enqueues if configured |
+| `sendJson`   | `(data: unknown) => boolean` | `JSON.stringify` then `send`; same return semantics as `send`; `false` if not serializable                           |
+| `connect`    | `() => void`                 | Open connection; closes any existing socket first (see `WsProvider`)                                                 |
+| `disconnect` | `() => void`                 | Intentional close; sets store to `phase: "idle"`, `status: "closed"`; no auto-reconnect; clears outbound queue       |
+| `getStatus`  | `() => WsStatus`             | Read current status; no subscription, no re-render                                                                   |
 
 **`send` / `sendJson` return value:**
 
 - `true` — sent or enqueued
-- `false` — not OPEN and queue full (`outgoingQueueMax > 0`), queue disabled (`outgoingQueueMax === 0`), or `sendJson` failed to `JSON.stringify` (e.g. circular reference)
+- `false` — not sent: queue full, queue disabled, or `sendJson` could not serialize
 
 ---
 
 ### `useWsStore()`
 
-Must be used inside the matching `WsProvider`. Uses `useSyncExternalStore` under the hood.
+Must be used inside the matching `WsProvider`. Uses `useSyncExternalStore` under the hood; **partial updates with unchanged values do not notify subscribers** (shallow compare).
 
 `WsState` is for **connection health / outbound queue / reconnect** — low-frequency lifecycle data. For high-frequency messages, use `useWsEvents("message", …)`, not the store.
 
+**Tip:** use a selector to subscribe only to the fields you need (e.g. `(s) => s.phase`). `useWsStore()` without a selector subscribes to the full state — any field change triggers a re-render.
+
 ```ts
 useWsStore(): WsState
 useWsStore<T>(selector: (state: WsState) => T): T
@@ -195,9 +197,9 @@ interface WsState {
 }
 ```
 
-| Belongs in store                                                                                                              | Does not belong                              |
-| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| `status`, `phase`, reconnect progress (`reconnectAttempt` / `reconnectExhausted`), pending queue size, liveness / stall summaries | `lastMessage`, message history, app payloads |
+| Belongs in store                                                                                              | Does not belong                              |
+| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `status`, `phase`, reconnect progress (`reconnectAttempt` / `reconnectExhausted`), liveness / stall summaries | `lastMessage`, message history, app payloads |
 
 `CreateWsContextOptions` (e.g. `url`, `reconnectMax`) are frozen at `createWsContext` and are **not** in `WsState`. For UI like `n/max`, keep the config alongside the store fields you subscribe to.
 
@@ -214,17 +216,17 @@ Maps to the current WebSocket connection state (similar to readyState). Does **n
 
 #### `WsPhase`
 
-| Value           | Meaning                                                                                          |
-| --------------- | ------------------------------------------------------------------------------------------------ |
-| `idle`          | Not connected, no reconnect scheduled (initial or manual `disconnect()`)                         |
-| `connecting`    | First connect or manual `connect()` in progress                                                  |
-| `open`          | Connected                                                                                        |
-| `reconnecting`  | Auto-reconnect cycle (waiting for timer or connecting); pair with `status`, `reconnectAttempt`   |
-| `stopped`       | Will not auto-reconnect; use `reconnectExhausted` to distinguish max retries vs reconnect disabled |
+| Value          | Meaning                                                                                            |
+| -------------- | -------------------------------------------------------------------------------------------------- |
+| `idle`         | Not connected, no reconnect scheduled (initial or manual `disconnect()`)                           |
+| `connecting`   | First connect or manual `connect()` in progress                                                    |
+| `open`         | Connected                                                                                          |
+| `reconnecting` | Auto-reconnect cycle (waiting for timer or connecting); pair with `status`, `reconnectAttempt`     |
+| `stopped`      | Will not auto-reconnect; use `reconnectExhausted` to distinguish max retries vs reconnect disabled |
 
 `status` and `phase` often change together but mean different things. For example, `phase === "reconnecting"` with `status === "closed"` means waiting for the reconnect timer; `status === "connecting"` means the timer fired and a connect attempt is in progress.
 
-**Tip:** use a selector to subscribe to only the fields you need.
+**Example:**
 
 ```tsx
 const phase = useWsStore((s) => s.phase);
@@ -255,20 +257,23 @@ Must be used inside the matching `WsProvider`. Registers in `useEffect` and unsu
 - Handler is kept in a ref — changing the callback does **not** re-subscribe
 - Changing `type` **does** re-subscribe
 - On unintentional close, the store is updated to `status: "closed"` and the appropriate `phase` before the `close` handler runs
+- Intentional `disconnect()` or provider unmount follows the same order: store first, then `close`
 - For multiple events, call `useWsEvents` multiple times
 
 ---
 
-### Liveness: `LivenessOptions`
+### Liveness
+
+Enable via `createWsContext({ liveness: { … } })`. After OPEN, sends periodic application-layer pings (JSON via `send`, not WebSocket control frames); if no matching pong within `timeoutMs`, closes the socket (which can trigger reconnect).
 
-Enable via `createWsContext({ liveness: { … } })`. After OPEN, sends periodic pings; if no matching pong within `timeoutMs`, closes the socket (which can trigger reconnect).
+Shape of the `liveness` option:
 
 ```ts
 interface LivenessOptions {
-  intervalMs: number;
-  timeoutMs: number;
-  ping: unknown | (() => unknown);
-  isPong: (data: unknown) => boolean;
+  intervalMs: number; // ping interval (ms)
+  timeoutMs: number; // wait for pong (ms)
+  ping: unknown | (() => unknown); // ping payload; function for dynamic values
+  isPong: (data: unknown) => boolean; // whether parsed data is a pong
 }
 ```
 
@@ -290,7 +295,7 @@ createWsContext({
 });
 ```
 
-Every incoming message is checked with `isPong`; a pong resets the timeout timer and still emits `"message"`.
+Every incoming message is checked with `isPong`; a pong clears the timeout timer and still emits `"message"`. Ping payloads are always sent via `JSON.stringify` (JSON only).
 
 ---
 
@@ -298,14 +303,14 @@ Every incoming message is checked with `isPong`; a pong resets the timeout timer
 
 When `outgoingQueueMax > 0`:
 
-| When                       | Behavior                                          |
-| -------------------------- | ------------------------------------------------- |
-| `send` while not OPEN      | Enqueue (FIFO)                                    |
-| Queue full                 | Returns `false`; does **not** drop older messages |
-| Socket OPEN                | Flush entire queue in order                       |
-| `disconnect()`             | Clear queue                                       |
-| `WsProvider` unmount       | Clear queue                                       |
-| Waiting for auto-reconnect | **Keep** queue                                    |
+| When                       | Behavior                                                       |
+| -------------------------- | -------------------------------------------------------------- |
+| `send` while not OPEN      | Enqueue (FIFO)                                                 |
+| Queue full                 | Returns `false`; does **not** drop older messages              |
+| Socket OPEN                | Flush entire queue in order                                    |
+| `disconnect()`             | Clear queue; store set to `idle` / `closed` (see `WsProvider`) |
+| `WsProvider` unmount       | Clear queue; store synced (see `WsProvider`)                   |
+| Waiting for auto-reconnect | **Keep** queue                                                 |
 
 ---
 
@@ -313,14 +318,15 @@ When `outgoingQueueMax > 0`:
 
 From the main `react-ws-context` entry:
 
-| Type                     | Description                                           |
-| ------------------------ | ----------------------------------------------------- |
-| `CreateWsContextOptions` | Options for `createWsContext`                         |
-| `WsContextValue`         | Return type of `useWsActions()`                       |
-| `WsEvents`               | Event name → handler map                              |
-| `WsStatus`               | WebSocket connection state (`WsState`)                |
+| Type                     | Description                                              |
+| ------------------------ | -------------------------------------------------------- |
+| `CreateWsContextOptions` | Options for `createWsContext`                            |
+| `LivenessOptions`        | Options for `liveness` in `createWsContext`              |
+| `WsContextValue`         | Return type of `useWsActions()`                          |
+| `WsEvents`               | Event name → handler map                                 |
+| `WsStatus`               | WebSocket connection state (`WsState`)                   |
 | `WsPhase`                | Provider connection intent / reconnect phase (`WsState`) |
-| `WsState`                | Subscribable store shape (health / queue / reconnect) |
+| `WsState`                | Subscribable store shape (health / queue / reconnect)    |
 
 ---
 
@@ -340,28 +346,42 @@ import {
 } from "react-ws-context/stall";
 ```
 
-| Export                       | Description                                                   |
-| ---------------------------- | ------------------------------------------------------------- |
-| `STALL_MESSAGE_TYPE`         | Client control message type (`"STALL"`)                       |
-| `STALL_ACK_TYPE`             | Server ack type (`"STALL_ACK"`)                               |
-| `createStallMessage(action)` | Build a message for `sendJson`                                |
-| `parseStallMessage(data)`    | Parse from `useWsEvents("message")` data; `null` if invalid   |
-| `StallAction`                | `"stall" \| "release"`                                        |
-| `StallMessage`               | `{ type: "STALL"; action: StallAction }`                      |
-| `StallAck`                   | `{ type: "STALL_ACK"; action: StallAction; active: boolean }` |
+| Export                       | Description                                                                                           |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `STALL_MESSAGE_TYPE`         | Client control message type (`"STALL"`)                                                               |
+| `STALL_ACK_TYPE`             | Server ack type (`"STALL_ACK"`) — for typing only; no built-in parser                                 |
+| `createStallMessage(action)` | Build a client `STALL` message for `sendJson`                                                         |
+| `parseStallMessage(data)`    | Parse client `STALL` messages from `useWsEvents("message")` data; `null` if invalid (not `STALL_ACK`) |
+| `StallAction`                | `"stall" \| "release"`                                                                                |
+| `StallMessage`               | `{ type: "STALL"; action: StallAction }`                                                              |
+| `StallAck`                   | `{ type: "STALL_ACK"; action: StallAction; active: boolean }` — parse server acks yourself            |
+
+**Example:**
+
+```tsx
+const { sendJson } = useWsActions();
+
+useWsEvents("message", (data) => {
+  const stall = parseStallMessage(data);
+  if (stall) console.log("stall control", stall.action);
+});
+
+sendJson(createStallMessage("stall"));
+```
 
 ---
 
 ## Design trade-offs
 
-| Topic            | Notes                                                                          |
-| ---------------- | ------------------------------------------------------------------------------ |
-| Immutable config | `url`, `reconnectMs`, etc. are fixed at create time                            |
-| Reconnect        | Fixed interval only; no exponential backoff; optional cap via `reconnectMax` |
-| SSR              | No `WebSocket` on the server; `connect()` is a no-op without `window`          |
-| Error status     | No `"error"` in `WsStatus`; use `useWsEvents("error")`                         |
-| `WsState` scope  | Health / queue / reconnect only — not messages or app data                     |
-| Rendering        | Components that only call `useWsActions` do not re-render on store or messages |
+| Topic            | Notes                                                                                                     |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| Immutable config | `url`, `reconnectMs`, etc. are fixed at create time; to use a different URL, call `createWsContext` again |
+| Reconnect        | Fixed interval only; no exponential backoff; optional cap via `reconnectMax`                              |
+| SSR              | No `WebSocket` on the server; `connect()` is a no-op without `window`                                     |
+| Error status     | No `"error"` in `WsStatus`; use `useWsEvents("error")`                                                    |
+| `WsState` scope  | Health / queue / reconnect only — not messages or app data                                                |
+| Rendering        | Components that only call `useWsActions` do not re-render on store or messages                            |
+| Store updates    | Repeated writes of the same field values do not notify; prefer selectors                                  |
 
 ---
 
@@ -380,13 +400,13 @@ This package does **not** list zustand or nanoevents as npm dependencies. It inl
 - **Maintainer:** [pmndrs](https://github.com/pmndrs) (Poimandres)
 - **License:** [MIT](https://github.com/pmndrs/zustand/blob/main/LICENSE)
 - **Adapted from:**
-  - External store API — aligned with [`vanilla.ts`](https://github.com/pmndrs/zustand/blob/main/src/vanilla.ts) (subset only)
-  - React subscription — inspired by [`react.ts`](https://github.com/pmndrs/zustand/blob/main/src/react.ts) `useStore`
+  - External store API — aligned with [`vanilla.ts`](https://github.com/pmndrs/zustand/blob/main/src/vanilla.ts) (subset only; no middleware, replace, or initializer factory); `setState` adds partial shallow dedup (unchanged values skip notification)
+  - React subscription — inspired by [`react.ts`](https://github.com/pmndrs/zustand/blob/main/src/react.ts) `useStore` (no `useDebugValue`); optional selector overload lives in `createUseWsStore`
 - **Files:** `src/ws-context/store.ts`, `src/ws-context/use-store.ts`
 
 ### [nanoevents](https://github.com/ai/nanoevents)
 
 - **Author:** [Andrey Sitnik](https://github.com/ai) (`ai`)
 - **License:** [MIT](https://github.com/ai/nanoevents/blob/main/LICENSE)
-- **Adapted from:** [`createNanoEvents`](https://github.com/ai/nanoevents/blob/main/index.js); `useWsEventsApi` added by this package (`ws-events.ts`)
+- **Adapted from:** [`createNanoEvents`](https://github.com/ai/nanoevents/blob/main/index.js); React subscription wrapper added in `ws-events.ts`
 - **Files:** `src/ws-context/emitter.ts`, `src/ws-context/ws-events.ts`

package/README.zh-TW.md

@@ -1,11 +1,11 @@
-> **English:** [README.md](./README.md)
-
 # react-ws-context
 
 [![npm version](https://img.shields.io/npm/v/react-ws-context.svg)](https://www.npmjs.com/package/react-ws-context)
 [![npm downloads](https://img.shields.io/npm/dm/react-ws-context.svg)](https://www.npmjs.com/package/react-ws-context)
 
-React 用的 WebSocket **連線層**套件。將連線生命週期、可訂閱狀態與訊息事件分離，避免 status 或高頻訊息更新拖垮整棵元件樹。
+> **English:** [README.md](./README.md)
+
+React 用的 **WebSocket 連線層**套件。將連線生命週期、可訂閱狀態與訊息事件分離，避免連線 status 或高頻訊息更新拖垮整棵元件樹。
 
 > **維護者：** [GaiaYang](https://github.com/GaiaYang)  
 > **原始碼：** [github.com/GaiaYang/react-ws](https://github.com/GaiaYang/react-ws)（monorepo 內路徑 `packages/react-ws`）
@@ -14,7 +14,7 @@ React 用的 WebSocket **連線層**套件。將連線生命週期、可訂閱
 
 - **零 runtime 依賴** — 僅需 `react >= 18`（peer dependency）
 - **設定凍結** — `url`、`reconnectMs` 等在 `createWsContext` 時固定；執行期以 `connect` / `disconnect` 控制
-- **渲染隔離** — 連線層 state（健康／佇列／重連）走外部 store；訊息走 event emitter，不進 React Context
+- **渲染隔離** — 連線層 state（健康／佇列／重連）走外部 store；訊息經 event emitter 傳遞，以 `useWsEvents` 訂閱（不寫入 React state）
 - **可選探活** — 週期性 ping／pong 偵測，逾時主動關閉 socket 以觸發重連
 - **可選 outbound 佇列** — 未 OPEN 時暫存待送訊息，連線成功後 flush
 
@@ -87,13 +87,13 @@ function Chat() {
 createWsContext(options)
         │
         ├── WsProvider      管理 WebSocket 實例、重連、探活、outbound 佇列
-        ├── useWsActions()  連線操作（send / connect / disconnect），不觸發重繪
-        ├── useWsStore()    訂閱連線層 state：健康／佇列／重連（useSyncExternalStore）
-        └── useWsEvents()  訂閱 open / message / error / close 事件
+        ├── useWsActions()  連線操作（send / connect / disconnect / getStatus），不觸發重繪
+        ├── useWsStore()    訂閱連線層 state：健康／佇列／重連
+        └── useWsEvents()   訂閱 open / message / error / close 事件
 ```
 
 - **同一應用可多次呼叫 `createWsContext`**，每次產生一組互不共用的 Provider 與 hooks（例如同時連業務 WS 與通知 WS）。
-- **Provider 內部 instance** — `useWsStoreApi`（store）、`useWsEventsApi`（emitter）；actions 在 `WsProvider` 內以 `useMemo` 組裝後注入 Context。
+- **Provider 內部** — 各 `WsProvider` 持有獨立的 store 與 event emitter（非公開 API）；actions 在 `WsProvider` 內以 `useMemo` 組裝後注入 Context。
 - **`WsState` 只放連線層、低頻欄位** — 連線健康（`status`、`phase`）、outbound 佇列（如未來 `pendingCount`）、重連（`reconnectAttempt`）。**不放**訊息 payload 或業務資料。
 - **訊息與錯誤事件** — 請用 `useWsEvents`；訊息歷史請自行寫入 state、cache 或外部 store。
 - **連線錯誤不反映在 `WsStatus`** — 請用 `useWsEvents("error", …)` 處理；原生 `error` 事件後通常緊接 `close`。
@@ -108,16 +108,16 @@ createWsContext(options)
 
 #### 參數：`CreateWsContextOptions`
 
-| 欄位               | 型別                                      | 預設     | 說明                                                                                          |
-| ------------------ | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
-| `url`              | `string`                                  | （必填） | WebSocket 連線網址                                                                            |
-| `protocols`        | `string \| string[]`                      | —        | 傳入 `new WebSocket(url, protocols)` 的子協定                                                 |
-| `autoConnect`      | `boolean`                                 | `true`   | `WsProvider` mount 後是否自動呼叫 `connect()`                                                 |
-| `reconnectMs`      | `number`                                  | `0`      | 非主動斷線後的重連間隔（毫秒）；`0` 表示不重連                                                |
-| `reconnectMax`     | `number`                                  | `0`      | 非主動斷線後最多自動重連幾次（不含首次連線）；`0` 不限制。`reconnectAttempt` 於成功 `open`、手動 `connect()` 或 `disconnect()` 歸零 |
-| `outgoingQueueMax` | `number`                                  | `0`      | 未 OPEN 時 outbound 佇列上限；`0` 關閉佇列                                                    |
-| `parse`            | `(data: MessageEvent["data"]) => unknown` | 見下方   | 將原始 `MessageEvent.data` 轉成業務資料                                                       |
-| `liveness`         | `LivenessOptions`                         | —        | 探活設定；省略則不啟用                                                                        |
+| 欄位               | 型別                                      | 預設     | 說明                                                             |
+| ------------------ | ----------------------------------------- | -------- | ---------------------------------------------------------------- |
+| `url`              | `string`                                  | （必填） | WebSocket 連線網址                                               |
+| `protocols`        | `string \| string[]`                      | —        | 傳入 `new WebSocket(url, protocols)` 的子協定                    |
+| `autoConnect`      | `boolean`                                 | `true`   | WsProvider 載入時是否自動連線                                    |
+| `reconnectMs`      | `number`                                  | `0`      | 非主動斷線後的重連間隔（毫秒）；`0` 表示不重連                   |
+| `reconnectMax`     | `number`                                  | `0`      | 非主動斷線後最多自動重連幾次；`0` 不限制（需 `reconnectMs > 0`） |
+| `outgoingQueueMax` | `number`                                  | `0`      | 未 OPEN 時 outbound 佇列上限；`0` 關閉佇列                       |
+| `parse`            | `(data: MessageEvent["data"]) => unknown` | 見下方   | 將原始 `MessageEvent.data` 轉成業務資料                          |
+| `liveness`         | `LivenessOptions`                         | —        | 探活設定；省略則不啟用                                           |
 
 **預設 `parse` 行為：**
 
@@ -139,13 +139,13 @@ createWsContext(options)
 
 負責建立、維護與銷毀原生 `WebSocket` 實例。
 
-| 行為                        | 說明                                                                                                             |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| mount + `autoConnect: true` | 自動 `connect()`                                                                                                 |
-| unmount                     | 取消重連、停止探活、清空 outbound 佇列；store 同步為 `status: "closed"`、`phase: "idle"`；關閉 socket 並 emit `close`（reason: `"provider unmount"`） |
-| `disconnect()`              | 同 unmount 的 store 重置（`phase: "idle"`、`status: "closed"`），但不觸發自動重連；emit `close`（reason: `"client disconnect"`）                         |
-| 重連                        | 非主動斷線且 `reconnectMs > 0` 時，以固定間隔重試（無 exponential backoff）；`reconnectMax > 0` 時超過次數即停止 |
-| 重連前                      | 若已有舊 socket，先關閉並 emit `close`（reason: `"reconnect"`）                                                  |
+| 行為                        | 說明                                                                                                                                                                                                     |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WsProvider` 載入且 `autoConnect: true` | 自動連線                                                                                                                                                                                                 |
+| unmount                     | 取消重連（`reconnectAttempt` 與 `reconnectExhausted` 歸零）、停止探活、清空 outbound 佇列；store 同步為 `status: "closed"`、`phase: "idle"`；關閉 socket 並 emit `close`（reason: `"provider unmount"`） |
+| `disconnect()`              | 同 unmount 的 cleanup 與 store 重置，但不觸發自動重連；emit `close`（reason: `"client disconnect"`）                                                                                                     |
+| 重連                        | 非主動斷線且 `reconnectMs > 0` 時，以固定間隔重試（無 exponential backoff）；`reconnectMax > 0` 時超過次數即停止                                                                                         |
+| `connect()` 時已有舊 socket | 先關閉舊 socket 並 emit `close`（reason: `"reconnect"`），再建立新連線（手動 connect 或自動重連皆同）                                                                                                    |
 
 ---
 
@@ -153,27 +153,29 @@ createWsContext(options)
 
 必須在對應的 `WsProvider` 內使用。回傳值以 `useMemo` 穩定引用，**不會**因 store 或訊息更新而重繪元件。
 
-| 方法         | 簽名                         | 說明                                                                                       |
-| ------------ | ---------------------------- | ------------------------------------------------------------------------------------------ |
-| `send`       | `(data) => boolean`          | 傳送原始資料（`string`、`ArrayBuffer`、`Blob` 等）。已 OPEN 則立即送出；否則視佇列設定入隊 |
-| `sendJson`   | `(data: unknown) => boolean` | `JSON.stringify` 後呼叫 `send`                                                             |
-| `connect`    | `() => void`                 | 建立連線；若已有連線會先關閉舊 socket                                                      |
+| 方法         | 簽名                         | 說明                                                                                             |
+| ------------ | ---------------------------- | ------------------------------------------------------------------------------------------------ |
+| `send`       | `(data) => boolean`          | 傳送原始資料（`string`、`ArrayBuffer`、`Blob` 等）。已 OPEN 則立即送出；否則視佇列設定入隊       |
+| `sendJson`   | `(data: unknown) => boolean` | `JSON.stringify` 後呼叫 `send`；回傳值同 `send`，無法序列化時為 `false`                          |
+| `connect`    | `() => void`                 | 建立連線；若已有連線會先關閉舊 socket（見 `WsProvider`）                                         |
 | `disconnect` | `() => void`                 | 主動斷線；store 設為 `phase: "idle"`、`status: "closed"`，**不**觸發自動重連；清空 outbound 佇列 |
-| `getStatus`  | `() => WsStatus`             | 讀取當下 status；不訂閱、不觸發渲染                                                        |
+| `getStatus`  | `() => WsStatus`             | 讀取當下 status；不訂閱、不觸發渲染                                                              |
 
 **`send` / `sendJson` 回傳值：**
 
 - `true` — 已送出，或已成功入隊
-- `false` — 未 OPEN 且佇列已滿（`outgoingQueueMax > 0` 且達上限），或佇列關閉（`outgoingQueueMax === 0`）；`sendJson` 另含 `JSON.stringify` 失敗（如 circular reference）
+- `false` — 未送出：佇列已滿、佇列關閉，或 `sendJson` 無法序列化
 
 ---
 
 ### `useWsStore()`
 
-必須在對應的 `WsProvider` 內使用。底層以 `useSyncExternalStore` 訂閱外部 store。
+必須在對應的 `WsProvider` 內使用。底層以 `useSyncExternalStore` 訂閱外部 store；**partial 內欄位值未變時不會通知訂閱者**（shallow compare）。
 
 `WsState` 定位：**連線健康／outbound 佇列／重連** 等低頻、連線生命週期資訊。高頻訊息請用 `useWsEvents("message", …)`，不要寫進 store。
 
+**建議：** 以 selector 只訂閱需要的欄位（例如 `(s) => s.phase`）。不帶 selector 的 `useWsStore()` 會訂閱整份 state，任一欄位變更都會觸發 re-render。
+
 ```ts
 useWsStore(): WsState
 useWsStore<T>(selector: (state: WsState) => T): T
@@ -195,9 +197,9 @@ interface WsState {
 }
 ```
 
-| 適合放進 store                                                                                                        | 不適合                                |
-| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| `status`、`phase`、重連進度（`reconnectAttempt` / `reconnectExhausted`）、待送佇列長度、探活／stall 等連線健康摘要 | `lastMessage`、訊息歷史、業務 payload |
+| 適合放進 store                                                                                       | 不適合                                |
+| ---------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `status`、`phase`、重連進度（`reconnectAttempt` / `reconnectExhausted`）、探活／stall 等連線健康摘要 | `lastMessage`、訊息歷史、業務 payload |
 
 `CreateWsContextOptions`（如 `url`、`reconnectMax`）在 `createWsContext` 時凍結，**不在** `WsState`；UI 若需顯示 `n/max` 請自行保存設定值，或訂閱時與 store 欄位組合。
 
@@ -214,17 +216,17 @@ interface WsState {
 
 #### `WsPhase`
 
-| 值              | 意義                                                                 |
-| --------------- | -------------------------------------------------------------------- |
-| `idle`          | 未連線、未排程重連（初始或手動 `disconnect()`）                    |
-| `connecting`    | 首次或手動 `connect()` 連線中                                        |
-| `open`          | 已連線                                                               |
-| `reconnecting`  | 自動重連週期（等待計時器或連線中）；搭配 `status`、`reconnectAttempt` |
-| `stopped`       | 不會再自動重連；`reconnectExhausted` 區分達上限或未啟用重連        |
+| 值             | 意義                                                                  |
+| -------------- | --------------------------------------------------------------------- |
+| `idle`         | 未連線、未排程重連（初始或手動 `disconnect()`）                       |
+| `connecting`   | 首次或手動 `connect()` 連線中                                         |
+| `open`         | 已連線                                                                |
+| `reconnecting` | 自動重連週期（等待計時器或連線中）；搭配 `status`、`reconnectAttempt` |
+| `stopped`      | 不會再自動重連；`reconnectExhausted` 區分達上限或未啟用重連           |
 
 `status` 與 `phase` 常同時變化，但語意不同。例如 `phase === "reconnecting"` 且 `status === "closed"` 表示正在等待重連計時器；`status === "connecting"` 則表示計時器已觸發、正在嘗試連線。
 
-**建議：** 以 selector 只訂閱需要的欄位；state 擴充後可避免不必要的重繪。
+**範例：**
 
 ```tsx
 const phase = useWsStore((s) => s.phase);
@@ -255,19 +257,22 @@ const canDisconnect =
 - `handler` 以 ref 保存最新引用，callback 重建**不會**導致重新訂閱
 - `type` 變更**會**重新訂閱
 - 意外斷線時，`close` handler 觸發前 store 已更新為 `status: "closed"` 及對應 `phase`（`reconnecting` / `stopped` 等）
+- 主動 `disconnect()` 或 Provider unmount 亦同：先更新 store，再 emit `close`
 - 需監聽多種事件時，分別呼叫多次 `useWsEvents`
 
 ---
 
-### 探活：`LivenessOptions`
+### 探活
+
+透過 `createWsContext({ liveness: { … } })` 啟用。連線 OPEN 後週期性送出應用層 ping（經 `send` 送 JSON，非 WebSocket 控制帧）；若在 `timeoutMs` 內未收到符合條件的 pong，主動 `close()` socket（進而觸發重連流程）。
 
-透過 `createWsContext({ liveness: { … } })` 啟用。連線 OPEN 後開始週期性送 ping；若在 `timeoutMs` 內未收到符合條件的 pong，主動 `close()` socket（進而觸發重連流程）。
+`liveness` 選項形狀如下：
 
 ```ts
 interface LivenessOptions {
   intervalMs: number; // ping 間隔（毫秒）
   timeoutMs: number; // 等待 pong 逾時（毫秒）
-  ping: unknown | (() => unknown); // ping  payload；函式則每次動態產生
+  ping: unknown | (() => unknown); // ping payload；函式則每次動態產生
   isPong: (data: unknown) => boolean; // 判定傳入 data 是否為 pong
 }
 ```
@@ -290,7 +295,7 @@ createWsContext({
 });
 ```
 
-探活期間，`onmessage` 收到的每一筆資料都會先經 `isPong` 判定；若為 pong 則重置逾時計時，並照常 emit `"message"` 事件。
+探活期間，`onmessage` 收到的每一筆資料都會先經 `isPong` 判定；若為 pong 則清除逾時計時，並照常 emit `"message"` 事件。ping payload 一律以 `JSON.stringify` 送出（僅支援 JSON 格式）。
 
 ---
 
@@ -298,14 +303,14 @@ createWsContext({
 
 當 `outgoingQueueMax > 0` 時：
 
-| 時機                     | 行為                           |
-| ------------------------ | ------------------------------ |
-| `send` 且 socket 未 OPEN | 訊息入隊（FIFO）               |
-| 佇列已滿                 | 回傳 `false`，**不**丟棄舊訊息 |
-| socket OPEN              | 依序 flush 全部佇列            |
-| `disconnect()`           | 清空佇列                       |
-| `WsProvider` unmount     | 清空佇列                       |
-| 自動重連等待期間         | **保留**佇列                   |
+| 時機                     | 行為                                                      |
+| ------------------------ | --------------------------------------------------------- |
+| `send` 且 socket 未 OPEN | 訊息入隊（FIFO）                                          |
+| 佇列已滿                 | 回傳 `false`，**不**丟棄舊訊息                            |
+| socket OPEN              | 依序 flush 全部佇列                                       |
+| `disconnect()`           | 清空佇列；store 設為 `idle` / `closed`（見 `WsProvider`） |
+| `WsProvider` unmount     | 清空佇列；store 同步（見 `WsProvider`）                   |
+| 自動重連等待期間         | **保留**佇列                                              |
 
 ---
 
@@ -313,14 +318,15 @@ createWsContext({
 
 自 `react-ws-context` 主入口匯出：
 
-| 型別                     | 說明                                               |
-| ------------------------ | -------------------------------------------------- |
-| `CreateWsContextOptions` | `createWsContext` 的選項                           |
-| `WsContextValue`         | `useWsActions()` 回傳型別                          |
-| `WsEvents`               | 事件名稱與 handler 的型別對應                      |
-| `WsStatus`               | WebSocket 連線狀態（`WsState` 的一環）             |
+| 型別                     | 說明                                                |
+| ------------------------ | --------------------------------------------------- |
+| `CreateWsContextOptions` | `createWsContext` 的選項                            |
+| `LivenessOptions`        | `createWsContext` 的 `liveness` 選項                |
+| `WsContextValue`         | `useWsActions()` 回傳型別                           |
+| `WsEvents`               | 事件名稱與 handler 的型別對應                       |
+| `WsStatus`               | WebSocket 連線狀態（`WsState` 的一環）              |
 | `WsPhase`                | Provider 連線意圖與重連策略階段（`WsState` 的一環） |
-| `WsState`                | 可訂閱 store 的 state 形狀（連線健康／佇列／重連） |
+| `WsState`                | 可訂閱 store 的 state 形狀（連線健康／佇列／重連）  |
 
 ---
 
@@ -340,15 +346,15 @@ import {
 } from "react-ws-context/stall";
 ```
 
-| 匯出                         | 說明                                                            |
-| ---------------------------- | --------------------------------------------------------------- |
-| `STALL_MESSAGE_TYPE`         | 客戶端控制訊息 type 常數（`"STALL"`）                           |
-| `STALL_ACK_TYPE`             | 伺服器確認 type 常數（`"STALL_ACK"`）                           |
-| `createStallMessage(action)` | 建立可 `sendJson` 的控制訊息                                    |
-| `parseStallMessage(data)`    | 從 `useWsEvents("message")` 的 `data` 解析；格式不符回傳 `null` |
-| `StallAction`                | `"stall" \| "release"`                                          |
-| `StallMessage`               | `{ type: "STALL"; action: StallAction }`                        |
-| `StallAck`                   | `{ type: "STALL_ACK"; action: StallAction; active: boolean }`   |
+| 匯出                         | 說明                                                                                                   |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `STALL_MESSAGE_TYPE`         | 客戶端控制訊息 type 常數（`"STALL"`）                                                                  |
+| `STALL_ACK_TYPE`             | 伺服器確認 type 常數（`"STALL_ACK"`）— 僅供型別使用，無內建 parser                                     |
+| `createStallMessage(action)` | 建立可 `sendJson` 的客戶端 `STALL` 訊息                                                                |
+| `parseStallMessage(data)`    | 從 `useWsEvents("message")` 的 `data` 解析客戶端 `STALL` 訊息；格式不符回傳 `null`（不含 `STALL_ACK`） |
+| `StallAction`                | `"stall" \| "release"`                                                                                 |
+| `StallMessage`               | `{ type: "STALL"; action: StallAction }`                                                               |
+| `StallAck`                   | `{ type: "STALL_ACK"; action: StallAction; active: boolean }` — 伺服器 ack 請自行解析                  |
 
 **範例：**
 
@@ -367,14 +373,15 @@ sendJson(createStallMessage("stall"));
 
 ## 設計取捨與限制
 
-| 項目           | 說明                                                                                       |
-| -------------- | ------------------------------------------------------------------------------------------ |
-| 設定不可變     | `url`、`reconnectMs` 等建立後固定；需換 URL 請另建 context 或手動 `disconnect` + `connect` |
-| 重連策略       | 固定間隔，無 exponential backoff；`reconnectMax > 0` 可限制次數 |
-| SSR            | 不在 server 建立 `WebSocket`；`connect()` 在 `window` 不存在時為 no-op                     |
-| 錯誤狀態       | 不設 `"error"` status；請監聽 `useWsEvents("error")`                                       |
-| `WsState` 範圍 | 只含連線健康／佇列／重連；訊息與業務資料不走 store                                         |
-| 訊息與渲染     | 只呼叫 `useWsActions` 的元件不會因 store 或 message 重繪                                   |
+| 項目           | 說明                                                                     |
+| -------------- | ------------------------------------------------------------------------ |
+| 設定不可變     | `url`、`reconnectMs` 等建立後固定；要換 URL 請另建一組 `createWsContext` |
+| 重連策略       | 固定間隔，無 exponential backoff；`reconnectMax > 0` 可限制次數          |
+| SSR            | 不在 server 建立 `WebSocket`；`connect()` 在 `window` 不存在時為 no-op   |
+| 錯誤狀態       | 不設 `"error"` status；請監聽 `useWsEvents("error")`                     |
+| `WsState` 範圍 | 只含連線健康／佇列／重連；訊息與業務資料不走 store                       |
+| 訊息與渲染     | 只呼叫 `useWsActions` 的元件不會因 store 或 message 重繪                 |
+| Store 更新     | 相同欄位值重複寫入不觸發訂閱；建議以 selector 訂閱                       |
 
 ---
 
@@ -393,8 +400,8 @@ sendJson(createStallMessage("stall"));
 - **作者／維護：** [pmndrs](https://github.com/pmndrs)（Poimandres）
 - **授權：** [MIT](https://github.com/pmndrs/zustand/blob/main/LICENSE)
 - **借鑑範圍：**
-  - 外部 store（`getState` / `setState` / `subscribe` / `getInitialState`）— 靈感與行為對齊 [`vanilla.ts`](https://github.com/pmndrs/zustand/blob/main/src/vanilla.ts)，非完整搬移（無 middleware、replace、initializer factory）
-  - React 訂閱 hook — 靈感來自 [`react.ts`](https://github.com/pmndrs/zustand/blob/main/src/react.ts) 的 `useStore`（selector 必填、無 `useDebugValue`）
+  - 外部 store（`getState` / `setState` / `subscribe` / `getInitialState`）— 靈感與行為對齊 [`vanilla.ts`](https://github.com/pmndrs/zustand/blob/main/src/vanilla.ts)，非完整搬移（無 middleware、replace、initializer factory）；`setState` 另含 partial shallow dedup（值未變不通知）
+  - React 訂閱 hook — 靈感來自 [`react.ts`](https://github.com/pmndrs/zustand/blob/main/src/react.ts) 的 `useStore`（無 `useDebugValue`）；公開 API 的可選 selector overload 在 `createUseWsStore`
 - **對應原始碼：** `src/ws-context/store.ts`、`src/ws-context/use-store.ts`
 
 ### [nanoevents](https://github.com/ai/nanoevents)
@@ -403,5 +410,5 @@ sendJson(createStallMessage("stall"));
 - **授權：** [MIT](https://github.com/ai/nanoevents/blob/main/LICENSE)
 - **借鑑範圍：**
   - Typed event emitter — 執行期邏輯幾乎對齊 [`createNanoEvents`](https://github.com/ai/nanoevents/blob/main/index.js)；型別為本套件收斂版
-  - `useWsEventsApi` 為本套件自行新增（React `useState` 包裝，見 `ws-events.ts`）
+  - React 訂閱包裝 — 本套件自行新增（`ws-events.ts`）
 - **對應原始碼：** `src/ws-context/emitter.ts`、`src/ws-context/ws-events.ts`

package/dist/index.d.mts

@@ -54,15 +54,15 @@ type WsState = {
 };
 //#endregion
 //#region src/ws-context/liveness/types.d.ts
-/** 探活選項 */
+/** 探活設定 */
 interface LivenessOptions {
-  /** 探活間隔（ms） */
+  /** ping 間隔（毫秒） */
   intervalMs: number;
-  /** 探活超時（ms） */
+  /** 等待 pong 逾時（毫秒） */
   timeoutMs: number;
-  /** 探活訊息 */
+  /** ping 內容；函式則每次動態產生 */
   ping: unknown | (() => unknown);
-  /** 探活回應判定 */
+  /** 判定傳入資料是否為 pong */
   isPong: (data: unknown) => boolean;
 }
 //#endregion
@@ -74,77 +74,78 @@ interface CreateWsContextOptions {
   /** 連線協定 */
   protocols?: string | string[];
   /**
-   * 是否自動重新連線。
+   * 是否在 WsProvider 載入時自動連線。
    *
    * @default true
    */
   autoConnect?: boolean;
   /**
-   * 自動重連間隔（ms）；`0` 不重連。
+   * 非主動斷線後，自動重連的間隔（毫秒）。
+   *
+   * `0` 表示不重連。
    *
    * @default 0
    */
   reconnectMs?: number;
   /**
-   * 非主動斷線後最多自動重連幾次（不含首次 `autoConnect`）。
-   * `reconnectAttempt` 於成功 `open`、手動 `connect()` 或 `disconnect()` 歸零。
+   * 非主動斷線後，最多自動重連幾次。
    *
-   * `0` 不限制（只要 `reconnectMs > 0`）。
+   * `0` 表示不限制；需搭配 `reconnectMs > 0` 才會重連。
    *
    * @default 0
    */
   reconnectMax?: number;
   /**
-   * 未連線時發送訊息的佇列上限；`0` 關閉。
+   * 未連線時，待送訊息的佇列上限。
+   *
+   * `0` 表示關閉佇列。
    *
    * @default 0
    */
   outgoingQueueMax?: number;
   /**
-   * 資料解析函數。
+   * 將原始 `MessageEvent.data` 轉成業務資料。
    *
-   * 預設處理方式：如果資料為字串，嘗試 `JSON.parse`，否則原樣返回。
+   * 預設：字串嘗試 `JSON.parse`，失敗則原樣回傳；非字串原樣回傳。
    */
   parse?: (data: MessageEvent["data"]) => unknown;
-  /** 探活 */
+  /** 探活設定；省略則不啟用 */
   liveness?: LivenessOptions;
 }
 interface WsEvents {
   /**
    * 收到訊息
    *
-   * @param data 訊息內容，已經過 `parse` 處理
-   * @param event 原始事件物件
+   * @param data 經 `parse` 處理後的資料
+   * @param event 原始 `MessageEvent`
    */
   message: (data: unknown, event: MessageEvent) => void;
   /** 連線建立 */
   open: (event: Event) => void;
-  /** 發生錯誤 */
+  /** 連線錯誤 */
   error: (event: Event) => void;
-  /** 連線斷開 */
+  /** 連線關閉 */
   close: (event: CloseEvent) => void;
 }
-/** 連線操作 API；可訂閱的連線層 state（健康／佇列／重連）請用 `useWsStore` */
+/** 連線操作 API；連線層 state 請用 `useWsStore` 訂閱 */
 interface WsContextValue {
   /**
-   * 傳送訊息
+   * 傳送原始資料。
    *
-   * @param data 訊息內容
-   * @returns 是否已送出或已入隊
+   * @returns `true` 表示已送出或已入隊；`false` 表示未送出
    */
   send: (data: Parameters<WebSocket["send"]>[0]) => boolean;
   /**
-   * 傳送 JSON 資料
+   * 以 JSON 傳送資料。
    *
-   * @param data 資料
-   * @returns 是否已送出或已入隊；`JSON.stringify` 失敗（如 circular reference）回傳 `false`
+   * @returns 同 `send`；無法序列化時為 `false`
    */
   sendJson: (data: unknown) => boolean;
   /** 建立連線 */
   connect: () => void;
-  /** 斷開連線 */
+  /** 主動斷開連線 */
   disconnect: () => void;
-  /** 讀取當下 `status`；不訂閱 store、不觸發渲染 */
+  /** 讀取當下 `status`；不訂閱、不觸發渲染 */
   getStatus: () => WsStatus;
 }
 //#endregion
@@ -166,5 +167,5 @@ declare function createWsContext(options: CreateWsContextOptions): {
   useWsEvents: <E extends keyof WsEvents>(type: E, handler: WsEvents[E]) => void;
 };
 //#endregion
-export { type CreateWsContextOptions, type WsContextValue, type WsEvents, type WsPhase, type WsState, type WsStatus, createWsContext };
+export { type CreateWsContextOptions, type LivenessOptions, type WsContextValue, type WsEvents, type WsPhase, type WsState, type WsStatus, createWsContext };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/ws-context/ws-store.ts","../src/ws-context/liveness/types.ts","../src/ws-context/types.ts","../src/ws-context/index.tsx"],"mappings":";;;;;;;;;;;;KAcY;;;;;;;;;;;;KAaA;;;;;;;;;;KAgBA;;EAEV,QAAQ;;EAER,OAAO;;;;;;;;EAQP;;;;;;EAMA;;;;;UC5De;;EAEf;;EAEA;;EAEA;;EAEA,SAAS;;;;;UCLM;;EAEf;;EAEA;;;;;;EAMA;;;;;;EAMA;;;;;;;;;EASA;;;;;;EAMA;;;;;;EAMA,SAAS,MAAM;;EAEf,WAAW;;UAGI;;;;;;;EAOf,UAAU,eAAe,OAAO;;EAEhC,OAAO,OAAO;;EAEd,QAAQ,OAAO;;EAEf,QAAQ,OAAO;;;UAIA;;;;;;;EAOf,OAAO,MAAM,WAAW;;;;;;;EAOxB,WAAW;;EAEX;;EAEA;;EAEA,iBAAiB;;;;;;;;;;;iBC5CH,gBAAgB,SAAS;EAmBL,eAAA,YAAA,sCAAiB,IAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/ws-context/ws-store.ts","../src/ws-context/liveness/types.ts","../src/ws-context/types.ts","../src/ws-context/index.tsx"],"mappings":";;;;;;;;;;;;KAcY;;;;;;;;;;;;KAaA;;;;;;;;;;KAYA;;EAEV,QAAQ;;EAER,OAAO;;;;;;;;EAQP;;;;;;EAMA;;;;;UCxDe;;EAEf;;EAEA;;EAEA;;EAEA,SAAS;;;;;UCLM;;EAEf;;EAEA;;;;;;EAMA;;;;;;;;EAQA;;;;;;;;EAQA;;;;;;;;EAQA;;;;;;EAMA,SAAS,MAAM;;EAEf,WAAW;;UAGI;;;;;;;EAOf,UAAU,eAAe,OAAO;;EAEhC,OAAO,OAAO;;EAEd,QAAQ,OAAO;;EAEf,QAAQ,OAAO;;;UAIA;;;;;;EAMf,OAAO,MAAM,WAAW;;;;;;EAMxB,WAAW;;EAEX;;EAEA;;EAEA,iBAAiB;;;;;;;;;;;iBCxCH,gBAAgB,SAAS;EAmBL,eAAA,YAAA,sCAAiB,IAAA"}

package/dist/index.mjs

@@ -177,7 +177,6 @@ function createStore(initialState) {
 		}
 	};
 }
-/** partial 內所有 key 值與 state 相同則視為無變更，不通知訂閱者 */
 function hasPartialChanged(state, partial) {
 	for (const [key, value] of Object.entries(partial)) if (!Object.is(state[key], value)) return true;
 	return false;
@@ -339,7 +338,13 @@ function createWsContext(options) {
 		const outgoingQueue = useOutgoingQueue(outgoingQueueMax);
 		const livenessSession = useLiveness(liveness, () => wsRef.current);
 		const getStatus = useCallback(() => store.getState().status, [store]);
-		/** 主動斷線與 Provider unmount 共用；`reason` 區分 `"client disconnect"` / `"provider unmount"` */
+		/**
+		* 主動斷線與 Provider unmount 共用 cleanup。
+		*
+		* 關閉 socket 時以 `reason` 寫入 synthetic `close` 事件：
+		* - `"client disconnect"` — `disconnect()`
+		* - `"provider unmount"` — `WsProvider` unmount
+		*/
 		const teardown = useCallback((reason) => {
 			reconnect.cancel();
 			livenessSession.stop();

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/ws-context/emitter.ts","../src/ws-context/ws-events.ts","../src/ws-context/liveness/resolve-ping.ts","../src/ws-context/liveness/controller.ts","../src/ws-context/liveness/liveness.ts","../src/ws-context/outgoing-queue.ts","../src/ws-context/store.ts","../src/ws-context/use-store.ts","../src/ws-context/ws-store.ts","../src/ws-context/ws-actions.ts","../src/ws-context/reconnect.ts","../src/ws-context/socket.ts","../src/ws-context/index.tsx"],"sourcesContent":["// Typed event emitter。\n// 執行期邏輯對齊 nanoevents 的 createNanoEvents（幾乎逐行相同）；型別為本套件收斂版。\n// Project: nanoevents — https://github.com/ai/nanoevents\n// Author: Andrey Sitnik — https://github.com/ai\n// License: MIT — https://github.com/ai/nanoevents/blob/main/LICENSE\n// Source:\n//   - https://github.com/ai/nanoevents/blob/main/index.js\n//   - https://github.com/ai/nanoevents/blob/main/index.d.ts\n// Modifications: 內嵌以達成零 runtime 依賴。\n\nexport interface Emitter<\n  Events extends { [E in keyof Events]: (...args: never[]) => void },\n> {\n  events: { [E in keyof Events]?: Array<Events[E]> };\n  emit<E extends keyof Events>(event: E, ...args: Parameters<Events[E]>): void;\n  on<E extends keyof Events>(event: E, cb: Events[E]): () => void;\n}\n\nexport function createEmitter<\n  Events extends { [E in keyof Events]: (...args: never[]) => void },\n>(): Emitter<Events> {\n  return {\n    events: {},\n    emit(event, ...args) {\n      const callbacks = this.events[event] || [];\n      for (let i = 0, len = callbacks.length; i < len; i++) {\n        callbacks[i]!(...args);\n      }\n    },\n    on(event, cb) {\n      (this.events[event] ||= []).push(cb);\n      return () => {\n        this.events[event] = this.events[event]?.filter((fn) => fn !== cb);\n      };\n    },\n  };\n}\n","import {\n  createContext,\n  useContext,\n  useEffect,\n  useRef,\n  useState,\n  type Context,\n} from \"react\";\nimport { createEmitter, type Emitter } from \"./emitter\";\nimport type { WsEvents } from \"./types\";\n\nexport type WsEventsEmitter = Emitter<WsEvents>;\n\nexport function createWsEventsContext() {\n  return createContext<WsEventsEmitter | null>(null);\n}\n\n/** 每個 `WsProvider` 各有一份 event emitter */\nexport function useWsEventsApi(): WsEventsEmitter {\n  const [emitter] = useState(() => createEmitter<WsEvents>());\n  return emitter;\n}\n\nexport function createUseWsEvents(EventsCtx: Context<WsEventsEmitter | null>) {\n  function useWsEvents<E extends keyof WsEvents>(\n    type: E,\n    handler: WsEvents[E],\n  ): void {\n    const emitter = useContext(EventsCtx);\n    if (!emitter) {\n      throw new Error(\"useWsEvents 必須包在對應的 WsProvider 內\");\n    }\n\n    const handlerRef = useRef(handler);\n\n    useEffect(() => {\n      handlerRef.current = handler;\n    });\n\n    useEffect(() => {\n      return emitter.on(type, ((...args: never[]) => {\n        (handlerRef.current as (...a: never[]) => void)(...args);\n      }) as WsEvents[E]);\n    }, [type, emitter]);\n  }\n\n  return useWsEvents;\n}\n","import type { LivenessOptions } from \"./types\";\n\nexport function resolvePingPayload(ping: LivenessOptions[\"ping\"]): unknown {\n  return typeof ping === \"function\" ? ping() : ping;\n}\n","import { resolvePingPayload } from \"./resolve-ping\";\nimport type { LivenessOptions } from \"./types\";\n\nexport interface LivenessController {\n  /** 開始探活 */\n  start: (sendPing: () => void) => void;\n  /** 停止探活 */\n  stop: () => void;\n  /** 收到訊息 */\n  onMessage: (data: unknown) => void;\n}\n\nexport function createLivenessController(\n  options: LivenessOptions,\n  onTimeout: () => void,\n): LivenessController {\n  const { intervalMs, timeoutMs, isPong } = options;\n\n  let intervalId: ReturnType<typeof setInterval> | null = null;\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n  let sendPingRef: (() => void) | null = null;\n\n  function clearTimeoutTimer(): void {\n    if (timeoutId != null) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n  }\n\n  function armTimeout(): void {\n    clearTimeoutTimer();\n    timeoutId = setTimeout(onTimeout, timeoutMs);\n  }\n\n  function tick(): void {\n    sendPingRef?.();\n    armTimeout();\n  }\n\n  return {\n    start(sendPing) {\n      sendPingRef = sendPing;\n      tick();\n      intervalId = setInterval(tick, intervalMs);\n    },\n\n    stop() {\n      if (intervalId != null) {\n        clearInterval(intervalId);\n        intervalId = null;\n      }\n      clearTimeoutTimer();\n      sendPingRef = null;\n    },\n\n    onMessage(data) {\n      if (isPong(data)) clearTimeoutTimer();\n    },\n  };\n}\n\nexport function createPingSender(\n  ping: LivenessOptions[\"ping\"],\n  sendJson: (data: unknown) => boolean,\n): () => void {\n  return () => {\n    sendJson(resolvePingPayload(ping));\n  };\n}\n","import { useState } from \"react\";\nimport {\n  createLivenessController,\n  createPingSender,\n  type LivenessController,\n} from \"./controller\";\nimport type { LivenessOptions } from \"./types\";\n\nexport interface Liveness {\n  /** 開始探活（socket 由 {@link createLiveness} 的 `getActiveSocket` 取得） */\n  start: () => void;\n  /** 停止探活 */\n  stop: () => void;\n  /** 收到訊息 */\n  onMessage: (data: unknown) => void;\n}\n\nconst DISABLED_LIVENESS: Liveness = {\n  start() {},\n  stop() {},\n  onMessage() {},\n};\n\nexport function createLiveness(\n  options: LivenessOptions,\n  getActiveSocket: () => WebSocket | null,\n): Liveness {\n  let controller: LivenessController | null = null;\n\n  return {\n    start() {\n      controller?.stop();\n      controller = createLivenessController(options, () => {\n        const current = getActiveSocket();\n        if (current?.readyState === WebSocket.OPEN) current.close();\n      });\n      const sendPing = createPingSender(options.ping, (data) => {\n        const current = getActiveSocket();\n        if (!current || current.readyState !== WebSocket.OPEN) return false;\n        current.send(JSON.stringify(data));\n        return true;\n      });\n      controller.start(sendPing);\n    },\n\n    stop() {\n      controller?.stop();\n      controller = null;\n    },\n\n    onMessage(data) {\n      controller?.onMessage(data);\n    },\n  };\n}\n\nexport function useLiveness(\n  options: LivenessOptions | undefined,\n  getActiveSocket: () => WebSocket | null,\n): Liveness {\n  const [session] = useState(() =>\n    options ? createLiveness(options, getActiveSocket) : DISABLED_LIVENESS,\n  );\n  return session;\n}\n","import { useState } from \"react\";\n\nexport type OutgoingData = Parameters<WebSocket[\"send\"]>[0];\n\nexport interface OutgoingQueue {\n  /** 列隊 */\n  enqueue: (data: OutgoingData) => boolean;\n  /** 清空 */\n  clear: () => void;\n  /** 依序送出後清空 */\n  flush: (send: (data: OutgoingData) => void) => void;\n}\n\nexport function createOutgoingQueue(max: number): OutgoingQueue {\n  let items: OutgoingData[] = [];\n\n  return {\n    enqueue(data) {\n      if (max <= 0 || items.length >= max) return false;\n      items.push(data);\n      return true;\n    },\n    clear() {\n      items = [];\n    },\n    flush(send) {\n      const queued = items;\n      items = [];\n      for (const data of queued) send(data);\n    },\n  };\n}\n\nexport function useOutgoingQueue(max: number): OutgoingQueue {\n  const [queue] = useState(() => createOutgoingQueue(max));\n  return queue;\n}\n","// 精簡外部 store：只保留本套件需要的 getState / setState / subscribe / getInitialState。\n// 靈感與行為對齊 zustand/vanilla（非完整搬移；無 middleware、無 replace、無 initializer factory）。\n// Project: zustand — https://github.com/pmndrs/zustand\n// Author: pmndrs (Poimandres) — https://github.com/pmndrs\n// License: MIT — https://github.com/pmndrs/zustand/blob/main/LICENSE\n// Source: https://github.com/pmndrs/zustand/blob/main/src/vanilla.ts\n// Modifications: 內嵌子集以達成零 runtime 依賴。\n\nexport type StoreApi<State> = {\n  getState: () => State;\n  getInitialState: () => State;\n  setState: (\n    partial: Partial<State> | ((state: State) => Partial<State>),\n  ) => void;\n  subscribe: (listener: (state: State, prev: State) => void) => () => void;\n};\n\nexport function createStore<State extends object>(\n  initialState: State,\n): StoreApi<State> {\n  let state = initialState;\n  const listeners = new Set<(state: State, prev: State) => void>();\n\n  return {\n    getState: () => state,\n    getInitialState: () => initialState,\n    setState: (partial) => {\n      const nextPartial =\n        typeof partial === \"function\" ? partial(state) : partial;\n      if (!hasPartialChanged(state, nextPartial)) return;\n      const prev = state;\n      state = Object.assign({}, state, nextPartial);\n      for (const listener of listeners) listener(state, prev);\n    },\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n  };\n}\n\n/** partial 內所有 key 值與 state 相同則視為無變更，不通知訂閱者 */\nfunction hasPartialChanged<State extends object>(\n  state: State,\n  partial: Partial<State>,\n): boolean {\n  for (const [key, value] of Object.entries(partial)) {\n    if (!Object.is(state[key as keyof State], value)) {\n      return true;\n    }\n  }\n  return false;\n}\n","// 訂閱外部 store（selector + useSyncExternalStore）。\n// 靈感來自 zustand/react 的 useStore（非完整搬移；selector 必填、無 useDebugValue）。\n// Project: zustand — https://github.com/pmndrs/zustand\n// Author: pmndrs (Poimandres) — https://github.com/pmndrs\n// License: MIT — https://github.com/pmndrs/zustand/blob/main/LICENSE\n// Source: https://github.com/pmndrs/zustand/blob/main/src/react.ts\n// Modifications: 內嵌以達成零 runtime 依賴。\n// 用途：訂閱 WsState（連線健康／佇列／重連）；訊息不走此 store。\n\nimport { useSyncExternalStore } from \"react\";\nimport type { StoreApi } from \"./store\";\n\nexport function useStore<State, Selected>(\n  store: StoreApi<State>,\n  selector: (state: State) => Selected,\n): Selected {\n  return useSyncExternalStore(\n    store.subscribe,\n    () => selector(store.getState()),\n    () => selector(store.getInitialState()),\n  );\n}\n","import { createContext, useContext, useState, type Context } from \"react\";\nimport { createStore, type StoreApi } from \"./store\";\nimport { useStore } from \"./use-store\";\n\n/**\n * 連線生命週期狀態（`WsState` 的一環）。\n *\n * - `idle` — 尚未連線\n * - `connecting` — 連線中\n * - `open` — 已連線\n * - `closed` — 已斷線\n *\n * 錯誤用 `useWsEvents(\"error\")`；不另設 error status。\n */\nexport type WsStatus = \"idle\" | \"connecting\" | \"open\" | \"closed\";\n\n/**\n * Provider 連線意圖與重連策略階段（`WsState` 的一環）。\n *\n * 與 `status`（WebSocket readyState 映射）正交，補足 UI 無法單靠 `status` 判斷的情境。\n *\n * - `idle` — 未連線、未排程重連（初始或手動 `disconnect()`）\n * - `connecting` — 首次或手動 `connect()` 連線中\n * - `open` — 已連線\n * - `reconnecting` — 自動重連週期（等待計時器或連線中）；細節搭配 `status`、`reconnectAttempt`\n * - `stopped` — 不會再自動重連；`reconnectExhausted` 區分達上限或未啟用重連\n */\nexport type WsPhase =\n  | \"idle\"\n  | \"connecting\"\n  | \"open\"\n  | \"reconnecting\"\n  | \"stopped\";\n\n/**\n * 可訂閱的連線層 state（低頻更新）。\n *\n * 只放：**連線健康**、**outbound 佇列**、**重連** 等連線生命週期資訊。\n *\n * 不放：訊息 payload、訊息歷史、業務資料（請用 `useWsEvents` 或自行管理 state）。\n *\n * 未來可能擴充例如 `pendingCount`；新增欄位時請維持低頻、可 selector 訂閱。\n */\nexport type WsState = {\n  /** 連線生命週期狀態 */\n  status: WsStatus;\n  /** Provider 連線意圖與重連策略階段 */\n  phase: WsPhase;\n  /**\n   * 本輪已排程的自動重連次數（意外斷線當下 +1，非重連成功才 +1）。\n   *\n   * 顯示為 `n` 時，代表第 `n` 次重連已排程或進行中。\n   *\n   * 成功 `open`、手動 `connect()` 或主動 `disconnect()` 歸零。\n   */\n  reconnectAttempt: number;\n  /**\n   * 本輪自動重連已達 `reconnectMax` 且最後一次也失敗。\n   *\n   * 手動 `connect()` 或 `disconnect()` 設定為 `false`\n   */\n  reconnectExhausted: boolean;\n};\n\nexport type WsStoreApi = StoreApi<WsState>;\n\nexport function createWsStore(init: WsStatus = \"idle\"): WsStoreApi {\n  const phase: WsPhase =\n    init === \"open\" || init === \"idle\" ? init : \"connecting\";\n  return createStore<WsState>({\n    status: init,\n    phase,\n    reconnectAttempt: 0,\n    reconnectExhausted: false,\n  });\n}\n\nexport function createWsStoreContext() {\n  return createContext<WsStoreApi | null>(null);\n}\n\n/** 每個 `WsProvider` 各有一份 {@link WsState} store */\nexport function useWsStoreApi(): WsStoreApi {\n  const [store] = useState(() => createWsStore());\n  return store;\n}\n\n/** 訂閱 {@link WsState}；建議以 selector 只取需要的連線層欄位。 */\nexport function createUseWsStore(StoreCtx: Context<WsStoreApi | null>) {\n  function useWsStore(): WsState;\n  function useWsStore<T>(selector: (state: WsState) => T): T;\n  function useWsStore<T>(selector?: (state: WsState) => T): T {\n    const store = useContext(StoreCtx);\n    if (!store) {\n      throw new Error(\"useWsStore 必須包在對應的 WsProvider 內\");\n    }\n    const select = selector ?? ((state: WsState) => state as T);\n    return useStore(store, select);\n  }\n\n  return useWsStore;\n}\n","import { createContext, useContext, type Context } from \"react\";\nimport type { WsContextValue } from \"./types\";\n\n/** actions 無獨立 instance；由 WsProvider 以 useMemo 組裝後注入 Context */\nexport function createWsActionsContext() {\n  return createContext<WsContextValue | null>(null);\n}\n\nexport function createUseWsActions(ActionsCtx: Context<WsContextValue | null>) {\n  function useWsActions(): WsContextValue {\n    const value = useContext(ActionsCtx);\n    if (!value) {\n      throw new Error(\"useWsActions 必須包在對應的 WsProvider 內\");\n    }\n    return value;\n  }\n\n  return useWsActions;\n}\n","import { useState } from \"react\";\n\nexport interface ReconnectCallbacks {\n  /** 讀取 store 的 `reconnectAttempt` */\n  getAttempt: () => number;\n  /** 寫入 store 的 `reconnectAttempt` */\n  setAttempt: (attempt: number) => void;\n  /** 寫入 store 的 `reconnectExhausted` */\n  setExhausted: (exhausted: boolean) => void;\n}\n\nexport interface Reconnect {\n  /** 開始連線時呼叫；回傳 `true` 表示由重連計時器觸發 */\n  onConnectBegin: () => boolean;\n  /** 連線成功時呼叫 */\n  onOpen: () => void;\n  /** 意外斷線後嘗試重連；有排重連回 `true` */\n  scheduleAfterClose: () => boolean;\n  /** 主動斷線或元件卸載時呼叫 */\n  cancel: () => void;\n  /** 設定重連時要執行的 connect */\n  bindOnReconnect: (fn: () => void) => void;\n}\n\nexport function createReconnect(\n  reconnectMs: number,\n  reconnectMax: number,\n  callbacks: ReconnectCallbacks,\n): Reconnect {\n  let intentionalClose = false;\n  let fromTimer = false;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let onReconnect = () => {};\n\n  const clearTimer = () => {\n    if (timer != null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  };\n\n  const resetCycle = () => {\n    if (callbacks.getAttempt() !== 0) callbacks.setAttempt(0);\n    callbacks.setExhausted(false);\n  };\n\n  return {\n    onConnectBegin() {\n      clearTimer();\n      intentionalClose = false;\n      const reconnecting = fromTimer;\n      if (!fromTimer) resetCycle();\n      fromTimer = false;\n      return reconnecting;\n    },\n\n    onOpen() {\n      resetCycle();\n    },\n\n    scheduleAfterClose() {\n      if (intentionalClose || reconnectMs <= 0) return false;\n      const attempt = callbacks.getAttempt();\n      if (reconnectMax > 0 && attempt >= reconnectMax) {\n        callbacks.setExhausted(true);\n        return false;\n      }\n      callbacks.setAttempt(attempt + 1);\n      fromTimer = true;\n      // 固定間隔重連，無 backoff；之後可換成指數退避\n      timer = setTimeout(() => {\n        timer = null;\n        onReconnect();\n      }, reconnectMs);\n      return true;\n    },\n\n    cancel() {\n      intentionalClose = true;\n      clearTimer();\n      resetCycle();\n    },\n\n    bindOnReconnect(fn) {\n      onReconnect = fn;\n    },\n  };\n}\n\nexport function useReconnect(\n  reconnectMs: number,\n  reconnectMax: number,\n  callbacks: ReconnectCallbacks,\n): Reconnect {\n  const [session] = useState(() =>\n    createReconnect(reconnectMs, reconnectMax, callbacks),\n  );\n  return session;\n}\n","export function detachAndClose(ws: WebSocket): void {\n  ws.onopen = null;\n  ws.onmessage = null;\n  ws.onerror = null;\n  ws.onclose = null;\n  if (ws.readyState < WebSocket.CLOSING) ws.close();\n}\n\nexport function clientCloseEvent(reason: string): CloseEvent {\n  return new CloseEvent(\"close\", {\n    code: 1000,\n    reason,\n    wasClean: true,\n  });\n}\n","import {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  type PropsWithChildren,\n} from \"react\";\nimport { createUseWsEvents, createWsEventsContext, useWsEventsApi } from \"./ws-events\";\nimport type { CreateWsContextOptions, WsContextValue } from \"./types\";\nimport { useLiveness } from \"./liveness/liveness\";\nimport { useOutgoingQueue } from \"./outgoing-queue\";\nimport {\n  createUseWsStore,\n  createWsStoreContext,\n  useWsStoreApi,\n  type WsPhase,\n} from \"./ws-store\";\nimport { createUseWsActions, createWsActionsContext } from \"./ws-actions\";\nimport { useReconnect } from \"./reconnect\";\nimport { clientCloseEvent, detachAndClose } from \"./socket\";\n\nexport type { CreateWsContextOptions, WsContextValue, WsEvents } from \"./types\";\n\nfunction defaultParse(data: MessageEvent[\"data\"]): unknown {\n  if (typeof data !== \"string\") return data;\n  try {\n    return JSON.parse(data) as unknown;\n  } catch {\n    return data;\n  }\n}\n\n/**\n * @example\n * ```ts\n * export const { WsProvider, useWsActions, useWsStore, useWsEvents } =\n *   createWsContext({ url: \"ws://localhost:8080\" });\n * ```\n */\nexport function createWsContext(options: CreateWsContextOptions) {\n  const {\n    url,\n    protocols,\n    autoConnect = true,\n    reconnectMs = 0,\n    reconnectMax = 0,\n    outgoingQueueMax = 0,\n    parse = defaultParse,\n    liveness,\n  } = options;\n\n  const StoreCtx = createWsStoreContext();\n  const useWsStore = createUseWsStore(StoreCtx);\n  const ActionsCtx = createWsActionsContext();\n  const useWsActions = createUseWsActions(ActionsCtx);\n  const EventsCtx = createWsEventsContext();\n  const useWsEvents = createUseWsEvents(EventsCtx);\n\n  function WsProvider({ children }: PropsWithChildren) {\n    const wsRef = useRef<WebSocket | null>(null);\n    const store = useWsStoreApi();\n    const emitter = useWsEventsApi();\n    const reconnect = useReconnect(reconnectMs, reconnectMax, {\n      getAttempt: () => store.getState().reconnectAttempt,\n      setAttempt: (reconnectAttempt) => store.setState({ reconnectAttempt }),\n      setExhausted: (reconnectExhausted) =>\n        store.setState({ reconnectExhausted }),\n    });\n    const outgoingQueue = useOutgoingQueue(outgoingQueueMax);\n    const livenessSession = useLiveness(liveness, () => wsRef.current);\n\n    const getStatus = useCallback<WsContextValue[\"getStatus\"]>(\n      () => store.getState().status,\n      [store],\n    );\n\n    /** 主動斷線與 Provider unmount 共用；`reason` 區分 `\"client disconnect\"` / `\"provider unmount\"` */\n    const teardown = useCallback(\n      (reason: string) => {\n        reconnect.cancel();\n        livenessSession.stop();\n        outgoingQueue.clear();\n        store.setState({ phase: \"idle\", status: \"closed\" });\n        const ws = wsRef.current;\n        wsRef.current = null;\n        if (ws) {\n          detachAndClose(ws);\n          emitter.emit(\"close\", clientCloseEvent(reason));\n        }\n      },\n      [store, emitter, outgoingQueue, livenessSession, reconnect],\n    );\n\n    const disconnect = useCallback<WsContextValue[\"disconnect\"]>(\n      () => teardown(\"client disconnect\"),\n      [teardown],\n    );\n\n    const connect = useCallback<WsContextValue[\"connect\"]>(() => {\n      if (typeof window === \"undefined\") return;\n\n      const fromReconnect = reconnect.onConnectBegin();\n      livenessSession.stop();\n\n      const prev = wsRef.current;\n      if (prev) {\n        wsRef.current = null;\n        detachAndClose(prev);\n        emitter.emit(\"close\", clientCloseEvent(\"reconnect\"));\n      }\n\n      store.setState({\n        status: \"connecting\",\n        phase: fromReconnect ? \"reconnecting\" : \"connecting\",\n      });\n\n      const ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);\n      wsRef.current = ws;\n\n      ws.onopen = (event) => {\n        if (wsRef.current !== ws) return;\n        reconnect.onOpen();\n        store.setState({ status: \"open\", phase: \"open\" });\n        outgoingQueue.flush((data) => ws.send(data));\n        livenessSession.start();\n        emitter.emit(\"open\", event);\n      };\n\n      ws.onmessage = (event) => {\n        if (wsRef.current !== ws) return;\n        const data = parse(event.data);\n        livenessSession.onMessage(data);\n        emitter.emit(\"message\", data, event);\n      };\n\n      ws.onerror = (event) => {\n        if (wsRef.current !== ws) return;\n        emitter.emit(\"error\", event);\n      };\n\n      ws.onclose = (event) => {\n        if (wsRef.current === ws) wsRef.current = null;\n        livenessSession.stop();\n        const scheduled = reconnect.scheduleAfterClose();\n        // 意外斷線：先更新 store，再 emit close（handler 可讀到一致的 status / phase）\n        const patch: { status: \"closed\"; phase?: WsPhase } = { status: \"closed\" };\n        if (scheduled) {\n          patch.phase = \"reconnecting\";\n        } else if (store.getState().phase !== \"idle\") {\n          patch.phase = \"stopped\";\n        }\n        store.setState(patch);\n        emitter.emit(\"close\", event);\n      };\n    }, [store, emitter, outgoingQueue, livenessSession, reconnect]);\n\n    reconnect.bindOnReconnect(connect);\n\n    useEffect(() => {\n      if (autoConnect) connect();\n      return () => teardown(\"provider unmount\");\n    }, [connect, teardown]);\n\n    const send = useCallback<WsContextValue[\"send\"]>(\n      (data) => {\n        const ws = wsRef.current;\n        if (ws && ws.readyState === WebSocket.OPEN) {\n          ws.send(data);\n          return true;\n        }\n        return outgoingQueue.enqueue(data);\n      },\n      [outgoingQueue],\n    );\n\n    const sendJson = useCallback<WsContextValue[\"sendJson\"]>(\n      (data) => {\n        try {\n          return send(JSON.stringify(data));\n        } catch {\n          return false;\n        }\n      },\n      [send],\n    );\n\n    const actions = useMemo<WsContextValue>(\n      () => ({ send, sendJson, connect, disconnect, getStatus }),\n      [send, sendJson, connect, disconnect, getStatus],\n    );\n\n    return (\n      <ActionsCtx.Provider value={actions}>\n        <StoreCtx.Provider value={store}>\n          <EventsCtx.Provider value={emitter}>{children}</EventsCtx.Provider>\n        </StoreCtx.Provider>\n      </ActionsCtx.Provider>\n    );\n  }\n\n  return {\n    WsProvider,\n    useWsActions,\n    useWsStore,\n    useWsEvents,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/ws-context/emitter.ts","../src/ws-context/ws-events.ts","../src/ws-context/liveness/resolve-ping.ts","../src/ws-context/liveness/controller.ts","../src/ws-context/liveness/liveness.ts","../src/ws-context/outgoing-queue.ts","../src/ws-context/store.ts","../src/ws-context/use-store.ts","../src/ws-context/ws-store.ts","../src/ws-context/ws-actions.ts","../src/ws-context/reconnect.ts","../src/ws-context/socket.ts","../src/ws-context/index.tsx"],"sourcesContent":["// Typed event emitter。\n// 執行期邏輯對齊 nanoevents 的 createNanoEvents（幾乎逐行相同）；型別為本套件收斂版。\n// Project: nanoevents — https://github.com/ai/nanoevents\n// Author: Andrey Sitnik — https://github.com/ai\n// License: MIT — https://github.com/ai/nanoevents/blob/main/LICENSE\n// Source:\n//   - https://github.com/ai/nanoevents/blob/main/index.js\n//   - https://github.com/ai/nanoevents/blob/main/index.d.ts\n// Modifications: 內嵌以達成零 runtime 依賴。\n\nexport interface Emitter<\n  Events extends { [E in keyof Events]: (...args: never[]) => void },\n> {\n  events: { [E in keyof Events]?: Array<Events[E]> };\n  emit<E extends keyof Events>(event: E, ...args: Parameters<Events[E]>): void;\n  on<E extends keyof Events>(event: E, cb: Events[E]): () => void;\n}\n\nexport function createEmitter<\n  Events extends { [E in keyof Events]: (...args: never[]) => void },\n>(): Emitter<Events> {\n  return {\n    events: {},\n    emit(event, ...args) {\n      const callbacks = this.events[event] || [];\n      for (let i = 0, len = callbacks.length; i < len; i++) {\n        callbacks[i]!(...args);\n      }\n    },\n    on(event, cb) {\n      (this.events[event] ||= []).push(cb);\n      return () => {\n        this.events[event] = this.events[event]?.filter((fn) => fn !== cb);\n      };\n    },\n  };\n}\n","import {\n  createContext,\n  useContext,\n  useEffect,\n  useRef,\n  useState,\n  type Context,\n} from \"react\";\nimport { createEmitter, type Emitter } from \"./emitter\";\nimport type { WsEvents } from \"./types\";\n\nexport type WsEventsEmitter = Emitter<WsEvents>;\n\nexport function createWsEventsContext() {\n  return createContext<WsEventsEmitter | null>(null);\n}\n\n/** 每個 `WsProvider` 各有一份 event emitter */\nexport function useWsEventsApi(): WsEventsEmitter {\n  const [emitter] = useState(() => createEmitter<WsEvents>());\n  return emitter;\n}\n\nexport function createUseWsEvents(EventsCtx: Context<WsEventsEmitter | null>) {\n  function useWsEvents<E extends keyof WsEvents>(\n    type: E,\n    handler: WsEvents[E],\n  ): void {\n    const emitter = useContext(EventsCtx);\n    if (!emitter) {\n      throw new Error(\"useWsEvents 必須包在對應的 WsProvider 內\");\n    }\n\n    const handlerRef = useRef(handler);\n\n    useEffect(() => {\n      handlerRef.current = handler;\n    });\n\n    useEffect(() => {\n      return emitter.on(type, ((...args: never[]) => {\n        (handlerRef.current as (...a: never[]) => void)(...args);\n      }) as WsEvents[E]);\n    }, [type, emitter]);\n  }\n\n  return useWsEvents;\n}\n","import type { LivenessOptions } from \"./types\";\n\nexport function resolvePingPayload(ping: LivenessOptions[\"ping\"]): unknown {\n  return typeof ping === \"function\" ? ping() : ping;\n}\n","import { resolvePingPayload } from \"./resolve-ping\";\nimport type { LivenessOptions } from \"./types\";\n\nexport interface LivenessController {\n  /** 開始探活 */\n  start: (sendPing: () => void) => void;\n  /** 停止探活 */\n  stop: () => void;\n  /** 收到訊息 */\n  onMessage: (data: unknown) => void;\n}\n\nexport function createLivenessController(\n  options: LivenessOptions,\n  onTimeout: () => void,\n): LivenessController {\n  const { intervalMs, timeoutMs, isPong } = options;\n\n  let intervalId: ReturnType<typeof setInterval> | null = null;\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n  let sendPingRef: (() => void) | null = null;\n\n  function clearTimeoutTimer(): void {\n    if (timeoutId != null) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n  }\n\n  function armTimeout(): void {\n    clearTimeoutTimer();\n    timeoutId = setTimeout(onTimeout, timeoutMs);\n  }\n\n  function tick(): void {\n    sendPingRef?.();\n    armTimeout();\n  }\n\n  return {\n    start(sendPing) {\n      sendPingRef = sendPing;\n      tick();\n      intervalId = setInterval(tick, intervalMs);\n    },\n\n    stop() {\n      if (intervalId != null) {\n        clearInterval(intervalId);\n        intervalId = null;\n      }\n      clearTimeoutTimer();\n      sendPingRef = null;\n    },\n\n    onMessage(data) {\n      if (isPong(data)) clearTimeoutTimer();\n    },\n  };\n}\n\nexport function createPingSender(\n  ping: LivenessOptions[\"ping\"],\n  sendJson: (data: unknown) => boolean,\n): () => void {\n  return () => {\n    sendJson(resolvePingPayload(ping));\n  };\n}\n","import { useState } from \"react\";\nimport {\n  createLivenessController,\n  createPingSender,\n  type LivenessController,\n} from \"./controller\";\nimport type { LivenessOptions } from \"./types\";\n\nexport interface Liveness {\n  /** 開始探活（socket 由 {@link createLiveness} 的 `getActiveSocket` 取得） */\n  start: () => void;\n  /** 停止探活 */\n  stop: () => void;\n  /** 收到訊息 */\n  onMessage: (data: unknown) => void;\n}\n\nconst DISABLED_LIVENESS: Liveness = {\n  start() {},\n  stop() {},\n  onMessage() {},\n};\n\nexport function createLiveness(\n  options: LivenessOptions,\n  getActiveSocket: () => WebSocket | null,\n): Liveness {\n  let controller: LivenessController | null = null;\n\n  return {\n    start() {\n      controller?.stop();\n      controller = createLivenessController(options, () => {\n        const current = getActiveSocket();\n        if (current?.readyState === WebSocket.OPEN) current.close();\n      });\n      const sendPing = createPingSender(options.ping, (data) => {\n        const current = getActiveSocket();\n        if (!current || current.readyState !== WebSocket.OPEN) return false;\n        current.send(JSON.stringify(data));\n        return true;\n      });\n      controller.start(sendPing);\n    },\n\n    stop() {\n      controller?.stop();\n      controller = null;\n    },\n\n    onMessage(data) {\n      controller?.onMessage(data);\n    },\n  };\n}\n\nexport function useLiveness(\n  options: LivenessOptions | undefined,\n  getActiveSocket: () => WebSocket | null,\n): Liveness {\n  const [session] = useState(() =>\n    options ? createLiveness(options, getActiveSocket) : DISABLED_LIVENESS,\n  );\n  return session;\n}\n","import { useState } from \"react\";\n\nexport type OutgoingData = Parameters<WebSocket[\"send\"]>[0];\n\nexport interface OutgoingQueue {\n  /** 列隊 */\n  enqueue: (data: OutgoingData) => boolean;\n  /** 清空 */\n  clear: () => void;\n  /** 依序送出後清空 */\n  flush: (send: (data: OutgoingData) => void) => void;\n}\n\nexport function createOutgoingQueue(max: number): OutgoingQueue {\n  let items: OutgoingData[] = [];\n\n  return {\n    enqueue(data) {\n      if (max <= 0 || items.length >= max) return false;\n      items.push(data);\n      return true;\n    },\n    clear() {\n      items = [];\n    },\n    flush(send) {\n      const queued = items;\n      items = [];\n      for (const data of queued) send(data);\n    },\n  };\n}\n\nexport function useOutgoingQueue(max: number): OutgoingQueue {\n  const [queue] = useState(() => createOutgoingQueue(max));\n  return queue;\n}\n","// 精簡外部 store：只保留本套件需要的 getState / setState / subscribe / getInitialState。\n// 靈感與行為對齊 zustand/vanilla（非完整搬移；無 middleware、無 replace、無 initializer factory）。\n// Project: zustand — https://github.com/pmndrs/zustand\n// Author: pmndrs (Poimandres) — https://github.com/pmndrs\n// License: MIT — https://github.com/pmndrs/zustand/blob/main/LICENSE\n// Source: https://github.com/pmndrs/zustand/blob/main/src/vanilla.ts\n// Modifications: 內嵌子集以達成零 runtime 依賴。\n\nexport type StoreApi<State> = {\n  getState: () => State;\n  getInitialState: () => State;\n  setState: (\n    partial: Partial<State> | ((state: State) => Partial<State>),\n  ) => void;\n  subscribe: (listener: (state: State, prev: State) => void) => () => void;\n};\n\nexport function createStore<State extends object>(\n  initialState: State,\n): StoreApi<State> {\n  let state = initialState;\n  const listeners = new Set<(state: State, prev: State) => void>();\n\n  return {\n    getState: () => state,\n    getInitialState: () => initialState,\n    setState: (partial) => {\n      const nextPartial =\n        typeof partial === \"function\" ? partial(state) : partial;\n      if (!hasPartialChanged(state, nextPartial)) return;\n      const prev = state;\n      state = Object.assign({}, state, nextPartial);\n      for (const listener of listeners) listener(state, prev);\n    },\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n  };\n}\n\nfunction hasPartialChanged<State extends object>(\n  state: State,\n  partial: Partial<State>,\n): boolean {\n  for (const [key, value] of Object.entries(partial)) {\n    if (!Object.is(state[key as keyof State], value)) {\n      return true;\n    }\n  }\n  return false;\n}\n","// 訂閱外部 store（selector + useSyncExternalStore）。\n// 靈感來自 zustand/react 的 useStore（非完整搬移；本層 selector 必填、無 useDebugValue）。\n// Project: zustand — https://github.com/pmndrs/zustand\n// Author: pmndrs (Poimandres) — https://github.com/pmndrs\n// License: MIT — https://github.com/pmndrs/zustand/blob/main/LICENSE\n// Source: https://github.com/pmndrs/zustand/blob/main/src/react.ts\n// Modifications: 內嵌以達成零 runtime 依賴。\n// 用途：訂閱 WsState（連線健康／佇列／重連）；訊息不走此 store。\n\nimport { useSyncExternalStore } from \"react\";\nimport type { StoreApi } from \"./store\";\n\nexport function useStore<State, Selected>(\n  store: StoreApi<State>,\n  selector: (state: State) => Selected,\n): Selected {\n  return useSyncExternalStore(\n    store.subscribe,\n    () => selector(store.getState()),\n    () => selector(store.getInitialState()),\n  );\n}\n","import { createContext, useContext, useState, type Context } from \"react\";\nimport { createStore, type StoreApi } from \"./store\";\nimport { useStore } from \"./use-store\";\n\n/**\n * 連線生命週期狀態（`WsState` 的一環）。\n *\n * - `idle` — 尚未連線\n * - `connecting` — 連線中\n * - `open` — 已連線\n * - `closed` — 已斷線\n *\n * 錯誤用 `useWsEvents(\"error\")`；不另設 error status。\n */\nexport type WsStatus = \"idle\" | \"connecting\" | \"open\" | \"closed\";\n\n/**\n * Provider 連線意圖與重連策略階段（`WsState` 的一環）。\n *\n * 與 `status`（WebSocket readyState 映射）正交，補足 UI 無法單靠 `status` 判斷的情境。\n *\n * - `idle` — 未連線、未排程重連（初始或手動 `disconnect()`）\n * - `connecting` — 首次或手動 `connect()` 連線中\n * - `open` — 已連線\n * - `reconnecting` — 自動重連週期（等待計時器或連線中）；細節搭配 `status`、`reconnectAttempt`\n * - `stopped` — 不會再自動重連；`reconnectExhausted` 區分達上限或未啟用重連\n */\nexport type WsPhase =\n  \"idle\" | \"connecting\" | \"open\" | \"reconnecting\" | \"stopped\";\n\n/**\n * 可訂閱的連線層 state（低頻更新）。\n *\n * 只放：**連線健康**、**outbound 佇列**、**重連** 等連線生命週期資訊。\n *\n * 不放：訊息 payload、訊息歷史、業務資料（請用 `useWsEvents` 或自行管理 state）。\n *\n * 未來可能擴充例如 `pendingCount`；新增欄位時請維持低頻、可 selector 訂閱。\n */\nexport type WsState = {\n  /** 連線生命週期狀態 */\n  status: WsStatus;\n  /** Provider 連線意圖與重連策略階段 */\n  phase: WsPhase;\n  /**\n   * 本輪已排程的自動重連次數（意外斷線當下 +1，非重連成功才 +1）。\n   *\n   * 顯示為 `n` 時，代表第 `n` 次重連已排程或進行中。\n   *\n   * 成功 `open`、手動 `connect()` 或主動 `disconnect()` 歸零。\n   */\n  reconnectAttempt: number;\n  /**\n   * 本輪自動重連已達 `reconnectMax` 且最後一次也失敗。\n   *\n   * 手動 `connect()` 或 `disconnect()` 設定為 `false`\n   */\n  reconnectExhausted: boolean;\n};\n\nexport type WsStoreApi = StoreApi<WsState>;\n\nexport function createWsStore(init: WsStatus = \"idle\"): WsStoreApi {\n  const phase: WsPhase =\n    init === \"open\" || init === \"idle\" ? init : \"connecting\";\n  return createStore<WsState>({\n    status: init,\n    phase,\n    reconnectAttempt: 0,\n    reconnectExhausted: false,\n  });\n}\n\nexport function createWsStoreContext() {\n  return createContext<WsStoreApi | null>(null);\n}\n\n/** 每個 `WsProvider` 各有一份 {@link WsState} store */\nexport function useWsStoreApi(): WsStoreApi {\n  const [store] = useState(() => createWsStore());\n  return store;\n}\n\n/** 訂閱 {@link WsState}；建議以 selector 只取需要的連線層欄位。 */\nexport function createUseWsStore(StoreCtx: Context<WsStoreApi | null>) {\n  function useWsStore(): WsState;\n  function useWsStore<T>(selector: (state: WsState) => T): T;\n  function useWsStore<T>(selector?: (state: WsState) => T): T {\n    const store = useContext(StoreCtx);\n    if (!store) {\n      throw new Error(\"useWsStore 必須包在對應的 WsProvider 內\");\n    }\n    const select = selector ?? ((state: WsState) => state as T);\n    return useStore(store, select);\n  }\n\n  return useWsStore;\n}\n","import { createContext, useContext, type Context } from \"react\";\nimport type { WsContextValue } from \"./types\";\n\n/** actions 無獨立 instance；由 WsProvider 以 useMemo 組裝後注入 Context */\nexport function createWsActionsContext() {\n  return createContext<WsContextValue | null>(null);\n}\n\nexport function createUseWsActions(ActionsCtx: Context<WsContextValue | null>) {\n  function useWsActions(): WsContextValue {\n    const value = useContext(ActionsCtx);\n    if (!value) {\n      throw new Error(\"useWsActions 必須包在對應的 WsProvider 內\");\n    }\n    return value;\n  }\n\n  return useWsActions;\n}\n","import { useState } from \"react\";\n\nexport interface ReconnectCallbacks {\n  /** 讀取 store 的 `reconnectAttempt` */\n  getAttempt: () => number;\n  /** 寫入 store 的 `reconnectAttempt` */\n  setAttempt: (attempt: number) => void;\n  /** 寫入 store 的 `reconnectExhausted` */\n  setExhausted: (exhausted: boolean) => void;\n}\n\nexport interface Reconnect {\n  /** 開始連線時呼叫；回傳 `true` 表示由重連計時器觸發 */\n  onConnectBegin: () => boolean;\n  /** 連線成功時呼叫 */\n  onOpen: () => void;\n  /** 意外斷線後嘗試重連；有排重連回 `true` */\n  scheduleAfterClose: () => boolean;\n  /** 主動斷線或元件卸載時呼叫 */\n  cancel: () => void;\n  /** 設定重連時要執行的 connect */\n  bindOnReconnect: (fn: () => void) => void;\n}\n\nexport function createReconnect(\n  reconnectMs: number,\n  reconnectMax: number,\n  callbacks: ReconnectCallbacks,\n): Reconnect {\n  let intentionalClose = false;\n  let fromTimer = false;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let onReconnect = () => {};\n\n  const clearTimer = () => {\n    if (timer != null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  };\n\n  const resetCycle = () => {\n    if (callbacks.getAttempt() !== 0) callbacks.setAttempt(0);\n    callbacks.setExhausted(false);\n  };\n\n  return {\n    onConnectBegin() {\n      clearTimer();\n      intentionalClose = false;\n      const reconnecting = fromTimer;\n      if (!fromTimer) resetCycle();\n      fromTimer = false;\n      return reconnecting;\n    },\n\n    onOpen() {\n      resetCycle();\n    },\n\n    scheduleAfterClose() {\n      if (intentionalClose || reconnectMs <= 0) return false;\n      const attempt = callbacks.getAttempt();\n      if (reconnectMax > 0 && attempt >= reconnectMax) {\n        callbacks.setExhausted(true);\n        return false;\n      }\n      callbacks.setAttempt(attempt + 1);\n      fromTimer = true;\n      // 固定間隔重連，無 backoff；之後可換成指數退避\n      timer = setTimeout(() => {\n        timer = null;\n        onReconnect();\n      }, reconnectMs);\n      return true;\n    },\n\n    cancel() {\n      intentionalClose = true;\n      clearTimer();\n      resetCycle();\n    },\n\n    bindOnReconnect(fn) {\n      onReconnect = fn;\n    },\n  };\n}\n\nexport function useReconnect(\n  reconnectMs: number,\n  reconnectMax: number,\n  callbacks: ReconnectCallbacks,\n): Reconnect {\n  const [session] = useState(() =>\n    createReconnect(reconnectMs, reconnectMax, callbacks),\n  );\n  return session;\n}\n","export function detachAndClose(ws: WebSocket): void {\n  ws.onopen = null;\n  ws.onmessage = null;\n  ws.onerror = null;\n  ws.onclose = null;\n  if (ws.readyState < WebSocket.CLOSING) ws.close();\n}\n\nexport function clientCloseEvent(reason: string): CloseEvent {\n  return new CloseEvent(\"close\", {\n    code: 1000,\n    reason,\n    wasClean: true,\n  });\n}\n","import {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  type PropsWithChildren,\n} from \"react\";\nimport {\n  createUseWsEvents,\n  createWsEventsContext,\n  useWsEventsApi,\n} from \"./ws-events\";\nimport type { CreateWsContextOptions, WsContextValue } from \"./types\";\nimport { useLiveness } from \"./liveness/liveness\";\nimport { useOutgoingQueue } from \"./outgoing-queue\";\nimport {\n  createUseWsStore,\n  createWsStoreContext,\n  useWsStoreApi,\n  type WsPhase,\n} from \"./ws-store\";\nimport { createUseWsActions, createWsActionsContext } from \"./ws-actions\";\nimport { useReconnect } from \"./reconnect\";\nimport { clientCloseEvent, detachAndClose } from \"./socket\";\n\nexport type { CreateWsContextOptions, WsContextValue, WsEvents } from \"./types\";\nexport type { LivenessOptions } from \"./liveness/types\";\n\nfunction defaultParse(data: MessageEvent[\"data\"]): unknown {\n  if (typeof data !== \"string\") return data;\n  try {\n    return JSON.parse(data) as unknown;\n  } catch {\n    return data;\n  }\n}\n\n/**\n * @example\n * ```ts\n * export const { WsProvider, useWsActions, useWsStore, useWsEvents } =\n *   createWsContext({ url: \"ws://localhost:8080\" });\n * ```\n */\nexport function createWsContext(options: CreateWsContextOptions) {\n  const {\n    url,\n    protocols,\n    autoConnect = true,\n    reconnectMs = 0,\n    reconnectMax = 0,\n    outgoingQueueMax = 0,\n    parse = defaultParse,\n    liveness,\n  } = options;\n\n  const StoreCtx = createWsStoreContext();\n  const useWsStore = createUseWsStore(StoreCtx);\n  const ActionsCtx = createWsActionsContext();\n  const useWsActions = createUseWsActions(ActionsCtx);\n  const EventsCtx = createWsEventsContext();\n  const useWsEvents = createUseWsEvents(EventsCtx);\n\n  function WsProvider({ children }: PropsWithChildren) {\n    const wsRef = useRef<WebSocket | null>(null);\n    const store = useWsStoreApi();\n    const emitter = useWsEventsApi();\n    const reconnect = useReconnect(reconnectMs, reconnectMax, {\n      getAttempt: () => store.getState().reconnectAttempt,\n      setAttempt: (reconnectAttempt) => store.setState({ reconnectAttempt }),\n      setExhausted: (reconnectExhausted) =>\n        store.setState({ reconnectExhausted }),\n    });\n    const outgoingQueue = useOutgoingQueue(outgoingQueueMax);\n    const livenessSession = useLiveness(liveness, () => wsRef.current);\n\n    const getStatus = useCallback<WsContextValue[\"getStatus\"]>(\n      () => store.getState().status,\n      [store],\n    );\n\n    /**\n     * 主動斷線與 Provider unmount 共用 cleanup。\n     *\n     * 關閉 socket 時以 `reason` 寫入 synthetic `close` 事件：\n     * - `\"client disconnect\"` — `disconnect()`\n     * - `\"provider unmount\"` — `WsProvider` unmount\n     */\n    const teardown = useCallback(\n      (reason: string) => {\n        reconnect.cancel();\n        livenessSession.stop();\n        outgoingQueue.clear();\n        store.setState({ phase: \"idle\", status: \"closed\" });\n        const ws = wsRef.current;\n        wsRef.current = null;\n        if (ws) {\n          detachAndClose(ws);\n          emitter.emit(\"close\", clientCloseEvent(reason));\n        }\n      },\n      [store, emitter, outgoingQueue, livenessSession, reconnect],\n    );\n\n    const disconnect = useCallback<WsContextValue[\"disconnect\"]>(\n      () => teardown(\"client disconnect\"),\n      [teardown],\n    );\n\n    const connect = useCallback<WsContextValue[\"connect\"]>(() => {\n      if (typeof window === \"undefined\") return;\n\n      const fromReconnect = reconnect.onConnectBegin();\n      livenessSession.stop();\n\n      const prev = wsRef.current;\n      if (prev) {\n        wsRef.current = null;\n        detachAndClose(prev);\n        emitter.emit(\"close\", clientCloseEvent(\"reconnect\"));\n      }\n\n      store.setState({\n        status: \"connecting\",\n        phase: fromReconnect ? \"reconnecting\" : \"connecting\",\n      });\n\n      const ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);\n      wsRef.current = ws;\n\n      ws.onopen = (event) => {\n        if (wsRef.current !== ws) return;\n        reconnect.onOpen();\n        store.setState({ status: \"open\", phase: \"open\" });\n        outgoingQueue.flush((data) => ws.send(data));\n        livenessSession.start();\n        emitter.emit(\"open\", event);\n      };\n\n      ws.onmessage = (event) => {\n        if (wsRef.current !== ws) return;\n        const data = parse(event.data);\n        livenessSession.onMessage(data);\n        emitter.emit(\"message\", data, event);\n      };\n\n      ws.onerror = (event) => {\n        if (wsRef.current !== ws) return;\n        emitter.emit(\"error\", event);\n      };\n\n      ws.onclose = (event) => {\n        if (wsRef.current === ws) wsRef.current = null;\n        livenessSession.stop();\n        const scheduled = reconnect.scheduleAfterClose();\n        // 意外斷線：先更新 store，再 emit close（handler 可讀到一致的 status / phase）\n        const patch: { status: \"closed\"; phase?: WsPhase } = {\n          status: \"closed\",\n        };\n        if (scheduled) {\n          patch.phase = \"reconnecting\";\n        } else if (store.getState().phase !== \"idle\") {\n          patch.phase = \"stopped\";\n        }\n        store.setState(patch);\n        emitter.emit(\"close\", event);\n      };\n    }, [store, emitter, outgoingQueue, livenessSession, reconnect]);\n\n    reconnect.bindOnReconnect(connect);\n\n    useEffect(() => {\n      if (autoConnect) connect();\n      return () => teardown(\"provider unmount\");\n    }, [connect, teardown]);\n\n    const send = useCallback<WsContextValue[\"send\"]>(\n      (data) => {\n        const ws = wsRef.current;\n        if (ws && ws.readyState === WebSocket.OPEN) {\n          ws.send(data);\n          return true;\n        }\n        return outgoingQueue.enqueue(data);\n      },\n      [outgoingQueue],\n    );\n\n    const sendJson = useCallback<WsContextValue[\"sendJson\"]>(\n      (data) => {\n        try {\n          return send(JSON.stringify(data));\n        } catch {\n          return false;\n        }\n      },\n      [send],\n    );\n\n    const actions = useMemo<WsContextValue>(\n      () => ({ send, sendJson, connect, disconnect, getStatus }),\n      [send, sendJson, connect, disconnect, getStatus],\n    );\n\n    return (\n      <ActionsCtx.Provider value={actions}>\n        <StoreCtx.Provider value={store}>\n          <EventsCtx.Provider value={emitter}>{children}</EventsCtx.Provider>\n        </StoreCtx.Provider>\n      </ActionsCtx.Provider>\n    );\n  }\n\n  return {\n    WsProvider,\n    useWsActions,\n    useWsStore,\n    useWsEvents,\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-ws-context",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "React WebSocket connection layer — separate hooks for actions, connection state, and message events to avoid unnecessary re-renders",
   "keywords": [
     "react",