@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/media/index.js

@@ -0,0 +1,218 @@
+import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
+import { q as queryPermission } from "../../chunks/QueryPermission--OKfvS9c.js";
+import { shallowRef, onScopeDispose, toValue } from "vue";
+function mediaDevicesWith(member) {
+  try {
+    if (typeof navigator === "undefined") return void 0;
+    const devices = navigator.mediaDevices;
+    if (typeof devices !== "object" || devices === null) return void 0;
+    const api = devices;
+    if (typeof api[member] !== "function") return void 0;
+    return api;
+  } catch {
+    return void 0;
+  }
+}
+function isKnownInsecureContext() {
+  try {
+    const secure = globalThis.isSecureContext;
+    return secure === false;
+  } catch {
+    return false;
+  }
+}
+function getMediaSupport() {
+  if (mediaDevicesWith("getUserMedia") !== void 0) return "supported";
+  return isKnownInsecureContext() ? "insecure-context" : "unsupported";
+}
+function canCaptureMedia() {
+  return getMediaSupport() === "supported";
+}
+function nameOf(value) {
+  if (value === null || typeof value !== "object" && typeof value !== "function") return void 0;
+  try {
+    const name = value["name"];
+    return typeof name === "string" ? name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function toMediaStreamFailure(cause) {
+  switch (nameOf(cause)) {
+    case "NotAllowedError":
+    case "PermissionDeniedError":
+      return { status: "denied" };
+    case "NotFoundError":
+    case "DevicesNotFoundError":
+      return { status: "unavailable" };
+    case "NotReadableError":
+    case "TrackStartError":
+      return { status: "in-use" };
+    default:
+      return { status: "failed", error: toError(cause) };
+  }
+}
+async function requestMediaStream(constraints) {
+  const devices = mediaDevicesWith("getUserMedia");
+  if (devices === void 0) return { status: "unsupported" };
+  try {
+    const stream = await devices.getUserMedia(constraints);
+    if (typeof stream !== "object" || stream === null) {
+      return { status: "failed", error: new Error("getUserMedia resolved without a MediaStream") };
+    }
+    return { status: "granted", stream };
+  } catch (cause) {
+    return toMediaStreamFailure(cause);
+  }
+}
+function requestCameraStream(constraints) {
+  return requestMediaStream({ video: constraints ?? true });
+}
+function requestMicrophoneStream(constraints) {
+  return requestMediaStream({ audio: constraints ?? true });
+}
+function emptyGroups(supported) {
+  return { supported, cameras: [], microphones: [], speakers: [] };
+}
+function kindOf(entry) {
+  if (entry === null || typeof entry !== "object") return void 0;
+  try {
+    const kind = entry["kind"];
+    return typeof kind === "string" ? kind : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function listMediaDevices() {
+  const devices = mediaDevicesWith("enumerateDevices");
+  if (devices === void 0) return emptyGroups(false);
+  try {
+    const entries = await devices.enumerateDevices();
+    if (!Array.isArray(entries)) return emptyGroups(true);
+    const cameras = [];
+    const microphones = [];
+    const speakers = [];
+    for (const entry of entries) {
+      switch (kindOf(entry)) {
+        case "videoinput":
+          cameras.push(entry);
+          break;
+        case "audioinput":
+          microphones.push(entry);
+          break;
+        case "audiooutput":
+          speakers.push(entry);
+          break;
+        default:
+          break;
+      }
+    }
+    return { supported: true, cameras, microphones, speakers };
+  } catch {
+    return emptyGroups(true);
+  }
+}
+async function hasCamera() {
+  return (await listMediaDevices()).cameras.length > 0;
+}
+async function hasMicrophone() {
+  return (await listMediaDevices()).microphones.length > 0;
+}
+function stopMediaStream(stream) {
+  if (stream === null || stream === void 0) return;
+  let tracks = [];
+  try {
+    const result = stream.getTracks();
+    if (!Array.isArray(result)) return;
+    tracks = result;
+  } catch {
+    return;
+  }
+  for (const track of tracks) {
+    try {
+      track.stop();
+    } catch {
+    }
+  }
+}
+function facingModeConstraints(facingMode, options) {
+  return {
+    ...options?.video,
+    // Applied after the spread on purpose: this function's whole subject is `facingMode`, so a stale one carried
+    // in via `options.video` must not win over the argument the caller just passed.
+    facingMode: options?.exact === true ? { exact: facingMode } : { ideal: facingMode }
+  };
+}
+function switchCamera(current, facingMode, options) {
+  stopMediaStream(current);
+  return requestCameraStream(facingModeConstraints(facingMode, options));
+}
+function getCameraPermission() {
+  return queryPermission("camera");
+}
+function getMicrophonePermission() {
+  return queryPermission("microphone");
+}
+const DefaultConstraints = { video: true };
+function useMediaStream(options) {
+  const status = shallowRef("idle");
+  const stream = shallowRef(null);
+  const error = shallowRef(null);
+  let held = null;
+  let disposed = false;
+  function release() {
+    stopMediaStream(held);
+    held = null;
+  }
+  const stop = () => {
+    release();
+    if (disposed) return;
+    stream.value = null;
+    status.value = "idle";
+    error.value = null;
+  };
+  const start = async (constraints) => {
+    release();
+    if (!disposed) {
+      stream.value = null;
+      error.value = null;
+      status.value = "pending";
+    }
+    const result = await requestMediaStream(
+      constraints ?? toValue(options)?.constraints ?? DefaultConstraints
+    );
+    if (disposed) {
+      if (result.status === "granted") stopMediaStream(result.stream);
+      return result;
+    }
+    if (result.status === "granted") {
+      held = result.stream;
+      stream.value = result.stream;
+    }
+    status.value = result.status;
+    error.value = result.status === "failed" ? result.error : null;
+    return result;
+  };
+  onScopeDispose(() => {
+    disposed = true;
+    release();
+  });
+  return { status, stream, error, start, stop };
+}
+export {
+  canCaptureMedia,
+  facingModeConstraints,
+  getCameraPermission,
+  getMediaSupport,
+  getMicrophonePermission,
+  hasCamera,
+  hasMicrophone,
+  listMediaDevices,
+  requestCameraStream,
+  requestMediaStream,
+  requestMicrophoneStream,
+  stopMediaStream,
+  switchCamera,
+  useMediaStream
+};
+//# sourceMappingURL=index.js.map

package/dist/foundation/media/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/media/CanCaptureMedia.ts","../../../src/foundation/media/MediaStreamResult.ts","../../../src/foundation/media/RequestMediaStream.ts","../../../src/foundation/media/ListMediaDevices.ts","../../../src/foundation/media/StopMediaStream.ts","../../../src/foundation/media/FacingMode.ts","../../../src/foundation/media/MediaPermission.ts","../../../src/foundation/media/UseMediaStream.ts"],"sourcesContent":["// Feature detection for the media-capture vector, and the one distinction that earns this module its own file:\n// `getUserMedia` is gated on a SECURE CONTEXT, and browsers enforce that by hiding `navigator.mediaDevices`\n// ENTIRELY rather than by rejecting the call. On a plain-HTTP page the API therefore looks *unimplemented* — the\n// developer reads \"this browser has no camera support\" off a browser that supports it perfectly, and goes hunting\n// for a polyfill instead of an `https://`. (`localhost` counts as secure, so it works in dev and breaks on the\n// first LAN-IP test.) That misreading costs real debugging time, so the insecure case gets its own reason\n// instead of collapsing into `unsupported`.\n//\n// Order of evidence: a present `getUserMedia` outranks the `isSecureContext` flag. Where the API is there, the\n// call itself answers accurately, and pre-emptively reporting `insecure-context` would block a working path.\n// `isSecureContext` is consulted only to *explain* an absent API.\n//\n// Every read is guarded. `navigator` is absent under SSR, `mediaDevices` is absent on insecure pages and older\n// browsers, and `isSecureContext` is absent outside a browser — Node reports `undefined`, which must NOT read as\n// insecure: \"unknown\" is not \"no\". A detector that throws defeats its own purpose, so the answer is total.\n\n/**\n * Why media capture is (un)available here.\n *\n * - `supported` — `navigator.mediaDevices.getUserMedia` is present and callable.\n * - `insecure-context` — the API is absent *and* the page is known to be a non-secure context. Actionable:\n *   serve over HTTPS (or `localhost`). Distinguished from `unsupported` because the fix is completely different.\n * - `unsupported` — no API and no evidence the context is the reason: SSR, a worker, an older browser.\n */\nexport type MediaSupport = 'supported' | 'insecure-context' | 'unsupported';\n\n/**\n * Reads `navigator.mediaDevices` when it exists and carries `member` as a callable.\n *\n * Two members are asked for separately because they fail separately: a browser can expose `enumerateDevices`\n * (device *existence*, no permission needed) while `getUserMedia` is missing or blocked. Guarded end-to-end;\n * returns `undefined` under SSR. Internal to the slice — used by the sibling modules, absent from the barrel.\n *\n * @param member The method the caller is about to invoke.\n * @returns The `MediaDevices` object, or `undefined` when it or `member` is unusable.\n */\nexport function mediaDevicesWith(member: 'getUserMedia' | 'enumerateDevices'): MediaDevices | undefined {\n  try {\n    if (typeof navigator === 'undefined') return undefined;\n\n    const devices: unknown = navigator.mediaDevices;\n    if (typeof devices !== 'object' || devices === null) return undefined;\n\n    const api = devices as MediaDevices;\n    if (typeof api[member] !== 'function') return undefined;\n    return api;\n  } catch {\n    // A throwing `navigator` / `mediaDevices` getter (a partial polyfill) reads as absent — same posture as\n    // `foundation/errors`' guarded reads and `foundation/share`'s `hasNativeShare`.\n    return undefined;\n  }\n}\n\n/**\n * Whether the page is *known* to be a non-secure context.\n *\n * Only an explicit `false` counts. `undefined` — Node, a stripped global, an engine predating the flag — means\n * the question could not be answered, and answering \"insecure\" there would blame HTTP for an absent API in an\n * environment that has no HTTP at all.\n */\nfunction isKnownInsecureContext(): boolean {\n  try {\n    // Read through an `unknown` cast rather than the DOM lib's `declare var isSecureContext: boolean`: outside a\n    // browser the global is genuinely missing, so the typed view is a lie this module must not act on.\n    const secure: unknown = (globalThis as { isSecureContext?: unknown }).isSecureContext;\n    return secure === false;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Reports whether media capture is available here, and when it is not, why.\n *\n * The `insecure-context` answer is the one worth rendering differently: it is the only reason a consumer can\n * actually act on (\"this page must be served over HTTPS\"), where `unsupported` is terminal for that visit.\n *\n * Never throws. Returns `unsupported` under SSR.\n */\nexport function getMediaSupport(): MediaSupport {\n  if (mediaDevicesWith('getUserMedia') !== undefined) return 'supported';\n  return isKnownInsecureContext() ? 'insecure-context' : 'unsupported';\n}\n\n/**\n * Reports whether `requestMediaStream` and friends can reach a real `getUserMedia`.\n *\n * The boolean form of {@link getMediaSupport} — for a plain \"hide the camera button\" check that does not care\n * *why*. Never throws. Returns `false` under SSR.\n */\nexport function canCaptureMedia(): boolean {\n  return getMediaSupport() === 'supported';\n}\n","// The result vocabulary of the capture vector, and the `DOMException`-name table that produces it. This mapping\n// is the substance of the whole slice: `getUserMedia` rejects with a handful of names that mean completely\n// different things to a user, and a consumer that only sees \"the promise rejected\" renders one useless message\n// for all of them — \"camera unavailable\" to someone who simply pressed Block, whose fix is a browser setting.\n//\n// Matched on `name`, deliberately not `instanceof DOMException` — the same posture as `foundation/errors`'\n// `isAbortError`. The check has to hold for a `DOMException` from another realm (iframe · worker), for engines\n// where these arrive as plain `Error`s, and for the `{ name: 'NotAllowedError' }` a test double throws.\n//\n// Legacy names are first-class, not politeness: `PermissionDeniedError` (older Chrome), `DevicesNotFoundError`\n// (older Firefox), and `TrackStartError` (older Chrome) are what those engines actually throw, and a table that\n// omits them silently downgrades a denial to a generic failure on exactly the browsers most likely to hit it.\n//\n// Names deliberately left OUT of the table, all landing on `failed`:\n//  - `OverconstrainedError` — a constraint the device cannot satisfy. Tempting to call `unavailable`, but the\n//    device usually exists and the caller's constraints are the bug (`facingMode: { exact }` on a desktop is the\n//    classic). Burying it as \"no camera\" hides a fixable mistake in the consumer's own code.\n//  - `AbortError` — the device was taken away mid-acquisition by the OS. Rare and genuinely exceptional.\n//  - `SecurityError` / `TypeError` — capture disabled by policy, or malformed constraints. Both are programmer\n//    or deployment errors, and both deserve the real `Error` rather than a soothing status.\n\nimport { toError } from '../errors';\n\n/**\n * The outcome of a capture attempt. Six arms because a camera prompt has six meaningfully different endings,\n * each wanting different UI copy and a different next step.\n *\n * - `granted` — the user allowed it; `stream` is live and the caller now OWNS it (see `stopMediaStream`).\n * - `denied` — the user pressed Block, or a prior block is being replayed without a prompt. Not retryable\n *   without a browser-settings change, so re-prompting on a timer only annoys.\n * - `unavailable` — no device matches the request. A laptop with no webcam, or an unplugged USB mic.\n * - `in-use` — the device exists but another application (or another tab) holds it. Retryable once freed.\n * - `unsupported` — no API here at all: SSR, an insecure context, an older browser. See `getMediaSupport` for\n *   which of those it is.\n * - `failed` — anything else, carrying the normalized `Error`.\n */\nexport type MediaStreamResult =\n  | { readonly status: 'granted'; readonly stream: MediaStream }\n  | { readonly status: 'denied' }\n  | { readonly status: 'unavailable' }\n  | { readonly status: 'in-use' }\n  | { readonly status: 'unsupported' }\n  | { readonly status: 'failed'; readonly error: Error };\n\n/** The `status` discriminant of a {@link MediaStreamResult} — for a consumer's own switch or status→copy map. */\nexport type MediaStreamStatus = MediaStreamResult['status'];\n\n/** Every {@link MediaStreamResult} arm except the successful one — what a rejected `getUserMedia` can become. */\nexport type MediaStreamFailure = Exclude<MediaStreamResult, { status: 'granted' }>;\n\n/**\n * Reads a caught value's `name` as a string. Guarded: a throwing getter or a `Proxy` trap reads as absent rather\n * than escalating into a second failure inside the `catch` that is already handling the first.\n */\nfunction nameOf(value: unknown): string | undefined {\n  if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return undefined;\n\n  try {\n    const name: unknown = (value as Record<string, unknown>)['name'];\n    return typeof name === 'string' ? name : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Classifies a rejected `getUserMedia` into its {@link MediaStreamFailure}.\n *\n * Exported for the sibling request modules and their tests; absent from the barrel, where the request functions\n * are the surface a consumer wants. Never throws — an unrecognized name falls through to `failed` with the value\n * normalized by `foundation/errors`' `toError`, so even a thrown `null` arrives as a real `Error`.\n *\n * @param cause The value `getUserMedia` rejected (or threw) with.\n * @returns The matching failure arm.\n */\nexport function toMediaStreamFailure(cause: unknown): MediaStreamFailure {\n  switch (nameOf(cause)) {\n    case 'NotAllowedError':\n    case 'PermissionDeniedError':\n      return { status: 'denied' };\n\n    case 'NotFoundError':\n    case 'DevicesNotFoundError':\n      return { status: 'unavailable' };\n\n    case 'NotReadableError':\n    case 'TrackStartError':\n      return { status: 'in-use' };\n\n    default:\n      return { status: 'failed', error: toError(cause) };\n  }\n}\n","// The acquisition half of the capture vector: one call, six outcomes, no throw.\n//\n// DEFINING CONTRACT: NOTHING HERE THROWS. These are called straight from a click handler, where a rejection is\n// an unhandled error in the consumer's app and the user — who just pressed Block, or has no webcam — sees\n// nothing happen at all. Every path resolves to a `MediaStreamResult` the caller switches on.\n//\n// The call sits INSIDE the `try`, not merely the `await`: `getUserMedia` throws synchronously for a constraints\n// object with neither `audio` nor `video` (a `TypeError`, before any promise exists), so a `try` wrapped only\n// around the await would let that one escape the contract.\n//\n// OWNERSHIP: a `granted` result hands the caller a live stream and, with it, the duty to release it. Nothing in\n// this module keeps a reference or stops anything for you — see `stopMediaStream`, or let `useMediaStream` own\n// the lifecycle. A stream that is merely dropped keeps the camera light on until the tab closes.\n\nimport { mediaDevicesWith } from './CanCaptureMedia';\nimport { toMediaStreamFailure, type MediaStreamResult } from './MediaStreamResult';\n\n/**\n * Requests a stream for arbitrary constraints — the general form the camera / microphone helpers delegate to.\n *\n * Call it from a user gesture where possible: some engines require transient activation, and browsers rate-limit\n * repeated prompts. A `granted` result transfers stream ownership to the caller.\n *\n * Never throws, never rejects.\n *\n * @param constraints The `MediaStreamConstraints` to pass through, e.g. `{ video: true, audio: true }`.\n * @returns The typed outcome — `granted` carrying the live stream, or one of the five failure arms.\n */\nexport async function requestMediaStream(constraints: MediaStreamConstraints): Promise<MediaStreamResult> {\n  const devices = mediaDevicesWith('getUserMedia');\n  if (devices === undefined) return { status: 'unsupported' };\n\n  try {\n    const stream: unknown = await devices.getUserMedia(constraints);\n\n    // The DOM types promise a `MediaStream`; a polyfill or a test double can resolve with anything. Letting a\n    // non-object through as `granted` would move the failure into the consumer's `stream.getTracks()`, far from\n    // its cause — so an off-spec resolve is a `failed` result here, where the context still exists.\n    if (typeof stream !== 'object' || stream === null) {\n      return { status: 'failed', error: new Error('getUserMedia resolved without a MediaStream') };\n    }\n\n    return { status: 'granted', stream: stream as MediaStream };\n  } catch (cause) {\n    return toMediaStreamFailure(cause);\n  }\n}\n\n/**\n * Requests a camera-only stream.\n *\n * Video only, deliberately: a \"camera\" request that also opened the microphone would widen the permission\n * prompt (browsers name every device being asked for) and capture audio the caller never asked for. Pass\n * `{ video: …, audio: true }` to {@link requestMediaStream} when both are genuinely wanted.\n *\n * Never throws, never rejects.\n *\n * @param constraints Track constraints for the video device — resolution, `deviceId`, `facingMode`. Omitted\n *   means `video: true`: whichever camera the browser prefers.\n * @returns The typed outcome.\n */\nexport function requestCameraStream(constraints?: MediaTrackConstraints): Promise<MediaStreamResult> {\n  return requestMediaStream({ video: constraints ?? true });\n}\n\n/**\n * Requests a microphone-only stream.\n *\n * Never throws, never rejects.\n *\n * @param constraints Track constraints for the audio device — `deviceId`, `echoCancellation`, `noiseSuppression`.\n *   Omitted means `audio: true`.\n * @returns The typed outcome.\n */\nexport function requestMicrophoneStream(constraints?: MediaTrackConstraints): Promise<MediaStreamResult> {\n  return requestMediaStream({ audio: constraints ?? true });\n}\n","// Device inventory — `enumerateDevices` regrouped into the three buckets a UI actually renders (a camera picker,\n// a microphone picker, an output picker), instead of one flat array every consumer re-filters by a `kind` string.\n//\n// THE LABEL GOTCHA, and the reason this module documents more than it computes: before capture permission is\n// granted, browsers return the devices with `label: ''` and (in most engines) an empty `deviceId`. The privacy\n// reason is sound — \"Logitech BRIO\" plus \"Yeti Nano\" is a fingerprint — but the consequence catches everyone:\n// a device picker built on a cold `enumerateDevices()` renders a list of blank rows. The sequence that works is\n// request a stream first, THEN enumerate, and the labels are populated. Counts are honest either way, which is\n// what makes `hasCamera` / `hasMicrophone` usable *before* prompting.\n//\n// Reported as a total shape rather than a discriminated result: every arm of this call is \"here are the devices\n// I could see\", and zero cameras behaves identically whether the API was missing or the machine has none. The\n// `supported` flag preserves the distinction for the one caller that needs it — a picker that wants to say \"this\n// browser cannot list devices\" rather than \"no cameras found\".\n//\n// Never throws. `enumerateDevices` can reject (a permissions policy blocking the feature) and can, on a partial\n// implementation, resolve with something other than an array; both land on empty groups.\n\nimport { mediaDevicesWith } from './CanCaptureMedia';\n\n/**\n * Media input / output devices, grouped by kind.\n *\n * Labels are empty strings until capture permission has been granted at least once in this origin — see the\n * module header. Group membership and counts are accurate regardless.\n */\nexport interface MediaDeviceGroups {\n  /** Whether `enumerateDevices` was reachable at all. `false` means every group is empty because the API is absent (SSR, older browser), not because the machine has no devices. */\n  readonly supported: boolean;\n\n  /** Video inputs — `kind === 'videoinput'`. Webcams, virtual cameras, capture cards. */\n  readonly cameras: readonly MediaDeviceInfo[];\n\n  /** Audio inputs — `kind === 'audioinput'`. Microphones, line-ins, virtual audio devices. */\n  readonly microphones: readonly MediaDeviceInfo[];\n\n  /** Audio outputs — `kind === 'audiooutput'`. Speakers and headsets. Absent entirely on Firefox, which does not enumerate outputs. */\n  readonly speakers: readonly MediaDeviceInfo[];\n}\n\n/** Builds the empty answer for a given support verdict — the shape both the absent-API and failed-call paths return. */\nfunction emptyGroups(supported: boolean): MediaDeviceGroups {\n  return { supported, cameras: [], microphones: [], speakers: [] };\n}\n\n/** Reads an enumerated entry's `kind`. Guarded, so one hostile entry cannot abort the whole grouping pass. */\nfunction kindOf(entry: unknown): string | undefined {\n  if (entry === null || typeof entry !== 'object') return undefined;\n\n  try {\n    const kind: unknown = (entry as Record<string, unknown>)['kind'];\n    return typeof kind === 'string' ? kind : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Lists the available media devices, grouped by kind.\n *\n * Call it AFTER a successful `requestCameraStream` / `requestMicrophoneStream` if the labels matter — a picker\n * built on a pre-permission call renders blank rows (module header). Entries with an unrecognized `kind` are\n * dropped rather than guessed at.\n *\n * Never throws, never rejects.\n *\n * @returns The grouped devices, with `supported: false` when the API is absent.\n */\nexport async function listMediaDevices(): Promise<MediaDeviceGroups> {\n  const devices = mediaDevicesWith('enumerateDevices');\n  if (devices === undefined) return emptyGroups(false);\n\n  try {\n    const entries: unknown = await devices.enumerateDevices();\n    if (!Array.isArray(entries)) return emptyGroups(true);\n\n    const cameras: MediaDeviceInfo[] = [];\n    const microphones: MediaDeviceInfo[] = [];\n    const speakers: MediaDeviceInfo[] = [];\n\n    for (const entry of entries as readonly unknown[]) {\n      switch (kindOf(entry)) {\n        case 'videoinput':\n          cameras.push(entry as MediaDeviceInfo);\n          break;\n        case 'audioinput':\n          microphones.push(entry as MediaDeviceInfo);\n          break;\n        case 'audiooutput':\n          speakers.push(entry as MediaDeviceInfo);\n          break;\n        default:\n          // An unknown or unreadable `kind`. Dropped: a device in the wrong picker is worse than a missing one.\n          break;\n      }\n    }\n\n    return { supported: true, cameras, microphones, speakers };\n  } catch {\n    // The API was there but refused to answer — a permissions policy, or a partial implementation. `supported`\n    // stays true because the absence here is of an *answer*, not of the API.\n    return emptyGroups(true);\n  }\n}\n\n/**\n * Reports whether this machine has at least one camera.\n *\n * Usable BEFORE prompting: counts are accurate without permission even though labels are not, which makes this\n * the right gate for showing or hiding a \"Take a photo\" affordance. Never throws; `false` under SSR.\n */\nexport async function hasCamera(): Promise<boolean> {\n  return (await listMediaDevices()).cameras.length > 0;\n}\n\n/**\n * Reports whether this machine has at least one microphone.\n *\n * Same pre-permission caveat as {@link hasCamera}. Never throws; `false` under SSR.\n */\nexport async function hasMicrophone(): Promise<boolean> {\n  return (await listMediaDevices()).microphones.length > 0;\n}\n","// Release. The single most-forgotten call in camera code, and the reason this module exists at its own file:\n// dropping the last reference to a `MediaStream` does NOT stop it. The tracks stay live, the camera indicator\n// light stays on, the microphone keeps listening, and the device stays locked against every other application —\n// until the tab is closed. Garbage collection is irrelevant; only `track.stop()` releases the hardware.\n//\n// Per-track, not per-stream: `MediaStream` has no `stop()`. A stream is a bag of tracks and each one holds its\n// own device handle, so a camera+mic stream needs two stops. Stopping only the first is a partial release that\n// looks correct (the light goes off) while the microphone is still recording.\n//\n// Each `stop()` gets its own `try`. One uncooperative track — an already-ended track from an engine that throws,\n// a test double, a track from a detached document — must not strand the tracks after it in the loop. Skipping\n// the rest is exactly the leak this function exists to prevent, so the loop always completes.\n\n/**\n * Stops every track on a stream, releasing the underlying camera / microphone.\n *\n * Idempotent and total: a `null` / `undefined` stream, an already-stopped stream, and an object that is not a\n * stream at all are all no-ops. Never throws — it is called from cleanup paths (`finally`, a scope disposal)\n * where a throw would mask the original failure or abort the rest of the teardown.\n *\n * @param stream The stream to release. Nullable so a caller can pass state without a guard of its own.\n */\nexport function stopMediaStream(stream: MediaStream | null | undefined): void {\n  if (stream === null || stream === undefined) return;\n\n  let tracks: readonly MediaStreamTrack[] = [];\n  try {\n    const result: unknown = stream.getTracks();\n    if (!Array.isArray(result)) return;\n    tracks = result as readonly MediaStreamTrack[];\n  } catch {\n    // No usable `getTracks` — not a stream, or one from a torn-down realm. Nothing to release.\n    return;\n  }\n\n  for (const track of tracks) {\n    try {\n      track.stop();\n    } catch {\n      // This track refused to stop. Swallowed on purpose: the remaining tracks still hold live devices, and\n      // they are the ones this loop must reach.\n    }\n  }\n}\n","// Front / back camera selection, and the two mistakes it invites.\n//\n// MISTAKE 1 — `exact`. `facingMode: { exact: 'environment' }` rejects with `OverconstrainedError` on every\n// device without a rear camera: all desktops, all laptops, most external webcams. Those devices do not report\n// `facingMode` at all, so `exact` is not \"prefer the back camera\", it is \"fail unless there is one\". `ideal` is\n// the default here for that reason — it picks the rear camera on a phone and degrades to the only camera on a\n// laptop. `exact` stays available for the case that genuinely needs it (a document scanner where the selfie cam\n// is useless), where failing loudly beats capturing the wrong thing.\n//\n// MISTAKE 2 — switching by acquiring first. The natural \"get the new stream, then stop the old one\" ordering\n// breaks on mobile: most phones cannot open both cameras at once, so the second `getUserMedia` fails with\n// `NotReadableError` while the first camera is still held — a flip button that works on a laptop and never on a\n// phone. `switchCamera` therefore stops FIRST. The trade-off is deliberate and visible: a failed acquisition\n// leaves the caller with no stream at all, which is the honest outcome (the old stream's device is already\n// released) and is reported as an ordinary failure arm.\n\nimport { requestCameraStream } from './RequestMediaStream';\nimport { stopMediaStream } from './StopMediaStream';\nimport type { MediaStreamResult } from './MediaStreamResult';\n\n/**\n * Which camera to prefer.\n *\n * - `user` — front / selfie camera, facing the user.\n * - `environment` — rear camera, facing away. What a scanner or a document capture wants.\n */\nexport type FacingMode = 'user' | 'environment';\n\n/** Tunes how a facing-mode preference is expressed as constraints. */\nexport interface FacingModeOptions {\n  /**\n   * Whether to demand the facing mode rather than prefer it. `true` emits `{ exact }`, which REJECTS with\n   * `OverconstrainedError` on any device lacking that camera — see the module header. Defaults to `false`\n   * (`{ ideal }`), which degrades to whatever camera exists.\n   */\n  readonly exact?: boolean;\n\n  /** Extra video track constraints to merge — resolution, frame rate, `deviceId`. A `facingMode` here is overwritten. */\n  readonly video?: MediaTrackConstraints;\n}\n\n/**\n * Builds video track constraints expressing a facing-mode preference.\n *\n * Feed the result to {@link requestCameraStream}. Pure — no device access, nothing to fail, so it needs no\n * result type and never throws.\n *\n * @param facingMode The camera to prefer.\n * @param options Whether to demand rather than prefer it, plus any extra track constraints to merge.\n * @returns The merged `MediaTrackConstraints`, with `facingMode` applied last.\n */\nexport function facingModeConstraints(facingMode: FacingMode, options?: FacingModeOptions): MediaTrackConstraints {\n  return {\n    ...options?.video,\n    // Applied after the spread on purpose: this function's whole subject is `facingMode`, so a stale one carried\n    // in via `options.video` must not win over the argument the caller just passed.\n    facingMode: options?.exact === true ? { exact: facingMode } : { ideal: facingMode },\n  };\n}\n\n/**\n * Flips to the other camera: releases `current`, then acquires a stream for `facingMode`.\n *\n * Stops first, always — two camera streams must never be held at once (module header). `current` may be `null`,\n * which makes this usable as the first acquisition too, so a flip button needs no special case for its initial\n * press.\n *\n * Never throws, never rejects.\n *\n * @param current The stream to release. Pass `null` when nothing is live yet.\n * @param facingMode The camera to switch to.\n * @param options Whether to demand rather than prefer it, plus any extra track constraints.\n * @returns The typed outcome of the new acquisition. Anything other than `granted` means nothing is live now.\n */\nexport function switchCamera(\n  current: MediaStream | null | undefined,\n  facingMode: FacingMode,\n  options?: FacingModeOptions,\n): Promise<MediaStreamResult> {\n  stopMediaStream(current);\n  return requestCameraStream(facingModeConstraints(facingMode, options));\n}\n","// Permission reads for the two capture devices — two one-line delegations to `foundation/notifications`'\n// `queryPermission`, and no second Permissions API wrapper.\n//\n// That slice owns the generic `navigator.permissions.query` seam (its name is about where it was first needed,\n// not what it covers): the guarded `navigator.permissions` read, the off-spec-state handling, and the\n// synchronous-throw case all already live there and are already tested. Re-implementing them here would produce\n// a second thing to keep correct and a second place to fix a browser quirk. These functions exist only to pin\n// the two permission names so a consumer cannot typo `'microfone'` into an `unsupported` it will never explain.\n//\n// WHY THIS IS NOT THE GRANT CHECK. `queryPermission('camera')` answers `prompt` in the ordinary case, and on\n// Firefox answers `unsupported` for both names — Firefox throws a `TypeError` for camera / microphone rather\n// than resolving. So it can tell you the user has already BLOCKED the camera (worth rendering: re-prompting is\n// futile, the fix is in site settings), and it can never tell you a request will succeed. The authoritative\n// answer is `requestCameraStream`'s own result. Treat this as a hint that improves copy, never as a gate.\n\nimport { queryPermission, type PermissionQueryState } from '../notifications';\n\n/**\n * The state of a queried permission — re-exported from `foundation/notifications` so a consumer of this slice\n * can name the return type without importing a second subpath.\n */\nexport type { PermissionQueryState };\n\n/**\n * Reads the camera permission's current state without prompting.\n *\n * A hint, not a gate — see the module header. `unsupported` is the normal Firefox answer and means \"cannot\n * tell\", never \"blocked\". Never throws, never rejects.\n *\n * @returns `granted` · `denied` · `prompt` · `unsupported`.\n */\nexport function getCameraPermission(): Promise<PermissionQueryState> {\n  return queryPermission('camera');\n}\n\n/**\n * Reads the microphone permission's current state without prompting.\n *\n * Same caveats as {@link getCameraPermission}. Never throws, never rejects.\n *\n * @returns `granted` · `denied` · `prompt` · `unsupported`.\n */\nexport function getMicrophonePermission(): Promise<PermissionQueryState> {\n  return queryPermission('microphone');\n}\n","// The Vue binding of the capture vector — a state machine over `requestMediaStream` whose real job is OWNING\n// the stream, because a component that forgets to release one leaves the camera light on after it is gone.\n//\n// Three release paths, all of which have to work or the leak is back:\n//  1. `stop()` — the explicit one.\n//  2. Scope disposal — `onScopeDispose`. The common case: the user navigates away with the preview open.\n//  3. Disposal WHILE A PROMPT IS OPEN — the one that is always missed. The user presses Allow after the\n//     component has gone; the promise resolves with a live stream nobody will ever render, and no disposal\n//     cleanup can reach it because it did not exist when the cleanup ran. `start` therefore re-checks\n//     liveness after the await and releases the arriving stream itself.\n//\n// The live stream is held in a plain closure variable as well as in the ref. The disposal hook must reach the\n// CURRENT stream, and reading the reactive value there would tie teardown to render timing for no benefit — the\n// closure variable is the single authority every release path funnels through.\n//\n// Acquisition is on demand — no `autoStart`, and nothing touches `navigator.mediaDevices` at setup. That keeps\n// the SSR pass inert by construction, and a permission prompt fired without a user gesture is both a worse\n// experience and rate-limited by browsers. A click calls `start`.\n//\n// Never throws: `start` inherits the module's contract and resolves to the result as well as reflecting it in\n// reactive state, so a caller can branch on the outcome immediately or watch the refs.\n\nimport { onScopeDispose, shallowRef, toValue, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport type { MediaStreamResult, MediaStreamStatus } from './MediaStreamResult';\nimport { requestMediaStream } from './RequestMediaStream';\nimport { stopMediaStream } from './StopMediaStream';\n\n/**\n * Where a `useMediaStream` instance sits in its cycle: `idle` before the first attempt and after `stop`,\n * `pending` while the browser prompt is open, then the {@link MediaStreamStatus} of the last attempt.\n */\nexport type MediaStreamState = 'idle' | 'pending' | MediaStreamStatus;\n\n/** Tunes a `useMediaStream` instance. */\nexport interface UseMediaStreamOptions {\n  /** Constraints for every `start()` that does not pass its own. Defaults to `{ video: true }` — camera, no microphone. */\n  readonly constraints?: MediaStreamConstraints;\n}\n\n/** What {@link useMediaStream} returns. */\nexport interface MediaStreamControls {\n  /** The current state — drives the button label, the spinner, and the permission-denied copy. */\n  readonly status: Readonly<ShallowRef<MediaStreamState>>;\n\n  /** The live stream, or `null` whenever `status` is anything but `granted`. Assign to a `<video>`'s `srcObject`. */\n  readonly stream: Readonly<ShallowRef<MediaStream | null>>;\n\n  /** The normalized error from a `failed` attempt; `null` for every other status, including `denied`, which is a decision rather than a failure. */\n  readonly error: Readonly<ShallowRef<Error | null>>;\n\n  /** Acquires a stream, releasing any currently held one first. Resolves to the outcome; never throws. */\n  readonly start: (constraints?: MediaStreamConstraints) => Promise<MediaStreamResult>;\n\n  /** Releases the held stream and returns to `idle`. Idempotent, safe before the first `start`. */\n  readonly stop: () => void;\n}\n\n/** The camera-only default — matching `requestCameraStream`, so an unconfigured composable does not silently open the microphone. */\nconst DefaultConstraints: MediaStreamConstraints = { video: true };\n\n/**\n * Acquires and owns a media stream, releasing it on `stop` and when the scope is disposed.\n *\n * ```vue\n * const camera = useMediaStream();\n * <video ref=\"videoEl\" autoplay playsinline muted />\n * <button @click=\"camera.start()\">Start</button>\n * // watchEffect(() => { if (videoEl.value) videoEl.value.srcObject = camera.stream.value; })\n * ```\n *\n * Inherits the slice's never-throws contract — a rejected promise is not one of the outcomes.\n *\n * @param options Default constraints for `start()`. A ref or getter is read at call time.\n * @returns The state machine plus the two lifecycle callbacks.\n */\nexport function useMediaStream(\n  options?: MaybeRefOrGetter<UseMediaStreamOptions | undefined>,\n): MediaStreamControls {\n  const status = shallowRef<MediaStreamState>('idle');\n  const stream = shallowRef<MediaStream | null>(null);\n  const error = shallowRef<Error | null>(null);\n\n  let held: MediaStream | null = null;\n  let disposed = false;\n\n  /** Releases the held stream and clears the handle. The one place tracks are stopped, so every path funnels here. */\n  function release(): void {\n    stopMediaStream(held);\n    held = null;\n  }\n\n  const stop = (): void => {\n    release();\n    if (disposed) return;\n    stream.value = null;\n    status.value = 'idle';\n    error.value = null;\n  };\n\n  const start = async (constraints?: MediaStreamConstraints): Promise<MediaStreamResult> => {\n    // Release before acquiring, never after: most phones cannot open two cameras at once, so an overlapping\n    // acquisition fails with `NotReadableError` — and on the devices where it succeeds it leaves the first\n    // camera live. Same ordering, same reason, as `switchCamera`.\n    release();\n    if (!disposed) {\n      stream.value = null;\n      error.value = null;\n      status.value = 'pending';\n    }\n\n    const result = await requestMediaStream(\n      constraints ?? toValue(options)?.constraints ?? DefaultConstraints,\n    );\n\n    if (disposed) {\n      // Torn down while the prompt was open. The stream arrived for a component that no longer exists; nothing\n      // else will ever reach it, so it is released here or the device stays held for the life of the tab.\n      if (result.status === 'granted') stopMediaStream(result.stream);\n      return result;\n    }\n\n    if (result.status === 'granted') {\n      held = result.stream;\n      stream.value = result.stream;\n    }\n    status.value = result.status;\n    error.value = result.status === 'failed' ? result.error : null;\n\n    return result;\n  };\n\n  onScopeDispose(() => {\n    disposed = true;\n    release();\n  });\n\n  return { status, stream, error, start, stop };\n}\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,36 @@
+/** Describes a long-lived connection's state, uniformly across SSE, WebSocket, and polling. */
+export declare const ConnectionState: {
+    /** Refers to a first connection attempt in flight — nothing has been established yet. */
+    readonly Connecting: "connecting";
+    /** Refers to an established connection that is passing traffic. */
+    readonly Open: "open";
+    /** Refers to a dropped connection with a retry pending or in flight — the distinction the wire ready-state cannot express. */
+    readonly Reconnecting: "reconnecting";
+    /** Refers to a connection that is down and not coming back — closed by the caller, unsupported, or out of retries. */
+    readonly Closed: "closed";
+};
+export type ConnectionState = (typeof ConnectionState)[keyof typeof ConnectionState];
+/**
+ * Provides the `EventSource.readyState` values from the WHATWG spec. Note `Closed` here is TERMINAL — the
+ * browser only reports it once it has abandoned its own reconnection, which is precisely the signal
+ * `createEventStream` waits for before taking the retry over.
+ */
+export declare const EventSourceReadyState: {
+    /** Refers to the connection being established — including the browser's OWN automatic reconnection. */
+    readonly Connecting: 0;
+    /** Refers to an open, streaming connection. */
+    readonly Open: 1;
+    /** Refers to a connection the browser will not retry: a fatal error, or an explicit `close()`. */
+    readonly Closed: 2;
+};
+/** Provides the `WebSocket.readyState` values from the WHATWG spec — note `Closing` occupies `2`, where `EventSource` puts `Closed`. */
+export declare const SocketReadyState: {
+    /** Refers to a handshake in progress; `send()` throws here, which is why this slice queues instead. */
+    readonly Connecting: 0;
+    /** Refers to an open socket ready for frames. */
+    readonly Open: 1;
+    /** Refers to a close handshake in progress; frames sent now are discarded. */
+    readonly Closing: 2;
+    /** Refers to a closed or failed socket. */
+    readonly Closed: 3;
+};

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

@@ -0,0 +1,101 @@
+import { RetryPolicy } from '../resilience';
+import { ConnectionState } from './ConnectionState';
+/**
+ * The minimal `EventSource` surface this wrapper drives. Narrow on purpose: a test double or a polyfill can
+ * satisfy it in a few lines, and the real `EventSource` satisfies it structurally.
+ */
+export interface EventStreamSource {
+    /** The wire ready-state — see {@link EventSourceReadyState}. The branch the double-reconnect guard turns on. */
+    readonly readyState: number;
+    /** Closes the connection and stops the browser's own reconnection. */
+    close(): void;
+    /** Registers a listener for `open`, `error`, `message`, or a server-named event. */
+    addEventListener(type: string, listener: (event: Event) => void): void;
+    /** Removes a previously registered listener. */
+    removeEventListener(type: string, listener: (event: Event) => void): void;
+}
+/** Builds the underlying source — injectable so tests and polyfills need no global. */
+export type EventStreamSourceFactory = (url: string, init: {
+    withCredentials: boolean;
+}) => EventStreamSource;
+/** Identifies who is retrying a broken stream — the guard against reconnecting on top of the browser. */
+export declare const ReconnectOwner: {
+    /** Refers to the browser's own `EventSource` retry already being in flight; this wrapper stands down. */
+    readonly Browser: "browser";
+    /** Refers to the browser having given up, with this wrapper's `resilience`-scheduled retry pending. */
+    readonly Wrapper: "wrapper";
+    /** Refers to nobody retrying — reconnection is disabled, the attempt budget is spent, or the stream was closed. */
+    readonly None: "none";
+};
+export type ReconnectOwner = (typeof ReconnectOwner)[keyof typeof ReconnectOwner];
+/** Describes a stream failure — above all, who (if anyone) is going to do something about it. */
+export interface EventStreamErrorContext {
+    /** Whoever is retrying this failure. See {@link ReconnectOwner}. */
+    readonly owner: ReconnectOwner;
+    /** The wrapper's consecutive attempt count; `0` while the browser owns the retry, since the wrapper has armed nothing. */
+    readonly attempt: number;
+    /** The connection state after this failure was handled. */
+    readonly state: ConnectionState;
+}
+/**
+ * Maps each server event name to the payload it carries — the generic every handler in
+ * {@link EventStreamOptions.events} is typed from.
+ */
+export type EventStreamPayloads = Record<string, unknown>;
+/** Maps event names to their handlers, each typed by that event's payload. */
+export type EventStreamHandlers<TEvents extends EventStreamPayloads> = {
+    readonly [K in keyof TEvents & string]?: (data: TEvents[K], event: MessageEvent<string>) => void;
+};
+/** Configures a {@link createEventStream} call. Every member is optional. */
+export interface EventStreamOptions<TEvents extends EventStreamPayloads = EventStreamPayloads> {
+    /** Handlers for server-NAMED events (`event: order-updated`). These never reach {@link EventStreamOptions.onMessage}. */
+    readonly events?: EventStreamHandlers<TEvents>;
+    /** Handles unnamed events only — the default `message` type. */
+    readonly onMessage?: (data: unknown, event: MessageEvent<string>) => void;
+    /** Fires each time the connection opens, including after every reconnect. */
+    readonly onOpen?: () => void;
+    /** Fires on every failure, with the context saying who is retrying it. */
+    readonly onError?: (error: Error, context: EventStreamErrorContext) => void;
+    /** Fires on every connection-state transition — the seam for a "reconnecting…" indicator. */
+    readonly onStateChange?: (state: ConnectionState) => void;
+    /** Whether to send credentials cross-origin. Default `false`. */
+    readonly withCredentials?: boolean;
+    /**
+     * Decodes a frame's `data` text. Default: `JSON.parse`, falling back to the RAW STRING when the text is not
+     * JSON — SSE carries text, and plain-text frames and sentinels like `[DONE]` are common enough that
+     * throwing on them would be hostile. Supply this to be strict, or to decode another format.
+     */
+    readonly parse?: (raw: string) => unknown;
+    /** The reconnect policy for failures the browser abandons, or `false` to never reconnect. Default `DefaultReconnectPolicy`. */
+    readonly retry?: RetryPolicy | false;
+    /** The randomness feeding backoff jitter — injectable for deterministic tests. Default `Math.random`. */
+    readonly random?: () => number;
+    /** The source factory. Default constructs a global `EventSource`; inject a double in tests. */
+    readonly eventSource?: EventStreamSourceFactory;
+}
+/** Controls a live Server-Sent Events subscription. */
+export interface EventStream {
+    /** The current connection state — `reconnecting` covers both the browser's retry and this wrapper's. */
+    readonly readyState: ConnectionState;
+    /** Whether an `EventSource` implementation was available at all; `false` under SSR, where the stream is inert. */
+    readonly supported: boolean;
+    /** The wrapper's consecutive reconnect attempts, zeroed on every successful open. */
+    readonly attempts: number;
+    /** Closes the stream, cancels any pending reconnect, and detaches every listener. Idempotent; suppresses all further reconnection. */
+    close(): void;
+}
+/**
+ * Opens a Server-Sent Events stream with typed named-event handlers and a reconnect that defers to the
+ * browser's own — see this file's header for how the double-reconnect is avoided.
+ *
+ * Never throws, at import time or at call time. Where `EventSource` does not exist (SSR, a locked-down
+ * runtime) the returned stream reports `supported: false` and state `closed`, and every method is a no-op —
+ * a defined answer rather than an exception a render cannot catch.
+ *
+ * @typeParam TEvents - Maps each server event name to its payload type.
+ * @param url - The stream endpoint.
+ * @param options - Handlers, retry policy, parsing, and injection seams.
+ * @returns The stream handle. ALWAYS call `close()` when done — an open `EventSource` survives navigation
+ * within an SPA and keeps both the connection and every captured handler alive.
+ */
+export declare function createEventStream<TEvents extends EventStreamPayloads = EventStreamPayloads>(url: string, options?: EventStreamOptions<TEvents>): EventStream;

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

@@ -0,0 +1,59 @@
+/** Describes what a poller is doing right now. */
+export declare const PollerState: {
+    /** Refers to a poller created but not started. */
+    readonly Idle: "idle";
+    /** Refers to a poller with a tick scheduled or running. */
+    readonly Running: "running";
+    /** Refers to a started poller held by at least one suspend reason — paused, hidden, or offline. */
+    readonly Paused: "paused";
+    /** Refers to a stopped poller: timers cleared, listeners detached, restartable with `start()`. */
+    readonly Stopped: "stopped";
+};
+export type PollerState = (typeof PollerState)[keyof typeof PollerState];
+/** The work a poller repeats. A returned promise is awaited, so the next tick is scheduled only after it settles. */
+export type PollFn = () => unknown;
+/** Configures a {@link createPoller} call. Every member is optional. */
+export interface PollerOptions {
+    /** The gap (ms) between the end of one poll and the start of the next. Default `30000`. */
+    readonly intervalMs?: number;
+    /** Whether to start polling immediately on creation. Default `true`; `false` waits for `start()`. */
+    readonly autoStart?: boolean;
+    /** Whether to run one poll at once on start, rather than after the first interval. Default `false`. */
+    readonly immediate?: boolean;
+    /** Whether to suspend while the tab is hidden. Default `true`. */
+    readonly pauseWhenHidden?: boolean;
+    /** Whether to suspend while the browser reports no network link. Default `true`. */
+    readonly pauseWhenOffline?: boolean;
+    /** Whether returning from a suspension polls at once instead of waiting a full interval. Default `true` — the data is already stale. */
+    readonly refreshOnResume?: boolean;
+    /** Receives an error thrown or rejected by the poll. The chain continues regardless — a failed poll is not a reason to stop polling. */
+    readonly onError?: (error: Error) => void;
+    /** Fires on every state transition — the seam for a "paused (offline)" indicator. */
+    readonly onStateChange?: (state: PollerState) => void;
+}
+/** Controls a running poll loop. */
+export interface Poller {
+    /** The current state. `paused` covers all three suspend reasons. */
+    readonly state: PollerState;
+    /** Starts (or restarts) polling. A no-op while already running. */
+    start(): void;
+    /** Suspends polling until `resume()`. Independent of the automatic hidden / offline suspensions. */
+    pause(): void;
+    /** Clears the caller's suspension. Polling stays suspended if the tab is still hidden or the browser still offline. */
+    resume(): void;
+    /** Stops polling, clears the pending timer, and detaches the visibility and connectivity listeners. Idempotent. */
+    stop(): void;
+}
+/**
+ * Creates a poller that repeats `fn` on an interval and suspends itself while the tab is hidden or the
+ * browser is offline — see this file's header for why both of those are non-negotiable.
+ *
+ * Never throws: an error from `fn` goes to `onError` and the loop continues, because a poll that failed once
+ * is the poll most worth retrying. Ticks never overlap.
+ *
+ * @param fn - The work to repeat; a returned promise is awaited before the next tick is scheduled.
+ * @param options - Interval, suspension behaviour, and hooks.
+ * @returns The poller handle. ALWAYS call `stop()` when done — a live poller holds a timer and two document /
+ * window listeners.
+ */
+export declare function createPoller(fn: PollFn, options?: PollerOptions): Poller;

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

@@ -0,0 +1,93 @@
+import { RetryPolicy } from '../resilience';
+import { ConnectionState } from './ConnectionState';
+/**
+ * The minimal `WebSocket` surface this client drives. Narrow on purpose: a test double satisfies it in a few
+ * lines, and the real `WebSocket` satisfies it structurally.
+ */
+export interface SocketConnection {
+    /** The wire ready-state — see {@link SocketReadyState}. Gates every send. */
+    readonly readyState: number;
+    /** Sends one text frame. Throws while `CONNECTING`, which is exactly what the queue exists to prevent. */
+    send(data: string): void;
+    /** Starts the close handshake. */
+    close(code?: number, reason?: string): void;
+    /** Registers a listener for `open`, `close`, `error`, or `message`. */
+    addEventListener(type: string, listener: (event: Event) => void): void;
+    /** Removes a previously registered listener. */
+    removeEventListener(type: string, listener: (event: Event) => void): void;
+}
+/** Builds the underlying socket — injectable so tests and polyfills need no global. */
+export type SocketFactory = (url: string, protocols?: string | readonly string[]) => SocketConnection;
+/** Configures the liveness heartbeat that detects a half-open socket. */
+export interface SocketHeartbeatOptions {
+    /** The interval (ms) between pings. */
+    readonly intervalMs: number;
+    /** The silence (ms) tolerated after a ping before the socket is declared dead and reconnected. Default: the interval. */
+    readonly timeoutMs?: number;
+    /** Builds the ping frame. Default `{"type":"ping"}`. Return the exact text your server expects. */
+    readonly ping?: () => string;
+}
+/** Configures a {@link createSocketClient} call. Every member is optional. */
+export interface SocketClientOptions<TIn = unknown, TOut = unknown> {
+    /** The subprotocols offered during the handshake. */
+    readonly protocols?: string | readonly string[];
+    /** Receives every decoded inbound message. Frames that fail to decode go to {@link SocketClientOptions.onError} instead. */
+    readonly onMessage?: (message: TIn, event: MessageEvent) => void;
+    /** Fires each time the socket opens, including after every reconnect and BEFORE the queue is flushed. */
+    readonly onOpen?: () => void;
+    /** Fires on every close, with `wasClean` distinguishing a handshake close from a drop. */
+    readonly onClose?: (event: CloseEvent) => void;
+    /** Fires on a socket error, a decode failure, or a send that the transport rejected. */
+    readonly onError?: (error: Error) => void;
+    /** Fires on every connection-state transition — the seam for a "reconnecting…" indicator. */
+    readonly onStateChange?: (state: ConnectionState) => void;
+    /** Encodes an outbound message. Default `JSON.stringify`. */
+    readonly serialize?: (message: TOut) => string;
+    /** Decodes an inbound frame. Default `JSON.parse`. A throw here is reported, and the frame is dropped. */
+    readonly deserialize?: (raw: string) => TIn;
+    /** The reconnect policy, or `false` to never reconnect. Default `DefaultReconnectPolicy`. */
+    readonly retry?: RetryPolicy | false;
+    /** The half-open detector. Omit to disable heartbeating entirely. */
+    readonly heartbeat?: SocketHeartbeatOptions;
+    /** The cap on frames buffered while not open; the oldest is dropped when full. Default `100`. */
+    readonly queueLimit?: number;
+    /** The randomness feeding backoff jitter — injectable for deterministic tests. Default `Math.random`. */
+    readonly random?: () => number;
+    /** The socket factory. Default constructs a global `WebSocket`; inject a double in tests. */
+    readonly socket?: SocketFactory;
+}
+/** Controls a live WebSocket connection. */
+export interface SocketClient<TOut = unknown> {
+    /** The current connection state. */
+    readonly readyState: ConnectionState;
+    /** Whether a `WebSocket` implementation was available at all; `false` under SSR, where the client is inert. */
+    readonly supported: boolean;
+    /** The number of frames buffered awaiting an open socket — non-zero means back-pressure or an outage. */
+    readonly queuedCount: number;
+    /** The consecutive reconnect attempts, zeroed on every successful open. */
+    readonly attempts: number;
+    /**
+     * Sends a message, queueing it when the socket is not open yet.
+     *
+     * @param message - The payload, encoded by `serialize`.
+     * @returns `true` when the frame went out immediately, `false` when it was queued or dropped.
+     */
+    send(message: TOut): boolean;
+    /** Closes the socket, cancels reconnection permanently, clears the heartbeat, and detaches every listener. Idempotent. */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Opens a JSON WebSocket with a send queue, `resilience`-scheduled reconnection, and a half-open detector —
+ * see this file's header for the three bugs each of those exists to prevent.
+ *
+ * Never throws, at import time or at call time. Where `WebSocket` does not exist (SSR) the returned client
+ * reports `supported: false` and state `closed`, `send` returns `false`, and `close` is a no-op.
+ *
+ * @typeParam TIn - The decoded inbound message type.
+ * @typeParam TOut - The outbound message type.
+ * @param url - The socket endpoint (`ws://` or `wss://`).
+ * @param options - Handlers, retry policy, heartbeat, codecs, and injection seams.
+ * @returns The client handle. ALWAYS call `close()` when done — an abandoned socket keeps its connection, its
+ * heartbeat timers, and every captured handler alive.
+ */
+export declare function createSocketClient<TIn = unknown, TOut = unknown>(url: string, options?: SocketClientOptions<TIn, TOut>): SocketClient<TOut>;

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

@@ -0,0 +1,41 @@
+/**
+ * Reads `navigator.onLine`, defaulting to online when there is no `navigator` (SSR), when the property is
+ * missing (a partial polyfill), or when the read throws.
+ *
+ * Mirrors `useOnlineStatus`'s reader exactly — see this file's header for why the duplication is deliberate.
+ *
+ * @returns `true` while the browser reports a network link; optimistically `true` when unreadable.
+ */
+export declare function readOnlineStatus(): boolean;
+/**
+ * Subscribes to connectivity changes via the window `online` / `offline` events.
+ *
+ * A no-op returning a no-op disposer when there is no `window` (SSR), so callers need no environment branch.
+ * The listener receives the new status, never a raw `Event`.
+ *
+ * @param listener - Invoked with `true` on `online` and `false` on `offline`.
+ * @returns A disposer that detaches both listeners; safe to call more than once.
+ */
+export declare function subscribeOnline(listener: (online: boolean) => void): () => void;
+/** Configures a {@link waitForOnline} call. Every member is optional. */
+export interface WaitForOnlineOptions {
+    /** The maximum wait (ms) before giving up and resolving `false`. Omit, or pass a non-positive value, to wait indefinitely. */
+    readonly timeoutMs?: number;
+    /** Abandons the wait early, resolving `false` — an abort is a "stop waiting" verdict here, never a rejection. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Waits for connectivity to come back, resolving `true` the moment it does.
+ *
+ * Resolves `true` immediately when already online, and `false` when the timeout lapses or the signal aborts —
+ * never rejects, and never leaves a timer or a listener behind on any of those paths. Under SSR, or wherever
+ * connectivity cannot be observed, it resolves `true` at once rather than hanging on an event that can never
+ * arrive.
+ *
+ * Remember what a `true` verdict is worth (see this file's header): it says a link exists, not that the
+ * server is reachable. Use it to gate a retry, then let the retry decide.
+ *
+ * @param options - The deadline and cancellation signal.
+ * @returns `true` when connectivity is (or becomes) available; `false` on timeout or abort.
+ */
+export declare function waitForOnline(options?: WaitForOnlineOptions): Promise<boolean>;