@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/net/Reconnect.d.ts

@@ -0,0 +1,49 @@
+import { RetryPolicy } from '../resilience';
+/**
+ * Provides the default reconnect policy for a long-lived connection: unbounded attempts, exponential growth
+ * from 1s, capped at 30s, with equal jitter.
+ *
+ * Differs from `DefaultRetryPolicy` in two ways that matter for a STREAM rather than a request. Attempts are
+ * unbounded because a stream's failure mode is a server restart or a laptop lid, and giving up after two
+ * tries leaves a dead page that no amount of waiting fixes — a request can surface an error to the caller,
+ * a background stream has nobody to tell. And the jitter is `Equal`, not `Full`: full jitter can pick a delay
+ * near zero, so a single client reconnecting to a flapping server hammers it immediately, whereas equal
+ * jitter guarantees a floor of half the computed delay while still spreading a whole fleet apart.
+ */
+export declare const DefaultReconnectPolicy: RetryPolicy;
+/** Configures a {@link createReconnectScheduler} instance. Every member is optional. */
+export interface ReconnectSchedulerOptions {
+    /** The retry policy driving the delays, or `false` to disable reconnection entirely. Default {@link DefaultReconnectPolicy}. */
+    readonly retry?: RetryPolicy | false;
+    /** The randomness feeding jitter — injectable so a test can pin an exact delay. Default `Math.random`. */
+    readonly random?: () => number;
+    /** Fires when an attempt is armed, before the wait — the seam for logging "reconnecting in 4s (attempt 3)". */
+    readonly onScheduled?: (attempt: number, delayMs: number) => void;
+}
+/** Schedules reconnection attempts with `foundation/resilience` backoff, at most one in flight. */
+export interface ReconnectScheduler {
+    /** The number of consecutive attempts armed since the last {@link ReconnectScheduler.reset}. */
+    readonly attempts: number;
+    /** The delay (ms) of the attempt currently waiting, or `undefined` when none is pending. */
+    readonly pendingDelayMs: number | undefined;
+    /**
+     * Arms the next attempt after a `resilience`-computed delay.
+     *
+     * @param run - Invoked once the delay elapses. Not invoked if {@link ReconnectScheduler.cancel} lands first.
+     * @returns `true` when an attempt is pending afterwards — including when one was ALREADY pending and this
+     * call was absorbed by the stacking guard; `false` when reconnection is disabled or the budget is spent.
+     */
+    schedule(run: () => void): boolean;
+    /** Zeroes the attempt counter after a successful connection, so the next drop starts from the base delay again. */
+    reset(): void;
+    /** Cancels a pending attempt and clears its timer. Idempotent, and safe when nothing is pending. */
+    cancel(): void;
+}
+/**
+ * Creates the reconnect scheduler shared by this slice's transports — one pending attempt at most, delays
+ * and budget delegated wholly to `foundation/resilience`.
+ *
+ * @param options - The retry policy, randomness source, and scheduling hook.
+ * @returns A scheduler; call `cancel()` when the owning transport closes, or its timer outlives it.
+ */
+export declare function createReconnectScheduler(options?: ReconnectSchedulerOptions): ReconnectScheduler;

package/dist/foundation/net/UseEventStream.d.ts

@@ -0,0 +1,25 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { ConnectionState } from './ConnectionState';
+import { EventStreamOptions, EventStreamPayloads } from './CreateEventStream';
+/** The live view a scope gets over its stream. */
+export interface EventStreamHandle {
+    /** The current connection state, updating on every transition. */
+    readonly readyState: Readonly<ShallowRef<ConnectionState>>;
+    /** Whether `EventSource` exists in this runtime; `false` under SSR and in a locked-down browser. */
+    readonly supported: Readonly<ShallowRef<boolean>>;
+    /** Closes the stream early. The scope-disposal cleanup calls it anyway. */
+    readonly close: () => void;
+}
+/**
+ * Opens a Server-Sent Events stream for the lifetime of the scope.
+ *
+ * The stream is closed when the scope is disposed and re-opened whenever `url` changes. Pass `null` to hold
+ * off connecting (waiting for auth, a route param, a feature flag) — a ref or getter is how that flips.
+ *
+ * @typeParam TEvents - Maps each server event name to its payload type.
+ * @param url - The stream endpoint, or `null` to stay disconnected.
+ * @param options - Handlers and configuration, read once when the stream opens; handler callbacks are re-read
+ *   per event, so a ref or getter keeps them live.
+ * @returns The connection state, support flag, and `close`.
+ */
+export declare function useEventStream<TEvents extends EventStreamPayloads = EventStreamPayloads>(url: MaybeRefOrGetter<string | null>, options?: MaybeRefOrGetter<EventStreamOptions<TEvents>>): EventStreamHandle;

package/dist/foundation/net/UsePolling.d.ts

@@ -0,0 +1,26 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { PollerState, PollFn, PollerOptions } from './CreatePoller';
+/** The live view a scope gets over its poll loop. */
+export interface PollingHandle {
+    /** The current poller state, updating on every transition. `paused` covers manual, hidden, and offline. */
+    readonly state: Readonly<ShallowRef<PollerState>>;
+    /** Suspends polling until `resume()`. */
+    readonly pause: () => void;
+    /** Clears the manual suspension; polling stays suspended if the tab is hidden or the browser offline. */
+    readonly resume: () => void;
+    /** Stops the loop and detaches its listeners. The scope-disposal cleanup calls it anyway. */
+    readonly stop: () => void;
+}
+/**
+ * Runs `fn` on an interval for the lifetime of the scope, suspended automatically while the tab is hidden or
+ * the browser is offline.
+ *
+ * The loop stops when the scope is disposed and is rebuilt whenever `intervalMs` changes. `fn` is read fresh
+ * on each tick, so a getter whose target changes needs no rebuild.
+ *
+ * @param fn - The work to repeat; a returned promise is awaited before the next tick is scheduled.
+ * @param options - Interval and suspension behaviour, read once when the loop is built; handler callbacks are
+ *   re-read per emission, so a ref or getter keeps them live.
+ * @returns The poller state and `pause` / `resume` / `stop`.
+ */
+export declare function usePolling(fn: MaybeRefOrGetter<PollFn>, options?: MaybeRefOrGetter<PollerOptions>): PollingHandle;

package/dist/foundation/net/UseSocket.d.ts

@@ -0,0 +1,32 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { ConnectionState } from './ConnectionState';
+import { SocketClientOptions } from './CreateSocketClient';
+/** The live view a scope gets over its socket. */
+export interface SocketHandle<TOut> {
+    /** The current connection state, updating on every transition. */
+    readonly readyState: Readonly<ShallowRef<ConnectionState>>;
+    /** Whether `WebSocket` exists in this runtime; `false` under SSR. */
+    readonly supported: Readonly<ShallowRef<boolean>>;
+    /**
+     * Sends a message, queueing it while the socket is still connecting.
+     *
+     * @returns `true` when the frame went out immediately, `false` when queued, dropped, or disposed.
+     */
+    readonly send: (message: TOut) => boolean;
+    /** Closes the socket early and suppresses reconnection. The scope-disposal cleanup calls it anyway. */
+    readonly close: () => void;
+}
+/**
+ * Opens a JSON WebSocket for the lifetime of the scope.
+ *
+ * The socket is closed when the scope is disposed and re-opened whenever `url` changes. Pass `null` to hold
+ * off connecting (waiting for auth, a route param, a feature flag) — a ref or getter is how that flips.
+ *
+ * @typeParam TIn - The decoded inbound message type.
+ * @typeParam TOut - The outbound message type.
+ * @param url - The socket endpoint, or `null` to stay disconnected.
+ * @param options - Handlers and configuration, read once when the socket opens; handler callbacks are re-read
+ *   per message, so a ref or getter keeps them live.
+ * @returns The connection state, support flag, and `send` / `close`.
+ */
+export declare function useSocket<TIn = unknown, TOut = unknown>(url: MaybeRefOrGetter<string | null>, options?: MaybeRefOrGetter<SocketClientOptions<TIn, TOut>>): SocketHandle<TOut>;

package/dist/foundation/net/index.d.ts

@@ -0,0 +1,9 @@
+export { ConnectionState, EventSourceReadyState, SocketReadyState } from './ConnectionState';
+export { DefaultReconnectPolicy, createReconnectScheduler, type ReconnectScheduler, type ReconnectSchedulerOptions, } from './Reconnect';
+export { createEventStream, ReconnectOwner, type EventStream, type EventStreamErrorContext, type EventStreamHandlers, type EventStreamOptions, type EventStreamPayloads, type EventStreamSource, type EventStreamSourceFactory, } from './CreateEventStream';
+export { useEventStream, type EventStreamHandle } from './UseEventStream';
+export { createSocketClient, type SocketClient, type SocketClientOptions, type SocketConnection, type SocketFactory, type SocketHeartbeatOptions, } from './CreateSocketClient';
+export { useSocket, type SocketHandle } from './UseSocket';
+export { PollerState, createPoller, type PollFn, type Poller, type PollerOptions } from './CreatePoller';
+export { usePolling, type PollingHandle } from './UsePolling';
+export { readOnlineStatus, subscribeOnline, waitForOnline, type WaitForOnlineOptions } from './Liveness';