<!-- source-hash: dcf2e60dac262a108cfeb8aa720addd1 -->
Subscribes a React component to a NATS JetStream ephemeral ordered consumer for a specific chat dialog, managing connection lifecycle, reconnection backoff, and sequence-aware resumption.

## Key Components

- **`useJetStreamDialogSubscription`** — Primary hook export. Manages a shared NATS WebSocket connection (ref-counted singleton) and an ephemeral JetStream `OrderedConsumer` scoped to `chat.{dialogId}.{topic}`.
- **`SharedConnection`** — Module-level singleton tracking the active NATS client, ref count, and deferred close/retry timers to avoid redundant reconnects across component instances.
- **`acquireClient`** — Increments the shared connection ref count (or creates a new client if the URL changed), cancelling any pending close timer.
- **`releaseClient`** — Decrements the ref count and schedules a deferred close (`SHARED_CLOSE_DELAY_MS`) when the last consumer releases the connection.
- **Connection effect** — Drives `connect()` / status-listener lifecycle; implements jittered exponential backoff with optional fast-retry leading attempts via `reconnectionBackoff`.
- **Subscription effect** — Recreates the ephemeral consumer on each `isConnected` transition, resuming from `highestStreamSeq + 1` to avoid replaying or skipping chunks.

## Usage Example

```typescript
const { isConnected, isSubscribed, reconnectionCount, currentStreamSeq } =
  useJetStreamDialogSubscription({
    enabled: true,
    dialogId: 'dialog-abc123',
    topic: 'events',
    optStartSeq: lastKnownSeq,         // null → live-tail (DeliverPolicy.New)
    getNatsWsUrl: () => 'wss://nats.example.com',
    onEvent: (data) => console.log('chunk received', data),
    onConnect: () => console.log('connected'),
    onDisconnect: () => console.log('disconnected'),
    reconnectionBackoff: {
      fastRetries: 3,
      fastRetryDelayMs: 200,
      initialDelayMs: 500,
      maxDelayMs: 30_000,
      multiplier: 2,
    },
    inactiveThresholdMs: 5 * 60_000,
  })
```

## Notes

- Protocol-level `-ERR` events (e.g. ACL violations) are logged as warnings but do **not** trigger reconnect, preventing auth-refresh loops.
- The shared connection singleton is module-scoped, so multiple hook instances sharing the same WebSocket URL reuse one NATS client.