@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/hooks/ui/.use-focus-trap.md

@@ -0,0 +1,59 @@
+<!-- source-hash: 5a28579d80860450719a15e80835fea5 -->
+Provides a React hook for managing keyboard focus within overlay UI surfaces (modals, sidebars, nav panels), handling initial focus, Tab cycling, Escape key handling, and guarded focus restoration on close.
+
+## Key Components
+
+### `useFocusTrap(containerRef, active, options)`
+
+The primary export. Attaches a container-scoped `keydown` listener when `active` is `true` and cleans up on deactivate.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `containerRef` | `RefObject<HTMLElement \| null>` | Ref to the overlay container element |
+| `active` | `boolean` | Enables/disables the trap |
+| `options` | `UseFocusTrapOptions` | Optional configuration |
+
+### `UseFocusTrapOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `onEscape` | `() => void` | — | Called on Escape keypress; passes through without `stopPropagation` |
+| `contain` | `boolean` | `true` | When `false`, disables Tab cycling (for non-modal surfaces like sliding sidebars) |
+
+### `FOCUSABLE_SELECTOR`
+
+Internal CSS selector matching all interactive, non-disabled, visible elements eligible for Tab focus.
+
+## Usage Example
+
+```typescript
+import { useRef } from 'react'
+import { useFocusTrap } from './use-focus-trap'
+
+function MobileNavPanel({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
+  const panelRef = useRef<HTMLDivElement>(null)
+
+  // Tab cycles within the panel; Escape triggers onClose
+  useFocusTrap(panelRef, isOpen, { onEscape: onClose })
+
+  return (
+    // tabIndex={-1} is required — see hook CONTRACT
+    <div ref={panelRef} tabIndex={-1}>
+      <a href="/home">Home</a>
+      <button onClick={onClose}>Close</button>
+    </div>
+  )
+}
+```
+
+> **Contract:** The container element **must** have `tabIndex={-1}`. Without it, clicking non-focusable areas inside the surface moves focus to `body`, causing the trap to stop receiving keyboard events.
+
+## Behavior Notes
+
+- **Stacking-safe:** Listener is container-scoped, so a modal opened above a sidebar will not leak its Escape event downward.
+- **Stable callback:** `onEscape` is stored in a `useRef` to prevent the effect from re-running on every inline function re-render.
+- **Guarded restore:** On deactivate, focus returns to the previously focused element only if focus has not moved to another intentional target (e.g. a dialog that opened during the overlay's lifetime).
+
+## Source
+
+[`use-focus-trap.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-focus-trap.ts)

package/src/hooks/ui/.use-header-height.md

@@ -0,0 +1,37 @@
+<!-- source-hash: 542d3494c008ba1da83803f8b2a5a8bc -->
+React hook that measures and tracks the combined pixel height of the sticky page header and optional announcement bar in real time, using `ResizeObserver` and `MutationObserver`.
+
+## Key Components
+
+- **`useHeaderHeight(defaultHeight?, options?)`** — Main export. Queries `<header>` and `[data-announcement-bar]` elements, sums their `offsetHeight` values, and re-measures whenever either element resizes or the DOM changes.
+- **`enabled` option** — Gates all observer setup. When `false`, skips measurement and returns `defaultHeight` immediately, avoiding document-wide observers for components that are always mounted but only need the value while an overlay is open.
+- **`ResizeObserver`** — Watches both the header and announcement bar for size changes.
+- **`MutationObserver`** — Watches `document.body` for child list changes or `data-announcement-bar` attribute mutations (e.g., bar appearing/disappearing dynamically), then re-observes the bar if it's newly added.
+
+## Usage Example
+
+```typescript
+import { useHeaderHeight } from './use-header-height'
+
+// Basic usage — offsets a fixed panel below the header
+function SearchOverlay({ isOpen }: { isOpen: boolean }) {
+  const headerHeight = useHeaderHeight(64, { enabled: isOpen })
+
+  return (
+    <div
+      style={{ top: headerHeight }}
+      className="fixed inset-x-0 bottom-0 z-50"
+    >
+      {/* panel content */}
+    </div>
+  )
+}
+```
+
+> Pass `enabled: isOpen` to avoid attaching document-wide observers when the overlay is closed.
+
+## Notes
+
+- Falls back to `defaultHeight` (default `64`) when no matching elements are found or when `enabled` is `false`.
+- Observers are fully disconnected on unmount or when `enabled` changes to `false`.
+- Source: [`use-header-height.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-header-height.ts)

package/src/hooks/ui/.use-horizontal-scrollbar.md

@@ -1,28 +1,24 @@
-<!-- source-hash: 9f63d7c2dd408b85d0a130f82da97780 -->
-Custom React hook for building a fully controlled horizontal scrollbar with drag, click-to-seek, wheel forwarding, edge-fade indicators, and RAF-throttled sync — all driven directly against the DOM without relying on native scrollbar styling.
+<!-- source-hash: a8097b26f77c0c63a9b433f937ece2a5 -->
+A React hook that manages a custom horizontal scrollbar with thumb sizing, position syncing, drag interaction, edge-fade indicators, and RAF-throttled scroll handling — all driven directly against the DOM for performance.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `useHorizontalScrollbar` | Hook | Main hook returning all refs, state, and event handlers |
-| `scrollRef` | Callback ref | Attach to the scrollable container; auto-sets up `ResizeObserver` |
-| `trackRef` | `RefObject<HTMLDivElement>` | Attach to the scrollbar track element |
-| `thumbRef` | `RefObject<HTMLDivElement>` | Attach to the draggable thumb element |
-| `thumbRatio` | `number` | Thumb width as a fraction of track width (`0` = hidden) |
-| `canScrollLeft` | `boolean` | Whether content can scroll further left (for edge fades) |
-| `canScrollRight` | `boolean` | Whether content can scroll further right (for edge fades) |
+**`useHorizontalScrollbar()`** — the single export; returns everything needed to wire up a scrollable container and its custom scrollbar UI.
 
-**Event Handlers Returned:**
+### Returned Values
 
-| Handler | Attach To |
-|---------|-----------|
-| `onScroll` | Scrollable container `onScroll` |
-| `onTrackClick` | Track element `onClick` |
-| `onTrackWheel` | Track element `onWheel` |
-| `onThumbPointerDown` | Thumb `onPointerDown` |
-| `onThumbPointerMove` | Thumb `onPointerMove` |
-| `onThumbPointerUp` | Thumb `onPointerUp` |
+| Name | Type | Description |
+|---|---|---|
+| `scrollRef` | callback ref | Attach to the scrollable container; sets up `ResizeObserver` + `MutationObserver` automatically |
+| `trackRef` | `RefObject<HTMLDivElement>` | Attach to the scrollbar track element |
+| `thumbRef` | `RefObject<HTMLDivElement>` | Attach to the scrollbar thumb element |
+| `thumbRatio` | `number` | Thumb width as a fraction of track width (`0` when no overflow) |
+| `canScrollLeft` | `boolean` | `true` when content is scrolled past the left edge |
+| `canScrollRight` | `boolean` | `true` when more content exists to the right |
+| `onScroll` | handler | RAF-throttled; attach to the container's `onScroll` |
+| `onTrackClick` | handler | Scrolls to clicked position on the track |
+| `onTrackWheel` | handler | Forwards wheel events from the track to the scroll container |
+| `onThumbPointerDown/Move/Up` | handlers | Full pointer-capture drag implementation |
 
 ## Usage Example
 
@@ -40,29 +36,20 @@ function ScrollableTable() {
   return (
     <div>
       {canScrollLeft && <div className="fade-left" />}
-
-      {/* Scrollable content */}
       <div ref={scrollRef} onScroll={onScroll} style={{ overflowX: 'auto' }}>
-        <table>{/* wide content */}</table>
+        {/* wide content */}
       </div>
-
       {canScrollRight && <div className="fade-right" />}
 
-      {/* Custom scrollbar */}
-      {thumbRatio > 0 && (
-        <div
-          ref={trackRef}
-          onClick={onTrackClick}
-          onWheel={onTrackWheel}
-          style={{ position: 'relative', height: 8 }}
-        >
+      {thumbRatio > 0 && thumbRatio < 1 && (
+        <div ref={trackRef} onClick={onTrackClick} onWheel={onTrackWheel}>
           <div
             ref={thumbRef}
             data-scrollbar-thumb
+            style={{ width: `${thumbRatio * 100}%`, position: 'absolute' }}
             onPointerDown={onThumbPointerDown}
             onPointerMove={onThumbPointerMove}
             onPointerUp={onThumbPointerUp}
-            style={{ position: 'absolute', width: `${thumbRatio * 100}%`, cursor: 'grab' }}
           />
         </div>
       )}
@@ -71,4 +58,8 @@ function ScrollableTable() {
 }
 ```
 
-> **Performance note:** Thumb position is written directly to `thumb.style.left` via `requestAnimationFrame`, bypassing React re-renders on every scroll event. Only `thumbRatio`, `canScrollLeft`, and `canScrollRight` trigger state updates.
+## Notes
+
+- `scrollRef` is a **callback ref**, so observer setup runs correctly even when the container mounts asynchronously (e.g. after data loads).
+- Thumb position is updated **directly on the DOM** (`thumb.style.left`) during scroll and drag to avoid React re-render overhead.
+- `ResizeObserver` watches both the container and its children; a `MutationObserver` re-observes when children change, keeping thumb size accurate after dynamic content updates.

package/src/hooks/ui/.use-marquee-engine.md

@@ -0,0 +1,73 @@
+<!-- source-hash: d8118aab70c3c6c9b39223ea34e7dd94 -->
+Provides a reusable `requestAnimationFrame` position engine for endless-scroll marquee animations, decoupled from any specific DOM strategy (scroll position or CSS transform).
+
+## Key Components
+
+### `MarqueeEngineOptions` (interface)
+
+Configuration object passed to the hook:
+
+| Option | Description |
+|---|---|
+| `active` | Master switch; enables/disables the rAF loop |
+| `speed` | Cruise speed in px/s |
+| `isPaused` | Per-frame pause verdict function (caller-owned reason set) |
+| `getWrapSize` | Returns the single-copy width/height for seam wrapping |
+| `getWrapMin` | Optional lower bound of the wrap range (default `0`) |
+| `apply` | Writes position to the DOM (`scrollLeft` or `transform`) |
+| `readBack` | Reads externally mutated position (user drag, native scroll) |
+| `onAfterFrame` | Called after each frame (e.g. hover re-resolution) |
+
+### `MarqueeEngineHandle` (interface)
+
+Returned by the hook:
+
+| Member | Description |
+|---|---|
+| `posRef` | Float position ref in px; callers may write during seam warps |
+| `glideBy(px)` | Accumulates a signed glide distance for chevron navigation |
+| `wrap(pos)` | Utility to normalize any position into `[0, wrapSize)` |
+
+### `useMarqueeEngine(options)` (hook)
+
+Core export. Manages three internal refs (`posRef`, `glideRemainingRef`, `speedEnvRef`), a latest-options ref to avoid restarting the rAF loop on every render, and the main `tick` function handling:
+
+- **Velocity envelope** — ~250ms ease between `0` and `speed` (smooth pause/resume)
+- **Glide mode** — proportional ease-out for chevron navigation, wrapping modulo copy size
+- **Cruise mode** — steady advance at enveloped speed with external resync
+- **Idle mode** — follows external scroll position so resume starts from current location
+
+## Usage Example
+
+```typescript
+// CardsStrip (horizontal scroller driver)
+const engine = useMarqueeEngine({
+  active: isVisible,
+  speed: 80,
+  isPaused: (now) => pauseReasons.size > 0 || suppressUntil > now,
+  getWrapSize: () => trackRef.current?.scrollWidth / 2 ?? 0,
+  getWrapMin: () => SEAM_BUFFER,
+  apply: (pos) => { if (trackRef.current) trackRef.current.scrollLeft = pos },
+  readBack: () => trackRef.current?.scrollLeft ?? 0,
+  onAfterFrame: resolveHover,
+})
+
+// Chevron navigation
+engine.glideBy(cardWidth)
+
+// MarqueeWall (transform driver — no readBack needed)
+const engine = useMarqueeEngine({
+  active: true,
+  speed: 50,
+  isPaused: () => !isVisible,
+  getWrapSize: () => trackRef.current?.offsetWidth / 2 ?? 0,
+  apply: (pos) => {
+    if (trackRef.current)
+      trackRef.current.style.transform = `translateX(${-pos}px)`
+  },
+})
+```
+
+## Source
+
+[`use-marquee-engine.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-marquee-engine.ts)

package/src/hooks/ui/.use-notification-permission.md

@@ -0,0 +1,49 @@
+<!-- source-hash: d6766f600f05a52d295b880209627895 -->
+React hook that tracks and requests browser desktop notification permission, with cross-browser support including a Safari compatibility fallback.
+
+## Key Components
+
+### `UseNotificationPermissionResult` (interface)
+
+| Property | Type | Description |
+|---|---|---|
+| `supported` | `boolean` | Whether the Notification API is available (false during SSR or on iOS Safari) |
+| `permission` | `NotificationPermission` | Current permission state: `"default"`, `"granted"`, or `"denied"` |
+| `request` | `() => Promise<NotificationPermission>` | Prompts the user for permission; must be triggered by a user gesture |
+
+### `useNotificationPermission()` (hook)
+
+Initializes permission state and registers three sync strategies to stay current:
+
+1. **Permissions API** — `navigator.permissions.query({ name: 'notifications' })` change event (Chrome, Firefox)
+2. **Visibility change** — re-reads `Notification.permission` when the tab becomes visible (Safari fallback)
+3. **Window focus** — re-reads on focus for cases where the user changed site settings in a browser panel
+
+Cleans up all listeners on unmount via a `cancelled` flag guard to prevent attaching listeners after the effect tears down.
+
+## Usage Example
+
+```typescript
+import { useNotificationPermission } from './use-notification-permission'
+
+function NotificationToggle() {
+  const { supported, permission, request } = useNotificationPermission()
+
+  if (!supported) return null
+
+  return (
+    <button
+      onClick={request}
+      disabled={permission === 'granted' || permission === 'denied'}
+    >
+      {permission === 'granted'
+        ? 'Notifications enabled'
+        : permission === 'denied'
+        ? 'Notifications blocked'
+        : 'Enable notifications'}
+    </button>
+  )
+}
+```
+
+> **Note:** Call `request()` only inside a user gesture handler (click, keydown, etc.). Browsers silently deny programmatic calls made outside a gesture context.

package/src/hooks/ui/.use-reset-on-page-hidden.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 9b85f4bd4fed063a86a9725221200835 -->
+Resets a callback whenever the browser tab is hidden or the window loses focus, guarding against `pointerleave`/`pointercancel` events being swallowed during tab switches or overlay interruptions.
+
+## Key Components
+
+- **`useResetOnPageHidden(reset)`** — React hook that attaches `blur` (on `window`) and `visibilitychange` (on `document`) listeners; invokes `reset` when either fires (visibility only on `'hidden'`). Cleans up both listeners on unmount or when `reset` identity changes.
+
+## Usage Example
+
+```typescript
+import { useCallback, useState } from 'react'
+import { useResetOnPageHidden } from './use-reset-on-page-hidden'
+
+function MarqueeWall() {
+  const [isHovered, setIsHovered] = useState(false)
+
+  // Must be stable — memoize with useCallback to avoid re-attaching listeners
+  const resetHover = useCallback(() => setIsHovered(false), [])
+
+  useResetOnPageHidden(resetHover)
+
+  return (
+    <div
+      onPointerEnter={() => setIsHovered(true)}
+      onPointerLeave={() => setIsHovered(false)}
+    >
+      {/* marquee pauses when isHovered is true */}
+    </div>
+  )
+}
+```
+
+## Notes
+
+- Pass a **stable** `reset` reference (via `useCallback`) — the hook re-attaches listeners whenever `reset`'s identity changes.
+- `blur` fires even when `visibilitychange` does not (e.g., a second window focused alongside this tab), making both listeners necessary.
+- On `blur` without tab hiding, the marquee may briefly resume under a stationary cursor in the unfocused window; it re-pauses on the next `pointermove`/`pointerenter`.
+- Intended as the single wiring point (SSOT) for all marquee surfaces (`MarqueeWall`, `CardsStrip`).
+
+**Source:** [`use-reset-on-page-hidden.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-reset-on-page-hidden.ts)

package/src/hooks/ui/.use-suppress-clone-focus.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 6043e94056db9c7b4cc50fc1680e236a -->
+Keeps a marquee clone's interactive elements clickable while removing them from keyboard tab order and the accessibility tree — solving the "clone cards swallow clicks" bug caused by using `inert`.
+
+## Key Components
+
+**`CLONE_FOCUSABLE_SELECTOR`** — Comprehensive CSS selector covering all natively focusable elements: anchors, form controls, `iframe`, `summary`, media with `controls`, `[tabindex]`, and editable content regions.
+
+**`useSuppressCloneFocus(active: boolean)`** — React hook that returns a `ref` to attach to a clone wrapper `<div>`. When `active`, it:
+- Sets `tabindex="-1"` on every focusable descendant (removes duplicate tab stops)
+- Watches for DOM mutations that could re-introduce tabbable elements via `MutationObserver`
+- Leaves click/pointer behavior fully intact (unlike `inert`, which blocks all interaction)
+- Re-applies suppression only when `tabindex` hasn't already been stamped, preventing infinite observer loops
+
+## Usage Example
+
+```typescript
+import { useSuppressCloneFocus } from './use-suppress-clone-focus'
+
+function MarqueeClone({ isClone }: { isClone: boolean }) {
+  const cloneRef = useSuppressCloneFocus(isClone)
+
+  return (
+    // aria-hidden keeps clone out of a11y tree;
+    // hook keeps it out of tab order while staying clickable
+    <div ref={cloneRef} aria-hidden={isClone}>
+      <a href="/article-1">Card One</a>
+      <a href="/article-2">Card Two</a>
+    </div>
+  )
+}
+```
+
+## Accessibility Contract
+
+| Mechanism | Handled by |
+|---|---|
+| Out of a11y tree | `aria-hidden` on clone wrapper (caller's responsibility) |
+| Out of tab order | This hook (`tabindex="-1"` on all focusable descendants) |
+| Clickable / pointer events | Preserved — clone anchors handle mouse, <kbd>⌘</kbd>-click, middle-click, and context menu natively |
+
+> **Why not `inert`?** The `inert` attribute also disables pointer events, causing clone cards near the seam of an endless-loop scroll to silently swallow all clicks — the core bug this hook is designed to prevent.

package/src/nats/.index.md

@@ -0,0 +1,39 @@
+<!-- source-hash: c277685d024b3565e47f9f7688345fba -->
+Barrel export file that re-exports all public API symbols from the NATS messaging module's submodules into a single entry point.
+
+## Key Components
+
+| Export Source | Description |
+|---|---|
+| `./nats` | Core NATS client utilities and types |
+| `./shared-connection` | Shared/singleton NATS connection management |
+| `./nats-provider` | NATS provider setup and configuration |
+| `./use-nats-subscription` | Composable for subscribing to NATS subjects |
+
+## Usage Example
+
+```typescript
+// Import everything from a single entry point
+import {
+  createNatsConnection,
+  sharedConnection,
+  NatsProvider,
+  useNatsSubscription,
+} from '@openframe/nats'
+
+// Subscribe to a subject using the composable
+const { messages, unsubscribe } = useNatsSubscription('msp.tickets.>')
+
+// Use the shared connection directly
+const nc = await sharedConnection()
+await nc.publish('msp.events.created', JSON.stringify({ id: 42 }))
+```
+
+## Notes
+
+- Import from this index rather than individual submodules to avoid internal path coupling.
+- Tree-shaking remains effective — bundlers resolve each `export *` to its originating module.
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/nats/.nats-provider.md

@@ -0,0 +1,46 @@
+<!-- source-hash: ab1964ccd3e26ab6a9f1caf2c64d5367 -->
+Manages a shared NATS WebSocket connection within a React component tree, exposing connection state and client access via context.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `NatsProvider` | Component | Establishes and maintains a NATS connection lifecycle; handles connect, reconnect, and teardown |
+| `useNats` | Hook | Returns `NatsContextValue`; throws if used outside `<NatsProvider>` |
+| `useOptionalNats` | Hook | Returns `NatsContextValue | null`; safe to call outside a provider |
+| `NatsProviderProps` | Interface | Props for `NatsProvider`, including `getWsUrl`, `onBeforeReconnect`, `clientConfig`, `reconnectionBackoff`, and `urlRevision` |
+| `NatsContextValue` | Interface | `{ client, status, isReady, reconnectionCount }` available to consumers |
+| `NatsReconnectionBackoff` | Re-export | Backoff configuration type from `shared-connection` |
+
+**`urlRevision`** is the primary mechanism to trigger URL re-evaluation (e.g., after an auth state change). Increment or change it to restart the connection lifecycle.
+
+## Usage Example
+
+```typescript
+import { NatsProvider, useNats } from './nats-provider'
+
+function App() {
+  const [revision, setRevision] = React.useState(0)
+  const getWsUrl = () => session ? `wss://nats.example.com?token=${session.token}` : null
+
+  return (
+    <NatsProvider
+      getWsUrl={getWsUrl}
+      urlRevision={revision}
+      onBeforeReconnect={async () => { await refreshSession() }}
+      reconnectionBackoff={{ initialDelayMs: 500, maxDelayMs: 10_000 }}
+    >
+      <MyComponent />
+    </NatsProvider>
+  )
+}
+
+function MyComponent() {
+  const { client, status, isReady, reconnectionCount } = useNats()
+
+  if (!isReady) return <p>Connecting… ({status})</p>
+  return <p>Connected — reconnections: {reconnectionCount}</p>
+}
+```
+
+**Source:** [`nats-provider.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/nats-provider.tsx)

package/src/nats/.nats.md

@@ -1,25 +1,32 @@
-<!-- source-hash: 418321f518535eef27f0004848e1e1b3 -->
-A browser/Tauri-only NATS client factory for WebSocket-based NATS connections (`nats.ws`), providing typed pub/sub, request/reply, JetStream ordered consumer subscriptions, and connection lifecycle management.
+<!-- source-hash: 67f40ff2bcded544220309f5fd1f87ad -->
+Browser/Tauri-compatible NATS client factory built on `nats.ws`, providing typed publish, subscribe, request-reply, and JetStream ordered consumer support with connection lifecycle management.
 
 ## Key Components
 
 ### Interfaces & Types
+
 | Export | Description |
-|--------|-------------|
-| `NatsClient` | Core client interface with all pub/sub/request/JetStream methods |
-| `NatsClientOptions` | Connection config: servers, auth, reconnect, exponential backoff, ping |
+|---|---|
+| `NatsClient` | Core client interface with connect/close/publish/subscribe/request methods |
+| `NatsClientOptions` | Connection config including servers, auth, reconnect, and exponential backoff |
 | `NatsSubscribeOptions` | Per-subscription options: queue group, max messages, abort signal |
-| `NatsPublishOptions` / `NatsRequestOptions` | Optional headers and timeout per operation |
-| `JetStreamOrderedSubscribeOptions` | JetStream ephemeral consumer config: stream, filter, deliver policy, start sequence |
-| `NatsStatus` / `NatsStatusEvent` | Connection state machine: `connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error` |
+| `NatsPublishOptions` / `NatsRequestOptions` | Optional headers and timeout for publish/request operations |
+| `JetStreamOrderedSubscribeOptions` | JetStream ephemeral consumer config with deliver policy and idle threshold |
+| `NatsStatus` / `NatsStatusEvent` | Union type and event shape for connection lifecycle events |
+| `JetStreamDeliverPolicy` | `'new'` or `'byStartSequence'` for ordered consumer replay |
+
+### Functions
 
-### Factory Function
-- **`createNatsClient(options)`** — Returns a `NatsClient` instance. Lazily imports `nats.ws` (browser-safe). All methods are lazy-connected and browser-only (throws if `window` is undefined).
+| Export | Description |
+|---|---|
+| `createNatsClient(options)` | Factory function — returns a fully-implemented `NatsClient` instance |
 
 ### Internal Helpers
-- **`createExponentialBackoffHandler`** — Configurable exponential backoff with optional crypto jitter for reconnect delays.
-- **`toNatsHeaders`** — Converts `Record<string, string>` or native `NatsHeaders` into a `nats.ws` headers object.
-- **`mapNatsTypeToStatus`** — Normalizes raw `nats.ws` status events to the typed `NatsStatus` union.
+
+- `createExponentialBackoffHandler` — configurable backoff with optional jitter using `crypto.getRandomValues`
+- `mapOptionsToConnectionOptions` — maps `NatsClientOptions` to `nats.ws` `ConnectionOptions`
+- `toNatsHeaders` — converts `Record<string, string>` or existing `NatsHeaders` into a `nats.ws` headers object
+- `assertClientSide` — throws if called outside a browser/WebSocket-capable runtime
 
 ## Usage Example
 
@@ -28,36 +35,36 @@ import { createNatsClient } from './nats'
 
 const client = createNatsClient({
   servers: 'wss://nats.example.com:443',
-  name: 'flamingo-ui',
   token: 'my-token',
   exponentialBackoff: {
     initialDelayMs: 500,
     maxDelayMs: 15_000,
-    multiplier: 2,
     jitter: true,
   },
 })
 
-// Listen for connection status changes
-const off = client.onStatus((event) => {
-  console.log('NATS status:', event.status)
-})
+client.onStatus(({ status }) => console.log('NATS status:', status))
 
 await client.connect()
 
-// Typed JSON publish
-client.publishJson('telemetry.events', { deviceId: 'abc', value: 42 })
+// Publish JSON
+client.publishJson('events.user.created', { id: '123', name: 'Alice' })
 
-// Typed JSON request/reply
+// Request-reply
 const response = await client.requestJson<{ ok: boolean }>(
-  'devices.query',
-  { id: 'abc' },
+  'rpc.user.create',
+  { name: 'Bob' },
   { timeoutMs: 3000 },
 )
 
-// JetStream ordered consumer (live-tail)
+// Core subscribe
+client.subscribeJson<{ id: string }>('events.user.*', (payload, msg) => {
+  console.log('Received:', payload)
+})
+
+// JetStream ordered (live-tail)
 const handle = await client.subscribeJetStreamOrdered(
-  (msg) => console.log('JetStream msg:', msg.seq),
+  (msg) => console.log('JetStream:', msg.subject),
   {
     streamName: 'EVENTS',
     filterSubject: 'events.>',
@@ -67,6 +74,9 @@ const handle = await client.subscribeJetStreamOrdered(
 
 // Cleanup
 handle.unsubscribe()
-off()
 await client.close()
-```
+```
+
+## Source
+
+[`nats.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/nats.ts)

package/src/nats/.shared-connection.md

@@ -0,0 +1,56 @@
+<!-- source-hash: 4006bdcdcf2f95808859b2ac679a5c98 -->
+Manages a per-URL pool of shared NATS WebSocket connections, providing reference-counted acquire/release lifecycle and a coordinated reconnection loop with exponential backoff.
+
+## Key Components
+
+### Constants
+
+- **`NATS_DEFAULTS`** — Tuning knobs for timeouts, ping intervals, and retry backoff used as defaults throughout the module.
+
+### Interfaces
+
+- **`SharedConnection`** — Internal state for a single URL slot: client handle, reference count, active timers, connect promise, and retry ownership token.
+- **`NatsReconnectionBackoff`** — Optional backoff configuration (fast retries, exponential phase, jitter cap).
+- **`AcquireClientOptions`** — Client identity/auth and transport settings passed at acquire time.
+- **`ReleaseClientOptions`** — Allows callers to override the default 3-second close grace period.
+- **`ConnectionLifecycleOptions`** / **`ConnectionLifecycleHandle`** — Input and output for `startConnectionLifecycle`.
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `acquireClient(url, opts?)` | Returns (or creates) the `SharedConnection` for a URL, increments `refCount`, cancels any pending close timer. |
+| `releaseClient(url, opts?)` | Decrements `refCount`; schedules connection teardown after a grace period if count reaches zero. |
+| `getSharedConnectionFor(url)` | Direct per-URL lookup; preferred over the legacy accessor. |
+| `getSharedConnection()` | Legacy single-slot accessor — returns the first live connection. Avoid in new code. |
+| `startConnectionLifecycle(options)` | Attaches a status observer and manages reconnect scheduling via a single `retryOwner` token. Returns a `stop()` handle. |
+
+## Usage Example
+
+```typescript
+import {
+  acquireClient,
+  releaseClient,
+  startConnectionLifecycle,
+} from './shared-connection'
+
+const conn = acquireClient('wss://nats.example.com', {
+  name: 'my-service',
+  user: 'machine',
+  pass: 'secret',
+})
+
+const lifecycle = startConnectionLifecycle({
+  conn,
+  wsUrl: 'wss://nats.example.com',
+  getFreshUrl: () => 'wss://nats.example.com',
+  backoff: { fastRetries: 2, fastRetryDelayMs: 500, maxDelayMs: 15_000 },
+  onStatusChange: (status) => console.log('NATS status:', status),
+})
+
+// On component unmount:
+lifecycle.stop()
+releaseClient('wss://nats.example.com', { delayMs: 5000 })
+```
+
+> **Retry ownership:** only one lifecycle instance drives `scheduleRetry` per URL at a time. The `retryOwner` token prevents concurrent reconnect races when multiple consumers share the same connection — remaining consumers re-claim ownership opportunistically on the next status event after the owner stops.