@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/screen/index.js

@@ -0,0 +1,402 @@
+import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
+import { shallowRef, onMounted, onScopeDispose, toValue, watch } from "vue";
+function readMember(source, key) {
+  try {
+    if (source === null || typeof source !== "object" && typeof source !== "function") return void 0;
+    return source[key];
+  } catch {
+    return void 0;
+  }
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function getDocument() {
+  try {
+    return typeof document === "undefined" ? void 0 : document;
+  } catch {
+    return void 0;
+  }
+}
+function getNavigator() {
+  try {
+    return typeof navigator === "undefined" ? void 0 : navigator;
+  } catch {
+    return void 0;
+  }
+}
+function getScreen() {
+  try {
+    return typeof screen === "undefined" ? void 0 : screen;
+  } catch {
+    return void 0;
+  }
+}
+const GestureRejectionPattern = /user (?:gesture|activation)|transient activation|user-activation/i;
+function classifyFullscreenRejection(cause) {
+  const error = toError(cause);
+  if (GestureRejectionPattern.test(error.message)) return { status: "requires-gesture", error };
+  if (error.name === "TypeError") return { status: "requires-gesture", error };
+  if (error.name === "NotAllowedError" || error.name === "SecurityError") return { status: "denied", error };
+  return { status: "failed", error };
+}
+function pickPrefixed(source, standard, prefixed) {
+  const method = readMember(source, standard) ?? readMember(source, prefixed);
+  return isFunction(method) ? method : void 0;
+}
+function getFullscreenElement() {
+  const doc = getDocument();
+  if (doc === void 0) return null;
+  const standard = readMember(doc, "fullscreenElement");
+  if (standard !== null && standard !== void 0) return standard;
+  const prefixed = readMember(doc, "webkitFullscreenElement");
+  if (prefixed !== null && prefixed !== void 0) return prefixed;
+  return null;
+}
+function isFullscreen() {
+  return getFullscreenElement() !== null;
+}
+function isFullscreenSupported() {
+  const doc = getDocument();
+  if (doc === void 0) return false;
+  const root = readMember(doc, "documentElement");
+  return isFunction(readMember(root, "requestFullscreen")) || isFunction(readMember(root, "webkitRequestFullscreen"));
+}
+async function enterFullscreen(element) {
+  const doc = getDocument();
+  if (doc === void 0) return { status: "unsupported" };
+  const target = element ?? readMember(doc, "documentElement");
+  if (target === null || target === void 0) return { status: "unsupported" };
+  const request = pickPrefixed(target, "requestFullscreen", "webkitRequestFullscreen");
+  if (request === void 0) return { status: "unsupported" };
+  try {
+    await request.call(target);
+    return { status: "ok" };
+  } catch (error) {
+    return classifyFullscreenRejection(error);
+  }
+}
+async function exitFullscreen() {
+  const doc = getDocument();
+  if (doc === void 0) return { status: "unsupported" };
+  const exit = pickPrefixed(doc, "exitFullscreen", "webkitExitFullscreen");
+  if (exit === void 0) return { status: "unsupported" };
+  if (getFullscreenElement() === null) return { status: "ok" };
+  try {
+    await exit.call(doc);
+    return { status: "ok" };
+  } catch (error) {
+    return classifyFullscreenRejection(error);
+  }
+}
+function toggleFullscreen(element) {
+  return isFullscreen() ? exitFullscreen() : enterFullscreen(element);
+}
+function onFullscreenChange(listener) {
+  const doc = getDocument();
+  if (doc === void 0 || !isFunction(readMember(doc, "addEventListener"))) {
+    return () => {
+    };
+  }
+  const handler = () => {
+    listener();
+  };
+  doc.addEventListener("fullscreenchange", handler);
+  doc.addEventListener("webkitfullscreenchange", handler);
+  return () => {
+    doc.removeEventListener("fullscreenchange", handler);
+    doc.removeEventListener("webkitfullscreenchange", handler);
+  };
+}
+function useFullscreen(target) {
+  const active = shallowRef(false);
+  const supported = shallowRef(false);
+  let unsubscribe;
+  onMounted(() => {
+    const sync = () => {
+      active.value = isFullscreen();
+      supported.value = isFullscreenSupported();
+    };
+    sync();
+    unsubscribe = onFullscreenChange(sync);
+  });
+  onScopeDispose(() => {
+    unsubscribe?.();
+    unsubscribe = void 0;
+  });
+  const enter = () => enterFullscreen(toValue(target) ?? void 0);
+  const exit = () => exitFullscreen();
+  const toggle = () => toggleFullscreen(toValue(target) ?? void 0);
+  return { isFullscreen: active, supported, enter, exit, toggle };
+}
+const WakeLockKind = {
+  /** Keeps the display on and undimmed. The only kind any browser implements today. */
+  Screen: "screen"
+};
+const IdleWakeLockState = { held: false, status: "idle", error: null };
+function classifyWakeLockRejection(cause) {
+  const error = toError(cause);
+  if (error.name === "NotAllowedError") return { status: "denied", error };
+  return { status: "failed", error };
+}
+function toWakeLockHandle(sentinel, type) {
+  return {
+    type,
+    get released() {
+      return readMember(sentinel, "released") === true;
+    },
+    release: async () => {
+      const release = readMember(sentinel, "release");
+      if (!isFunction(release) || release === void 0) return;
+      try {
+        await release.call(sentinel);
+      } catch {
+      }
+    }
+  };
+}
+async function requestWakeLock(type = WakeLockKind.Screen) {
+  const nav = getNavigator();
+  if (nav === void 0) return { status: "unsupported" };
+  const wakeLock = readMember(nav, "wakeLock");
+  const request = readMember(wakeLock, "request");
+  if (!isFunction(request) || request === void 0) return { status: "unsupported" };
+  try {
+    const sentinel = await request.call(wakeLock, type);
+    return { status: "ok", value: toWakeLockHandle(sentinel, type) };
+  } catch (error) {
+    return classifyWakeLockRejection(error);
+  }
+}
+function holdWakeLock(options) {
+  const type = options?.type ?? WakeLockKind.Screen;
+  let state = IdleWakeLockState;
+  let handle = null;
+  let disposed = false;
+  let acquiring = false;
+  const publish = (next) => {
+    state = next;
+    const onChange = options?.onChange;
+    if (onChange === void 0) return;
+    try {
+      onChange(next);
+    } catch {
+    }
+  };
+  const acquire = async () => {
+    if (disposed || acquiring) return;
+    if (handle !== null && !handle.released) return;
+    acquiring = true;
+    try {
+      const result = await requestWakeLock(type);
+      if (disposed) {
+        if (result.status === "ok") void result.value.release();
+        return;
+      }
+      if (result.status === "ok") {
+        handle = result.value;
+        publish({ held: true, status: "ok", error: null });
+        return;
+      }
+      handle = null;
+      publish({
+        held: false,
+        status: result.status,
+        error: result.status === "unsupported" ? null : result.error
+      });
+    } finally {
+      acquiring = false;
+    }
+  };
+  const onVisibilityChange = () => {
+    if (disposed) return;
+    const doc2 = getDocument();
+    if (doc2 === void 0) return;
+    if (readMember(doc2, "visibilityState") === "visible") {
+      void acquire();
+      return;
+    }
+    handle = null;
+    if (state.held) publish({ held: false, status: state.status, error: state.error });
+  };
+  const doc = getDocument();
+  const listening = doc !== void 0 && isFunction(readMember(doc, "addEventListener"));
+  if (listening && doc !== void 0) doc.addEventListener("visibilitychange", onVisibilityChange);
+  void acquire();
+  return {
+    get state() {
+      return state;
+    },
+    release: () => {
+      if (disposed) return;
+      disposed = true;
+      if (listening && doc !== void 0) doc.removeEventListener("visibilitychange", onVisibilityChange);
+      const current = handle;
+      handle = null;
+      if (current !== null) void current.release();
+      state = IdleWakeLockState;
+    }
+  };
+}
+function useWakeLock(active, type) {
+  const state = shallowRef(IdleWakeLockState);
+  let hold = null;
+  function release() {
+    hold?.release();
+    hold = null;
+    state.value = IdleWakeLockState;
+  }
+  function apply() {
+    release();
+    if (!toValue(active)) return;
+    hold = holdWakeLock({
+      type: toValue(type),
+      onChange: (next) => {
+        state.value = next;
+      }
+    });
+  }
+  onMounted(apply);
+  watch([() => toValue(active), () => toValue(type)], apply);
+  onScopeDispose(release);
+  return state;
+}
+const ScreenOrientationType = {
+  /** Upright, the device's natural portrait. */
+  PortraitPrimary: "portrait-primary",
+  /** Upside-down portrait. */
+  PortraitSecondary: "portrait-secondary",
+  /** Rotated a quarter turn from natural portrait. */
+  LandscapePrimary: "landscape-primary",
+  /** Rotated the other quarter turn. */
+  LandscapeSecondary: "landscape-secondary"
+};
+const ScreenOrientationLock = {
+  /** Any orientation — effectively releases a lock while keeping one nominally set. */
+  Any: "any",
+  /** The device's own natural orientation, whichever that is. */
+  Natural: "natural",
+  /** Either portrait orientation, letting the device flip between them. */
+  Portrait: "portrait",
+  /** Either landscape orientation. */
+  Landscape: "landscape",
+  /** Upright portrait only. */
+  PortraitPrimary: "portrait-primary",
+  /** Upside-down portrait only. */
+  PortraitSecondary: "portrait-secondary",
+  /** One landscape direction only. */
+  LandscapePrimary: "landscape-primary",
+  /** The other landscape direction only. */
+  LandscapeSecondary: "landscape-secondary"
+};
+const FullscreenRequirementPattern = /fullscreen/i;
+const KnownOrientationTypes = Object.values(ScreenOrientationType);
+function getScreenOrientation() {
+  return readMember(getScreen(), "orientation");
+}
+function isOrientationType(value) {
+  return typeof value === "string" && KnownOrientationTypes.includes(value);
+}
+function classifyOrientationRejection(cause) {
+  const error = toError(cause);
+  if (FullscreenRequirementPattern.test(error.message)) return { status: "requires-fullscreen", error };
+  if (error.name === "SecurityError") return { status: "requires-fullscreen", error };
+  if (error.name === "NotSupportedError") return { status: "unsupported" };
+  if (error.name === "NotAllowedError") return { status: "denied", error };
+  return { status: "failed", error };
+}
+function getOrientation() {
+  const type = readMember(getScreenOrientation(), "type");
+  return isOrientationType(type) ? type : null;
+}
+function getOrientationAngle() {
+  const angle = readMember(getScreenOrientation(), "angle");
+  return typeof angle === "number" && Number.isFinite(angle) ? angle : null;
+}
+function isOrientationLockSupported() {
+  return isFunction(readMember(getScreenOrientation(), "lock"));
+}
+async function lockOrientation(orientation) {
+  const screenOrientation = getScreenOrientation();
+  const lock = readMember(screenOrientation, "lock");
+  if (!isFunction(lock) || lock === void 0) return { status: "unsupported" };
+  try {
+    await lock.call(screenOrientation, orientation);
+    return { status: "ok" };
+  } catch (error) {
+    return classifyOrientationRejection(error);
+  }
+}
+function unlockOrientation() {
+  const screenOrientation = getScreenOrientation();
+  const unlock = readMember(screenOrientation, "unlock");
+  if (!isFunction(unlock) || unlock === void 0) return { status: "unsupported" };
+  try {
+    unlock.call(screenOrientation);
+    return { status: "ok" };
+  } catch (error) {
+    return { status: "failed", error: toError(error) };
+  }
+}
+function onOrientationChange(listener) {
+  const screenOrientation = getScreenOrientation();
+  const target = screenOrientation;
+  if (target === void 0 || !isFunction(readMember(target, "addEventListener"))) {
+    return () => {
+    };
+  }
+  const handler = () => {
+    listener();
+  };
+  target.addEventListener("change", handler);
+  return () => {
+    target.removeEventListener("change", handler);
+  };
+}
+function useOrientation() {
+  const orientation = shallowRef(null);
+  const angle = shallowRef(null);
+  const supported = shallowRef(false);
+  let unsubscribe;
+  onMounted(() => {
+    const sync = () => {
+      orientation.value = getOrientation();
+      angle.value = getOrientationAngle();
+      supported.value = isOrientationLockSupported();
+    };
+    sync();
+    unsubscribe = onOrientationChange(sync);
+  });
+  onScopeDispose(() => {
+    unsubscribe?.();
+    unsubscribe = void 0;
+  });
+  const lock = (target) => lockOrientation(target);
+  const unlock = () => unlockOrientation();
+  return { orientation, angle, supported, lock, unlock };
+}
+export {
+  IdleWakeLockState,
+  ScreenOrientationLock,
+  ScreenOrientationType,
+  WakeLockKind,
+  enterFullscreen,
+  exitFullscreen,
+  getFullscreenElement,
+  getOrientation,
+  getOrientationAngle,
+  holdWakeLock,
+  isFullscreen,
+  isFullscreenSupported,
+  isOrientationLockSupported,
+  lockOrientation,
+  onFullscreenChange,
+  onOrientationChange,
+  requestWakeLock,
+  toggleFullscreen,
+  unlockOrientation,
+  useFullscreen,
+  useOrientation,
+  useWakeLock
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/screen/ScreenEnvironment.ts","../../../src/foundation/screen/Fullscreen.ts","../../../src/foundation/screen/UseFullscreen.ts","../../../src/foundation/screen/WakeLock.ts","../../../src/foundation/screen/UseWakeLock.ts","../../../src/foundation/screen/ScreenOrientation.ts","../../../src/foundation/screen/UseOrientation.ts"],"sourcesContent":["// Guarded access to the three globals this slice touches — `document`, `navigator`, `screen` — plus the hostile-\n// read helper every property access here routes through. Internal: absent from the barrel.\n//\n// WHY THIS EXISTS AT ALL: the APIs in this slice are the least uniformly implemented in the browser platform.\n// Fullscreen ships prefixed on Safari, wake lock is absent on most desktop browsers, `screen.orientation` is\n// missing on older iOS. Under SSR all three globals are gone. Reading any of them directly means a `typeof`\n// guard at ~20 call sites; one of them will eventually be forgotten, and the failure mode is a `ReferenceError`\n// thrown from a module that promises never to throw.\n//\n// WHY EVERY READ IS TRY-WRAPPED: a property read can itself throw. A polyfill installs a getter that throws when\n// its preconditions are unmet; a `Proxy` traps `get`; an embedded context revokes access to a cross-origin\n// `document` member. `foundation/errors` takes exactly this posture for the same reason — a guard that throws\n// defeats its own purpose. Unreadable therefore reads as absent, never as a failure.\n//\n// The typed-cast idiom: reads return `unknown` and each call site casts to the precise signature it needs\n// (`as (() => Promise<void>) | undefined`), rather than the slice sharing one loose callable type. The cast is\n// narrow, local, and documents the shape the platform is expected to provide at that exact point.\n\n/**\n * Reads `key` off `source`, yielding `undefined` for a non-object, a missing member, or a read that throws.\n *\n * The workhorse of this slice: prefixed members (`webkitRequestFullscreen`) are not in the DOM lib's types, and\n * stubs in tests are partial by design, so nothing may assume a member is present or readable.\n *\n * @param source The value to read from — safely accepts `undefined`, `null`, and primitives.\n * @param key The property name to read.\n * @returns The member's value, or `undefined` when it is absent or unreadable.\n */\nexport function readMember(source: unknown, key: string): unknown {\n  try {\n    if (source === null || (typeof source !== 'object' && typeof source !== 'function')) return undefined;\n    return (source as Record<string, unknown>)[key];\n  } catch {\n    // A throwing getter or `Proxy` trap. Unreadable reads as absent — see this file's header.\n    return undefined;\n  }\n}\n\n/**\n * Whether `value` is callable — the capability check behind every `*Supported` predicate in this slice.\n *\n * Deliberately only a check: call sites cast to their own precise signature before invoking, so this never\n * becomes a loose way to call an unknown value.\n *\n * @param value The value to test.\n * @returns `true` when `value` is a function.\n */\nexport function isFunction(value: unknown): boolean {\n  return typeof value === 'function';\n}\n\n/**\n * The document, or `undefined` when there is none — SSR, a worker, or any non-DOM host.\n *\n * @returns The global `document`, or `undefined`.\n */\nexport function getDocument(): Document | undefined {\n  try {\n    return typeof document === 'undefined' ? undefined : document;\n  } catch {\n    // A host that throws on the global itself. Treated as no DOM.\n    return undefined;\n  }\n}\n\n/**\n * The navigator, or `undefined` when there is none.\n *\n * Note Node ships a real `globalThis.navigator` with none of the members this slice wants, so a defined\n * navigator proves nothing on its own — every member is still capability-checked before use.\n *\n * @returns The global `navigator`, or `undefined`.\n */\nexport function getNavigator(): Navigator | undefined {\n  try {\n    return typeof navigator === 'undefined' ? undefined : navigator;\n  } catch {\n    // See `getDocument`.\n    return undefined;\n  }\n}\n\n/**\n * The screen, or `undefined` when there is none.\n *\n * @returns The global `screen`, or `undefined`.\n */\nexport function getScreen(): Screen | undefined {\n  try {\n    return typeof screen === 'undefined' ? undefined : screen;\n  } catch {\n    // See `getDocument`.\n    return undefined;\n  }\n}\n","// The Fullscreen API, made total. Enter / exit / toggle / read, each resolving to a `ScreenResult`.\n//\n// WEBKIT PREFIXES ARE NOT LEGACY CRUFT. Safari has never shipped the unprefixed names on all its surfaces —\n// `webkitRequestFullscreen`, `webkitFullscreenElement`, `webkitExitFullscreen`, and the `webkitfullscreenchange`\n// event are still the live path there. So every accessor tries the standard member first and falls back to the\n// prefixed one, and `onFullscreenChange` subscribes to BOTH events: a browser that fires only one is the normal\n// case, and a browser firing both merely calls an idempotent snapshot read twice.\n//\n// WHY A REJECTION IS CLASSIFIED RATHER THAN REPORTED: `requestFullscreen` rejects for two very different\n// reasons that the platform reports almost identically. The common one by far is a missing user gesture — the\n// call escaped its click handler, or an `await` landed before it and spent the transient activation. That is a\n// developer error with a mechanical fix, and it must not read the same as \"this browser cannot do fullscreen\".\n// The spec rejects the activation case with a `TypeError`, whereas operational failures arrive as `DOMException`s\n// with a name, so the type itself carries most of the signal; the message pattern is checked first because it is\n// the only thing that survives a browser choosing a different type.\n//\n// KNOWN AMBIGUITY, deliberately resolved toward the common case: a permissions-policy block (an iframe without\n// `allow=\"fullscreen\"`) also rejects with a `TypeError` in Chromium, so it lands on `requires-gesture` too.\n// Distinguishing them would take reading `document.featurePolicy`, which is non-standard and absent in Safari.\n// Since both are fixed by the embedder rather than at runtime, and the gesture case is overwhelmingly more\n// frequent, the mapping favours it — and the original error rides along on the result for anyone who needs more.\n//\n// `document.fullscreenEnabled` is NOT used as the support check. It reports the permissions-policy answer, not\n// the API's presence, so a `false` there would make the whole slice claim `unsupported` in an iframe where the\n// call might still be worth attempting. Method presence is the honest question for \"is this API here\".\n\nimport { toError } from '../errors';\n\nimport { getDocument, isFunction, readMember } from './ScreenEnvironment';\nimport type { ScreenFailure, ScreenResult } from './ScreenResult';\n\n/** Matches how browsers word an activation failure — checked before the error's type, which browsers vary on. */\nconst GestureRejectionPattern = /user (?:gesture|activation)|transient activation|user-activation/i;\n\n/** A fullscreen request or exit, as the platform exposes it. Safari's prefixed form returns `undefined`, not a promise. */\ntype FullscreenCall = (this: unknown) => Promise<void> | void;\n\n/** Sorts a rejected fullscreen call into the slice's vocabulary — see this file's header for the reasoning. */\nfunction classifyFullscreenRejection(cause: unknown): ScreenFailure {\n  const error = toError(cause);\n\n  if (GestureRejectionPattern.test(error.message)) return { status: 'requires-gesture', error };\n  // The spec's activation rejection. `DOMException`s (which carry a `name`) fall through to the checks below.\n  if (error.name === 'TypeError') return { status: 'requires-gesture', error };\n  if (error.name === 'NotAllowedError' || error.name === 'SecurityError') return { status: 'denied', error };\n\n  return { status: 'failed', error };\n}\n\n/** Picks the standard member off `source`, falling back to its WebKit-prefixed twin. */\nfunction pickPrefixed(source: unknown, standard: string, prefixed: string): FullscreenCall | undefined {\n  const method = readMember(source, standard) ?? readMember(source, prefixed);\n  return isFunction(method) ? (method as FullscreenCall) : undefined;\n}\n\n/**\n * The element currently presented fullscreen, or `null` when nothing is.\n *\n * Reads the standard `document.fullscreenElement` first and Safari's `webkitFullscreenElement` second. Returns\n * `null` under SSR.\n *\n * @returns The fullscreen element, or `null`.\n */\nexport function getFullscreenElement(): Element | null {\n  const doc = getDocument();\n  if (doc === undefined) return null;\n\n  const standard = readMember(doc, 'fullscreenElement');\n  if (standard !== null && standard !== undefined) return standard as Element;\n\n  const prefixed = readMember(doc, 'webkitFullscreenElement');\n  if (prefixed !== null && prefixed !== undefined) return prefixed as Element;\n\n  return null;\n}\n\n/**\n * Whether anything is currently presented fullscreen.\n *\n * A point-in-time read, not a subscription — `useFullscreen` is the reactive form. Returns `false` under SSR.\n *\n * @returns `true` when a fullscreen element is present.\n */\nexport function isFullscreen(): boolean {\n  return getFullscreenElement() !== null;\n}\n\n/**\n * Whether the Fullscreen API is present at all.\n *\n * Answers presence, not permission: an iframe lacking `allow=\"fullscreen\"` still reports `true` here, and its\n * request resolves to a non-`ok` status instead. Returns `false` under SSR. See this file's header for why\n * `document.fullscreenEnabled` is not consulted.\n *\n * @returns `true` when a fullscreen request could be attempted.\n */\nexport function isFullscreenSupported(): boolean {\n  const doc = getDocument();\n  if (doc === undefined) return false;\n\n  const root = readMember(doc, 'documentElement');\n  return isFunction(readMember(root, 'requestFullscreen')) || isFunction(readMember(root, 'webkitRequestFullscreen'));\n}\n\n/**\n * Presents `element` fullscreen, defaulting to the document root.\n *\n * CALL THIS FROM A USER GESTURE. Browsers require transient activation, and a call that has lost it — because it\n * sits outside a click handler, or because an `await` preceded it — resolves to `requires-gesture`, not `failed`.\n *\n * Never throws, never rejects.\n *\n * @param element The element to present. Defaults to `document.documentElement`.\n * @returns `ok` once the platform accepts the request, or the classified failure.\n */\nexport async function enterFullscreen(element?: Element): Promise<ScreenResult> {\n  const doc = getDocument();\n  if (doc === undefined) return { status: 'unsupported' };\n\n  const target = element ?? (readMember(doc, 'documentElement') as Element | null | undefined);\n  if (target === null || target === undefined) return { status: 'unsupported' };\n\n  const request = pickPrefixed(target, 'requestFullscreen', 'webkitRequestFullscreen');\n  if (request === undefined) return { status: 'unsupported' };\n\n  try {\n    // `await` on Safari's `undefined` return is a no-op, which is exactly the intended \"already done\" semantic.\n    await request.call(target);\n    return { status: 'ok' };\n  } catch (error) {\n    return classifyFullscreenRejection(error);\n  }\n}\n\n/**\n * Leaves fullscreen.\n *\n * Idempotent: exiting when nothing is fullscreen resolves to `ok` rather than surfacing the `TypeError` browsers\n * reject that call with. A caller unwinding its own state should not have to check first.\n *\n * Never throws, never rejects.\n *\n * @returns `ok` once the document is out of fullscreen, or the classified failure.\n */\nexport async function exitFullscreen(): Promise<ScreenResult> {\n  const doc = getDocument();\n  if (doc === undefined) return { status: 'unsupported' };\n\n  const exit = pickPrefixed(doc, 'exitFullscreen', 'webkitExitFullscreen');\n  if (exit === undefined) return { status: 'unsupported' };\n\n  if (getFullscreenElement() === null) return { status: 'ok' };\n\n  try {\n    await exit.call(doc);\n    return { status: 'ok' };\n  } catch (error) {\n    return classifyFullscreenRejection(error);\n  }\n}\n\n/**\n * Exits fullscreen when something is presented, enters with `element` otherwise.\n *\n * Inherits {@link enterFullscreen}'s gesture requirement on the entering leg. Never throws, never rejects.\n *\n * @param element The element to present when entering. Defaults to `document.documentElement`.\n * @returns The result of whichever leg ran.\n */\nexport function toggleFullscreen(element?: Element): Promise<ScreenResult> {\n  return isFullscreen() ? exitFullscreen() : enterFullscreen(element);\n}\n\n/**\n * Subscribes `listener` to fullscreen transitions, returning an unsubscribe.\n *\n * Listens on both `fullscreenchange` and `webkitfullscreenchange`, so a browser on either spelling is covered.\n * A browser firing both invokes `listener` twice per transition — harmless for the snapshot reads this exists to\n * drive, but do not use it to count transitions.\n *\n * Returns a no-op unsubscribe under SSR, so a caller never needs to branch on the environment.\n *\n * @param listener Invoked after every fullscreen transition.\n * @returns A function that removes both listeners.\n */\nexport function onFullscreenChange(listener: () => void): () => void {\n  const doc = getDocument();\n  if (doc === undefined || !isFunction(readMember(doc, 'addEventListener'))) {\n    return () => {\n      // No DOM to unsubscribe from. A no-op keeps the caller's teardown path uniform.\n    };\n  }\n\n  const handler = (): void => {\n    listener();\n  };\n\n  doc.addEventListener('fullscreenchange', handler);\n  doc.addEventListener('webkitfullscreenchange', handler);\n\n  return () => {\n    doc.removeEventListener('fullscreenchange', handler);\n    doc.removeEventListener('webkitfullscreenchange', handler);\n  };\n}\n","// The Vue binding of the fullscreen vector. No behaviour of its own — the three actions delegate, so the\n// never-throws contract holds unchanged and every outcome arrives as a `ScreenResult`.\n//\n// STATE IS A SUBSCRIPTION, NOT A LOCAL FLAG. Fullscreen can be left by routes this app never sees: the Escape\n// key, the browser's own exit affordance, the OS window manager. A flag flipped in `enter` / `exit` would be\n// wrong the instant the user pressed Escape. The subscription re-reads the platform's own `fullscreenElement` on\n// every notification, so the component's answer is the document's answer, always. This is the Vue counterpart of\n// the original's `useSyncExternalStore` and the same shape as `foundation/hooks`' `useMediaQuery`: seed `false`,\n// subscribe in `onMounted`, unsubscribe in `onScopeDispose`.\n//\n// SEEDING `false` RATHER THAN READING AT SETUP IS THE SSR RULE, not a nicety: `isFullscreen` and\n// `isFullscreenSupported` both read `document`, which does not exist on the server. `onMounted` is client-only by\n// construction, so the server pass answers `false` for both and the truth lands at hydration with no mismatch.\n//\n// `supported` rides the same subscription rather than being computed once — one pair of listeners drives both\n// values, the same trade `foundation/device`'s `useDisplayMode` makes with its media queries.\n\nimport {\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport {\n  enterFullscreen,\n  exitFullscreen,\n  isFullscreen,\n  isFullscreenSupported,\n  onFullscreenChange,\n  toggleFullscreen,\n} from './Fullscreen';\nimport type { ScreenResult } from './ScreenResult';\n\n/** What {@link useFullscreen} returns. */\nexport interface FullscreenControls {\n  /** Whether anything is currently presented fullscreen — including a transition this composable did not initiate. */\n  readonly isFullscreen: Readonly<ShallowRef<boolean>>;\n\n  /** Whether the Fullscreen API is present. `false` under SSR; render the control only once this is `true`. */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n\n  /** Presents the composable's target fullscreen. Call from a user gesture. Resolves to the result; never throws. */\n  readonly enter: () => Promise<ScreenResult>;\n\n  /** Leaves fullscreen. Resolves to `ok` when nothing was presented. Never throws. */\n  readonly exit: () => Promise<ScreenResult>;\n\n  /** Exits when presented, enters otherwise. Call from a user gesture. Never throws. */\n  readonly toggle: () => Promise<ScreenResult>;\n}\n\n/**\n * Tracks fullscreen state and exposes the three actions against an optional target.\n *\n * Pass `target` to present one element (a video, a canvas, a dashboard panel); omit it to present the whole\n * document. Takes the element as a ref or getter rather than handing one back, so a `useTemplateRef` drops\n * straight in — and it is read at call time, so it may still be `null` when the handler is wired up.\n *\n * Inherits the module's never-throws contract.\n *\n * @param target The element to present. Defaults to `document.documentElement` when omitted or still `null`.\n * @returns The current state plus the `enter` / `exit` / `toggle` actions.\n */\nexport function useFullscreen(\n  target?: MaybeRefOrGetter<Element | null | undefined>,\n): FullscreenControls {\n  const active = shallowRef(false);\n  const supported = shallowRef(false);\n\n  let unsubscribe: (() => void) | undefined;\n\n  onMounted(() => {\n    const sync = (): void => {\n      active.value = isFullscreen();\n      supported.value = isFullscreenSupported();\n    };\n    sync();\n    unsubscribe = onFullscreenChange(sync);\n  });\n\n  onScopeDispose(() => {\n    unsubscribe?.();\n    unsubscribe = undefined;\n  });\n\n  const enter = (): Promise<ScreenResult> => enterFullscreen(toValue(target) ?? undefined);\n  const exit = (): Promise<ScreenResult> => exitFullscreen();\n  const toggle = (): Promise<ScreenResult> => toggleFullscreen(toValue(target) ?? undefined);\n\n  return { isFullscreen: active, supported, enter, exit, toggle };\n}\n","// The Screen Wake Lock API — keeping the display awake — in two layers: `requestWakeLock` for one lock, and\n// `holdWakeLock` for a lock that STAYS held.\n//\n// THE WHOLE DIFFICULTY OF THIS API: the platform releases the lock the moment the page stops being visible, and\n// it does not give it back. Switch tabs, answer a call, let the phone lock — the sentinel is released and every\n// later read of it says so. Nothing re-acquires on return. A recipe app that requests a lock on mount and calls\n// it done therefore works exactly until the user glances at a message, after which the screen sleeps mid-recipe\n// and the feature silently no longer exists. That is the bug this module is written to prevent, and it is why\n// `holdWakeLock` — not `requestWakeLock` — is what a consumer normally wants.\n//\n// So `holdWakeLock` subscribes to `visibilitychange` and re-requests when the page comes back visible and the\n// caller still wants the lock. Re-acquiring is guarded three ways: not when disposed, not when a request is\n// already in flight (visibility can flap faster than the request settles), and not when the current handle is\n// still live (a `visible` → `visible` notification must not stack a second lock).\n//\n// WHY THIS IS NOT A COMPOSABLE. The re-acquire cycle is the part most worth testing, and as a composable it\n// would only be testable through a renderer — with the timing of a watcher, a `nextTick` boundary, and a fake\n// `document` layered on top of the behaviour under test. As a plain function it is directly testable in node,\n// and `useWakeLock` becomes a thin binding with nothing of its own to get wrong. The same split\n// `foundation/share` makes between `share` and `useShare`.\n//\n// `denied` covers both of the spec's `NotAllowedError` cases — a permissions-policy block and a document that is\n// not visible — because they are the same answer to the consumer: the platform said no to this request, and\n// repeating it right now changes nothing.\n\nimport { toError } from '../errors';\n\nimport { getDocument, getNavigator, isFunction, readMember } from './ScreenEnvironment';\nimport type { ScreenFailure, ScreenStatus, ScreenValueResult } from './ScreenResult';\n\n/** The kinds of wake lock the platform defines. Only `screen` exists; the spec keeps the axis open. */\nexport const WakeLockKind = {\n  /** Keeps the display on and undimmed. The only kind any browser implements today. */\n  Screen: 'screen',\n} as const;\n\n/** One of the {@link WakeLockKind} values. */\nexport type WakeLockKind = (typeof WakeLockKind)[keyof typeof WakeLockKind];\n\n/** `navigator.wakeLock.request`, as the platform exposes it. */\ntype WakeLockRequest = (this: unknown, type: string) => Promise<unknown>;\n\n/** `WakeLockSentinel.release`, as the platform exposes it. */\ntype WakeLockRelease = (this: unknown) => Promise<void>;\n\n/**\n * A held wake lock. Wraps the platform's `WakeLockSentinel` so that {@link WakeLockHandle.release} is total and\n * {@link WakeLockHandle.released} reads through to the live sentinel rather than a snapshot taken at request\n * time — the platform flips that flag on its own when the page is hidden.\n */\nexport interface WakeLockHandle {\n  /** The kind of lock held. */\n  readonly type: WakeLockKind;\n\n  /** Whether the lock is no longer held — by an explicit release, or by the platform hiding the page. */\n  readonly released: boolean;\n\n  /** Releases the lock. Safe to call twice, and on an already-released lock. Never throws. */\n  release: () => Promise<void>;\n}\n\n/** Where a {@link holdWakeLock} sits: `idle` before its first request settles, then the last request's status. */\nexport type WakeLockStatus = 'idle' | ScreenStatus;\n\n/** The observable state of a {@link WakeLockHold}. */\nexport interface WakeLockState {\n  /** Whether a lock is held right now. Drops to `false` when the page is hidden, back to `true` on return. */\n  readonly held: boolean;\n\n  /** The status of the most recent request, or `idle` before the first one settles. */\n  readonly status: WakeLockStatus;\n\n  /** The error from the most recent non-`ok` request, or `null`. Always `null` for `unsupported`. */\n  readonly error: Error | null;\n}\n\n/** Tunes a {@link holdWakeLock}. */\nexport interface WakeLockHoldOptions {\n  /** The kind of lock to hold. Defaults to `screen`, the only kind implemented. */\n  readonly type?: WakeLockKind;\n\n  /** Called on every state transition — the seam `useWakeLock` renders from. A throw from it is swallowed. */\n  readonly onChange?: (state: WakeLockState) => void;\n}\n\n/** A wake lock held across visibility changes until released. */\nexport interface WakeLockHold {\n  /** The current state. Re-read it after an `onChange`; it is not reactive on its own. */\n  readonly state: WakeLockState;\n\n  /** Stops re-acquiring, unsubscribes, and releases any held lock. Idempotent. */\n  release: () => void;\n}\n\n/**\n * The state before any request has settled. A module constant, not a fresh literal: `useWakeLock` resets to it\n * whenever it goes inactive, and a stable identity is what keeps that reset from waking every watcher on it.\n */\nexport const IdleWakeLockState: WakeLockState = { held: false, status: 'idle', error: null };\n\n/** Sorts a rejected wake-lock request into the slice's vocabulary — see this file's header on `denied`. */\nfunction classifyWakeLockRejection(cause: unknown): ScreenFailure {\n  const error = toError(cause);\n\n  if (error.name === 'NotAllowedError') return { status: 'denied', error };\n\n  return { status: 'failed', error };\n}\n\n/** Wraps a platform sentinel so `release` cannot throw and `released` stays live. */\nfunction toWakeLockHandle(sentinel: unknown, type: WakeLockKind): WakeLockHandle {\n  return {\n    type,\n\n    get released(): boolean {\n      // Read through on every access — the platform flips this when it takes the lock back.\n      return readMember(sentinel, 'released') === true;\n    },\n\n    release: async (): Promise<void> => {\n      const release = readMember(sentinel, 'release') as WakeLockRelease | undefined;\n      if (!isFunction(release) || release === undefined) return;\n\n      try {\n        await release.call(sentinel);\n      } catch {\n        // Already released, or the sentinel was detached with the document. Either way the lock is gone, which\n        // is what the caller asked for — there is nothing to recover or report.\n      }\n    },\n  };\n}\n\n/**\n * Requests a single wake lock.\n *\n * The lock this yields is released by the platform as soon as the page is hidden and is NOT restored on return —\n * prefer {@link holdWakeLock} unless you genuinely want one attempt. Must be called from an active, visible\n * document; a hidden one is rejected as `denied`.\n *\n * Never throws, never rejects.\n *\n * @param type The kind of lock. Defaults to `screen`.\n * @returns `ok` with the handle, or the classified failure.\n */\nexport async function requestWakeLock(\n  type: WakeLockKind = WakeLockKind.Screen,\n): Promise<ScreenValueResult<WakeLockHandle>> {\n  const nav = getNavigator();\n  if (nav === undefined) return { status: 'unsupported' };\n\n  const wakeLock = readMember(nav, 'wakeLock');\n  const request = readMember(wakeLock, 'request') as WakeLockRequest | undefined;\n  if (!isFunction(request) || request === undefined) return { status: 'unsupported' };\n\n  try {\n    const sentinel = await request.call(wakeLock, type);\n    return { status: 'ok', value: toWakeLockHandle(sentinel, type) };\n  } catch (error) {\n    return classifyWakeLockRejection(error);\n  }\n}\n\n/**\n * Holds a wake lock, re-acquiring it whenever the page returns to visible.\n *\n * This is the form a consumer normally wants: the platform drops the lock on every tab switch, notification, and\n * screen blank, and without the re-acquire the feature quietly stops working after the first one. Starts\n * requesting immediately and reports each transition through `options.onChange`.\n *\n * Call {@link WakeLockHold.release} when done — nothing else ends the cycle.\n *\n * Never throws.\n *\n * @param options The lock kind and the state-change callback.\n * @returns The live hold.\n */\nexport function holdWakeLock(options?: WakeLockHoldOptions): WakeLockHold {\n  const type = options?.type ?? WakeLockKind.Screen;\n\n  let state: WakeLockState = IdleWakeLockState;\n  let handle: WakeLockHandle | null = null;\n  let disposed = false;\n  let acquiring = false;\n\n  const publish = (next: WakeLockState): void => {\n    state = next;\n\n    const onChange = options?.onChange;\n    if (onChange === undefined) return;\n\n    try {\n      onChange(next);\n    } catch {\n      // The consumer's own listener failed. The hold is unaffected and keeps its lock — swallowing here is the\n      // same posture `foundation/share` takes with a throwing `onError`.\n    }\n  };\n\n  const acquire = async (): Promise<void> => {\n    if (disposed || acquiring) return;\n    // Still holding a live lock — a `visible` → `visible` notification must not stack a second one.\n    if (handle !== null && !handle.released) return;\n\n    acquiring = true;\n    try {\n      const result = await requestWakeLock(type);\n\n      if (disposed) {\n        // Released while the request was in flight. Nothing is watching the state any more, but the lock itself\n        // is real and would otherwise outlive the hold that owns it.\n        if (result.status === 'ok') void result.value.release();\n        return;\n      }\n\n      if (result.status === 'ok') {\n        handle = result.value;\n        publish({ held: true, status: 'ok', error: null });\n        return;\n      }\n\n      handle = null;\n      publish({\n        held: false,\n        status: result.status,\n        error: result.status === 'unsupported' ? null : result.error,\n      });\n    } finally {\n      acquiring = false;\n    }\n  };\n\n  const onVisibilityChange = (): void => {\n    if (disposed) return;\n\n    const doc = getDocument();\n    if (doc === undefined) return;\n\n    if (readMember(doc, 'visibilityState') === 'visible') {\n      void acquire();\n      return;\n    }\n\n    // Hidden: the platform has already taken the lock back without telling us. Drop the handle so the next\n    // `visible` re-requests, and report the loss so a consumer's indicator does not keep claiming it is held.\n    handle = null;\n    if (state.held) publish({ held: false, status: state.status, error: state.error });\n  };\n\n  const doc = getDocument();\n  const listening = doc !== undefined && isFunction(readMember(doc, 'addEventListener'));\n  if (listening && doc !== undefined) doc.addEventListener('visibilitychange', onVisibilityChange);\n\n  void acquire();\n\n  return {\n    get state(): WakeLockState {\n      return state;\n    },\n\n    release: (): void => {\n      if (disposed) return;\n      disposed = true;\n\n      if (listening && doc !== undefined) doc.removeEventListener('visibilitychange', onVisibilityChange);\n\n      const current = handle;\n      handle = null;\n      if (current !== null) void current.release();\n\n      // State is reset WITHOUT publishing. `release` runs from a scope-disposal cleanup, and calling back into a\n      // consumer that is tearing down buys nothing — `useWakeLock` resets its own state on the same path.\n      state = IdleWakeLockState;\n    },\n  };\n}\n","// The Vue binding of the wake-lock vector. Deliberately thin: `holdWakeLock` owns the request cycle, the\n// visibility re-acquire, and the teardown, so this file is only the watcher that starts one and the state that\n// renders from it. Everything worth testing lives one layer down, in node.\n//\n// THE TEARDOWN RELEASE IS NOT OPTIONAL. A wake lock outlives the component that took it — nothing in the platform\n// ties it to a component tree. Leak one and the user's screen stays awake after they have navigated away from the\n// recipe, the workout, the boarding pass; on a phone that is a visible battery cost with no visible cause. So\n// every path releases: scope disposal, an `active` flip, and a re-run of the watcher.\n//\n// STARTED FROM `onMounted` PLUS A NON-IMMEDIATE WATCHER, never an immediate one. `holdWakeLock` reads\n// `navigator.wakeLock` and attaches a `visibilitychange` listener to `document`; an immediate watcher also runs\n// during a server render, where neither exists. `onMounted` covers the initial state, the watcher covers every\n// later flip, and both funnel through the same `apply` so `active: true → false` releases through exactly the\n// same code path as a disposal, with no second teardown to keep in sync.\n\nimport {\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { holdWakeLock, IdleWakeLockState } from './WakeLock';\nimport type { WakeLockHold, WakeLockKind, WakeLockState } from './WakeLock';\n\n/**\n * Holds a screen wake lock for as long as `active` resolves to `true`, re-acquiring it after every visibility\n * change.\n *\n * Drive it from whatever state means \"the user is watching\": a running timer, a playing video, an open recipe.\n * Flipping `active` to `false` releases; so does disposing the scope. The lock is re-acquired automatically when\n * the page returns to visible, which is the behaviour a raw `navigator.wakeLock.request` does not give you.\n *\n * Holds a defined `idle` state under SSR and on browsers without the API — check `status === 'unsupported'`\n * before offering a \"keep screen awake\" control.\n *\n * @param active Whether the lock should be held. A ref or getter is how it flips.\n * @param type The kind of lock. Defaults to `screen`. Changing it re-acquires.\n * @returns The current {@link WakeLockState}.\n */\nexport function useWakeLock(\n  active: MaybeRefOrGetter<boolean>,\n  type?: MaybeRefOrGetter<WakeLockKind | undefined>,\n): Readonly<ShallowRef<WakeLockState>> {\n  const state = shallowRef<WakeLockState>(IdleWakeLockState);\n\n  let hold: WakeLockHold | null = null;\n\n  function release(): void {\n    hold?.release();\n    hold = null;\n    // The shared constant is load-bearing: a stable identity means an already-idle state does not wake watchers.\n    state.value = IdleWakeLockState;\n  }\n\n  function apply(): void {\n    release();\n    if (!toValue(active)) return;\n    hold = holdWakeLock({\n      type: toValue(type),\n      onChange: (next) => {\n        state.value = next;\n      },\n    });\n  }\n\n  onMounted(apply);\n  // Non-immediate on purpose: an immediate watcher runs on the server, where `navigator` and `document` are\n  // absent. Two getters, so Vue compares each with `Object.is` and only a genuine change re-acquires.\n  watch([() => toValue(active), () => toValue(type)], apply);\n  onScopeDispose(release);\n\n  return state;\n}\n","// The Screen Orientation API — reading which way the device is held, and asking it to stay that way.\n//\n// LOCKING ALMOST ALWAYS NEEDS FULLSCREEN. On mobile Chromium — the only place `lock()` meaningfully works — the\n// document must already be fullscreen, and a call from a normal page rejects. Desktop browsers reject it\n// outright, and Safari does not implement `lock()` at all on any platform. So the realistic sequence is\n// `enterFullscreen()` first, `lockOrientation()` second, and a consumer that skips the first step gets a\n// rejection that has nothing to do with orientation being unavailable.\n//\n// That is why `requires-fullscreen` is its own status. Reported as `failed` it reads as \"orientation locking is\n// broken here\" and a consumer hides the feature; reported accurately it says \"you called this too early\", which\n// is fixable in one line. The union is widened for this one entry point rather than for the whole slice, the\n// same way `foundation/share` widens `ShareResult` with `copied` for `shareOrCopy` alone — the extra leg exists\n// where it is real and nowhere else.\n//\n// NAMING, because this repo has two orientations: `foundation/utils`' `Orientation` is a LAYOUT axis\n// (horizontal / vertical) for components. This slice's `ScreenOrientationType` is a DEVICE orientation\n// (portrait-primary / landscape-secondary …). They are unrelated vocabularies and the `Screen` prefix keeps an\n// import from silently resolving to the wrong one.\n//\n// The read and lock vocabularies differ, which is not an accident of this file: the platform reports one of four\n// concrete orientations, but accepts eight lock targets including the relative `natural`, `portrait`, and\n// `landscape`. Modelling them as one type would let `getOrientation()` claim to return `any`.\n//\n// KNOWN GAP — the legacy `window.orientationchange` event and `window.orientation` angle are deliberately NOT\n// read. They are the only signal on iOS before 16.4, but `screen.orientation` is absent there too, so a\n// subscription would fire against a `getOrientation()` that returns `null` regardless. One mechanism, one\n// answer; the same call `foundation/device`'s `useDisplayMode` makes about `navigator.standalone`.\n\nimport { toError } from '../errors';\n\nimport { getScreen, isFunction, readMember } from './ScreenEnvironment';\nimport type { ScreenResult } from './ScreenResult';\n\n/** The concrete orientations the platform reports — what `getOrientation` can return. */\nexport const ScreenOrientationType = {\n  /** Upright, the device's natural portrait. */\n  PortraitPrimary: 'portrait-primary',\n  /** Upside-down portrait. */\n  PortraitSecondary: 'portrait-secondary',\n  /** Rotated a quarter turn from natural portrait. */\n  LandscapePrimary: 'landscape-primary',\n  /** Rotated the other quarter turn. */\n  LandscapeSecondary: 'landscape-secondary',\n} as const;\n\n/** One of the {@link ScreenOrientationType} values. */\nexport type ScreenOrientationType = (typeof ScreenOrientationType)[keyof typeof ScreenOrientationType];\n\n/** The lock targets the platform accepts — the four concrete orientations plus four relative ones. */\nexport const ScreenOrientationLock = {\n  /** Any orientation — effectively releases a lock while keeping one nominally set. */\n  Any: 'any',\n  /** The device's own natural orientation, whichever that is. */\n  Natural: 'natural',\n  /** Either portrait orientation, letting the device flip between them. */\n  Portrait: 'portrait',\n  /** Either landscape orientation. */\n  Landscape: 'landscape',\n  /** Upright portrait only. */\n  PortraitPrimary: 'portrait-primary',\n  /** Upside-down portrait only. */\n  PortraitSecondary: 'portrait-secondary',\n  /** One landscape direction only. */\n  LandscapePrimary: 'landscape-primary',\n  /** The other landscape direction only. */\n  LandscapeSecondary: 'landscape-secondary',\n} as const;\n\n/** One of the {@link ScreenOrientationLock} values. */\nexport type ScreenOrientationLock = (typeof ScreenOrientationLock)[keyof typeof ScreenOrientationLock];\n\n/**\n * A {@link ScreenResult} widened with the precondition that only orientation locking has.\n *\n * `requires-fullscreen` means the API is present and willing, but the document is not fullscreen — enter\n * fullscreen and retry. Distinct from `denied` (the platform refused outright) and from `unsupported` (this\n * device cannot lock at all, which is every desktop browser and all of Safari).\n */\nexport type OrientationLockResult = ScreenResult | { readonly status: 'requires-fullscreen'; readonly error: Error };\n\n/** The `status` discriminant of an {@link OrientationLockResult}. */\nexport type OrientationLockStatus = OrientationLockResult['status'];\n\n/** `ScreenOrientation.lock`, as the platform exposes it. */\ntype OrientationLockCall = (this: unknown, orientation: string) => Promise<void>;\n\n/** `ScreenOrientation.unlock`, as the platform exposes it — synchronous and void, unlike `lock`. */\ntype OrientationUnlockCall = (this: unknown) => void;\n\n/** Matches how browsers word the fullscreen precondition, which they report with varying error names. */\nconst FullscreenRequirementPattern = /fullscreen/i;\n\n/** The reported orientations, for validating whatever the platform actually puts in `screen.orientation.type`. */\nconst KnownOrientationTypes: readonly string[] = Object.values(ScreenOrientationType);\n\n/** The `screen.orientation` object, or `undefined` where the API is absent (older iOS, SSR). */\nfunction getScreenOrientation(): unknown {\n  return readMember(getScreen(), 'orientation');\n}\n\n/** Whether `value` is one of the four orientations the platform is specified to report. */\nfunction isOrientationType(value: unknown): value is ScreenOrientationType {\n  return typeof value === 'string' && KnownOrientationTypes.includes(value);\n}\n\n/** Sorts a rejected `lock()` into the vocabulary — see this file's header on why fullscreen gets its own leg. */\nfunction classifyOrientationRejection(cause: unknown): Exclude<OrientationLockResult, { status: 'ok' }> {\n  const error = toError(cause);\n\n  // Checked before the name: browsers disagree on the type here (`SecurityError`, `NotSupportedError`, a bare\n  // `DOMException`) but all of them say \"fullscreen\" in the message.\n  if (FullscreenRequirementPattern.test(error.message)) return { status: 'requires-fullscreen', error };\n  if (error.name === 'SecurityError') return { status: 'requires-fullscreen', error };\n  // The device cannot lock at all — desktop Chromium's answer. `unsupported` carries no error by contract.\n  if (error.name === 'NotSupportedError') return { status: 'unsupported' };\n  if (error.name === 'NotAllowedError') return { status: 'denied', error };\n\n  return { status: 'failed', error };\n}\n\n/**\n * The current device orientation, or `null` when it cannot be determined — SSR, or a browser without\n * `screen.orientation` (iOS before 16.4).\n *\n * A point-in-time read; `useOrientation` is the reactive form. An unrecognized value from the platform reads as\n * `null` rather than being passed through, so the return type is honest.\n *\n * @returns The current {@link ScreenOrientationType}, or `null`.\n */\nexport function getOrientation(): ScreenOrientationType | null {\n  const type = readMember(getScreenOrientation(), 'type');\n  return isOrientationType(type) ? type : null;\n}\n\n/**\n * The current orientation angle in degrees (`0`, `90`, `180`, `270`), or `null` when unavailable.\n *\n * Relative to the device's natural orientation, so `0` is portrait on a phone and landscape on many tablets —\n * never infer a shape from the angle alone. Pair it with {@link getOrientation}.\n *\n * @returns The angle, or `null`.\n */\nexport function getOrientationAngle(): number | null {\n  const angle = readMember(getScreenOrientation(), 'angle');\n  return typeof angle === 'number' && Number.isFinite(angle) ? angle : null;\n}\n\n/**\n * Whether orientation locking is present at all.\n *\n * `true` says the method exists, not that it will succeed — a lock outside fullscreen still fails on the devices\n * that have it. `false` under SSR, on desktop Safari, and on iOS.\n *\n * @returns `true` when a lock could be attempted.\n */\nexport function isOrientationLockSupported(): boolean {\n  return isFunction(readMember(getScreenOrientation(), 'lock'));\n}\n\n/**\n * Asks the device to hold `orientation`.\n *\n * ENTER FULLSCREEN FIRST. Mobile browsers require it, and a call from a normal page resolves to\n * `requires-fullscreen` — a distinct status precisely because it is fixable, unlike `unsupported`. Desktop\n * browsers and Safari resolve to `unsupported` no matter what you do.\n *\n * Never throws, never rejects.\n *\n * @param orientation The lock target — a concrete orientation, or a relative one like `natural`.\n * @returns `ok` once the device honours the lock, or the classified failure.\n */\nexport async function lockOrientation(orientation: ScreenOrientationLock): Promise<OrientationLockResult> {\n  const screenOrientation = getScreenOrientation();\n\n  const lock = readMember(screenOrientation, 'lock') as OrientationLockCall | undefined;\n  if (!isFunction(lock) || lock === undefined) return { status: 'unsupported' };\n\n  try {\n    await lock.call(screenOrientation, orientation);\n    return { status: 'ok' };\n  } catch (error) {\n    return classifyOrientationRejection(error);\n  }\n}\n\n/**\n * Releases any orientation lock, letting the device rotate freely again.\n *\n * Synchronous, unlike {@link lockOrientation} — the platform's `unlock()` returns nothing and takes effect\n * immediately. Safe to call when no lock is held. Resolves to `unsupported` rather than `ok` where the API is\n * absent, so \"nothing to unlock\" and \"cannot unlock\" stay distinguishable.\n *\n * Never throws.\n *\n * @returns `ok` when the lock was released, `unsupported` where the API is absent, `failed` on a throw.\n */\nexport function unlockOrientation(): ScreenResult {\n  const screenOrientation = getScreenOrientation();\n\n  const unlock = readMember(screenOrientation, 'unlock') as OrientationUnlockCall | undefined;\n  if (!isFunction(unlock) || unlock === undefined) return { status: 'unsupported' };\n\n  try {\n    unlock.call(screenOrientation);\n    return { status: 'ok' };\n  } catch (error) {\n    // `unlock()` has no fullscreen precondition, so the widened leg cannot apply here — a throw is a plain failure.\n    return { status: 'failed', error: toError(error) };\n  }\n}\n\n/**\n * Subscribes `listener` to orientation changes, returning an unsubscribe.\n *\n * Returns a no-op unsubscribe where the API is absent, so a caller never branches on the environment.\n *\n * @param listener Invoked after every orientation change.\n * @returns A function that removes the listener.\n */\nexport function onOrientationChange(listener: () => void): () => void {\n  const screenOrientation = getScreenOrientation();\n\n  const target = screenOrientation as EventTarget | undefined;\n  if (target === undefined || !isFunction(readMember(target, 'addEventListener'))) {\n    return () => {\n      // No orientation API to unsubscribe from. A no-op keeps the caller's teardown path uniform.\n    };\n  }\n\n  const handler = (): void => {\n    listener();\n  };\n\n  target.addEventListener('change', handler);\n\n  return () => {\n    target.removeEventListener('change', handler);\n  };\n}\n","// The Vue binding of the orientation vector — reactive orientation plus the two actions, so a component does\n// not pair a ref with a `screen.orientation` subscription by hand.\n//\n// Reads go through one subscription for the same reason `useFullscreen`'s do: the device rotates without asking\n// this app, so re-reading the platform's own value on every notification is the only correct answer. The three\n// values are separate `shallowRef`s rather than one snapshot object — the original had to split them because\n// `useSyncExternalStore` loops on a fresh object identity, and keeping them split here preserves that the two\n// primitives update independently.\n//\n// SEEDED, NOT READ AT SETUP: `getOrientation`, `getOrientationAngle`, and `isOrientationLockSupported` all read\n// `screen`, which does not exist on the server. `onMounted` is client-only, so SSR gets a defined `null` / `null`\n// / `false` and the truth arrives at hydration with no mismatch.\n\nimport { onMounted, onScopeDispose, shallowRef, type ShallowRef } from 'vue';\n\nimport {\n  getOrientation,\n  getOrientationAngle,\n  isOrientationLockSupported,\n  lockOrientation,\n  onOrientationChange,\n  unlockOrientation,\n} from './ScreenOrientation';\nimport type { OrientationLockResult, ScreenOrientationLock, ScreenOrientationType } from './ScreenOrientation';\nimport type { ScreenResult } from './ScreenResult';\n\n/** What {@link useOrientation} returns. */\nexport interface OrientationControls {\n  /** The current device orientation, or `null` under SSR and where `screen.orientation` is absent. */\n  readonly orientation: Readonly<ShallowRef<ScreenOrientationType | null>>;\n\n  /** The current angle in degrees relative to the device's natural orientation, or `null` when unavailable. */\n  readonly angle: Readonly<ShallowRef<number | null>>;\n\n  /** Whether locking is present. `false` under SSR, on desktop, and on Safari — hide the control when `false`. */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n\n  /** Asks the device to hold an orientation. Enter fullscreen first. Resolves to the result; never throws. */\n  readonly lock: (orientation: ScreenOrientationLock) => Promise<OrientationLockResult>;\n\n  /** Releases the lock. Synchronous, like the platform's own `unlock()`. Never throws. */\n  readonly unlock: () => ScreenResult;\n}\n\n/**\n * Tracks the device orientation and exposes the lock actions.\n *\n * Use the reported orientation to adapt a layout only where a CSS media query genuinely cannot — the query is\n * cheaper and needs no JavaScript. The real reason to reach for this composable is `lock` / `unlock`, which have\n * no CSS equivalent.\n *\n * Inherits the module's never-throws contract.\n *\n * @returns The current orientation and angle plus the `lock` / `unlock` actions.\n */\nexport function useOrientation(): OrientationControls {\n  const orientation = shallowRef<ScreenOrientationType | null>(null);\n  const angle = shallowRef<number | null>(null);\n  const supported = shallowRef(false);\n\n  let unsubscribe: (() => void) | undefined;\n\n  onMounted(() => {\n    const sync = (): void => {\n      orientation.value = getOrientation();\n      angle.value = getOrientationAngle();\n      supported.value = isOrientationLockSupported();\n    };\n    sync();\n    unsubscribe = onOrientationChange(sync);\n  });\n\n  onScopeDispose(() => {\n    unsubscribe?.();\n    unsubscribe = undefined;\n  });\n\n  const lock = (target: ScreenOrientationLock): Promise<OrientationLockResult> => lockOrientation(target);\n  const unlock = (): ScreenResult => unlockOrientation();\n\n  return { orientation, angle, supported, lock, unlock };\n}\n"],"names":["doc"],"mappings":"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"}

package/dist/foundation/selection/Field.d.ts

@@ -0,0 +1,31 @@
+/** Represents the value extraction for one field of an item — the unit a comparator or predicate reads. */
+export type FieldAccessor<T> = (item: T) => unknown;
+/**
+ * Represents the field-name → accessor registry handed to {@link readField}, `applySort`, and `applyFilters`.
+ * Every entry is optional; a field with no entry falls back to a plain property read.
+ */
+export type FieldAccessors<T, TField extends string = string> = Partial<Readonly<Record<TField, FieldAccessor<T>>>>;
+/**
+ * Reads one field off an item: the registered accessor when present, otherwise the item's own property of
+ * that name. Returns `undefined` for a non-object item with no accessor — which the sort model treats as
+ * nullish (sorts last) and the filter model treats as "matches nothing but a nullish `equals`".
+ */
+export declare function readField<T, TField extends string>(item: T, field: TField, accessors?: FieldAccessors<T, TField>): unknown;
+/**
+ * Reports whether a value is absent for comparison purposes — `null`, `undefined`, or `NaN`.
+ *
+ * `NaN` counts as nullish deliberately: it is the one number that makes `a - b` return `NaN`, which would
+ * make a comparator non-transitive and leave the sorted order engine-defined. Folding it in with the
+ * nullish values gives it a documented home (last) instead.
+ */
+export declare function isNullish(value: unknown): boolean;
+/** Represents the locale seam shared by the sort and filter entry points. Omit to use the host default. */
+export interface LocaleOptions {
+    /** The BCP 47 locale driving string collation (sort) and case folding (filter). Defaults to the host locale. */
+    locale?: string;
+}
+/**
+ * Coerces any value to text for the filter model's text operators. Symbols are handled explicitly because
+ * `String(symbol)` throws, and a filter must never throw on unexpected row data.
+ */
+export declare function toText(value: unknown): string;

package/dist/foundation/selection/Filter.d.ts

@@ -0,0 +1,71 @@
+import { FieldAccessors, LocaleOptions } from './Field';
+/** Defines the closed set of comparisons a filter may express. */
+export declare const FilterOperator: {
+    /** Refers to exact equality — case-folded for strings, no cross-type coercion. */
+    readonly Equals: "equals";
+    /** Refers to a substring match on the value's text form. */
+    readonly Contains: "contains";
+    /** Refers to a prefix match on the value's text form. */
+    readonly StartsWith: "startsWith";
+    /** Refers to a strictly-greater-than comparison. */
+    readonly GreaterThan: "gt";
+    /** Refers to a strictly-less-than comparison. */
+    readonly LessThan: "lt";
+    /** Refers to an inclusive range check between two bounds. */
+    readonly Between: "between";
+    /** Refers to membership in a fixed list of values. */
+    readonly In: "in";
+};
+export type FilterOperator = (typeof FilterOperator)[keyof typeof FilterOperator];
+/** The fields every filter carries, whatever its operator. */
+interface FilterBase<TField extends string> {
+    /** The field name, resolved through the accessor registry or read as a plain property. */
+    readonly field: TField;
+    /** The case sensitivity of string comparison. Defaults to `false` — text operators fold case. */
+    readonly isCaseSensitive?: boolean;
+}
+/** Represents a filter whose operator takes a single comparison value. */
+export interface ValueFilter<TField extends string = string> extends FilterBase<TField> {
+    /** The comparison applied to the field. */
+    readonly op: 'equals' | 'contains' | 'startsWith' | 'gt' | 'lt';
+    /** The value compared against the field. */
+    readonly value: unknown;
+}
+/** Represents an inclusive range filter. Bounds may be given in either order. */
+export interface BetweenFilter<TField extends string = string> extends FilterBase<TField> {
+    /** The comparison applied to the field. */
+    readonly op: 'between';
+    /** The inclusive `[low, high]` bounds — normalised when reversed. */
+    readonly value: readonly [unknown, unknown];
+}
+/** Represents a membership filter over a fixed candidate list. */
+export interface InFilter<TField extends string = string> extends FilterBase<TField> {
+    /** The comparison applied to the field. */
+    readonly op: 'in';
+    /** The candidate values; the field matches when it equals any of them. */
+    readonly value: readonly unknown[];
+}
+/**
+ * Represents one filter clause. A discriminated union rather than `{ field, op, value: unknown }` so the
+ * value shape each operator requires — a 2-tuple for `between`, an array for `in` — is checked at the call
+ * site instead of failing at match time.
+ */
+export type FilterDescriptor<TField extends string = string> = ValueFilter<TField> | BetweenFilter<TField> | InFilter<TField>;
+/**
+ * Reports whether one item satisfies one filter clause. Exported for the surfaces that test a single row —
+ * an optimistic insert deciding whether the new row belongs in the current view, for instance.
+ */
+export declare function matchesFilter<T, TField extends string = string>(item: T, filter: FilterDescriptor<TField>, accessors?: FieldAccessors<T, TField>, options?: LocaleOptions): boolean;
+/**
+ * Builds the AND-ed predicate a filter list describes — exported so a virtualised or streaming surface can
+ * test rows as they arrive instead of materialising a filtered array.
+ */
+export declare function filterPredicate<T, TField extends string = string>(filters: readonly FilterDescriptor<TField>[], accessors?: FieldAccessors<T, TField>, options?: LocaleOptions): (item: T) => boolean;
+/**
+ * Keeps the items matching every filter. Clauses combine with AND — two clauses on the same field narrow
+ * each other (the `between` of a `gt` and an `lt`), they do not union.
+ *
+ * Returns the input array itself when there is nothing to filter, so an unfiltered render costs no copy.
+ */
+export declare function applyFilters<T, TField extends string = string>(items: ReadonlyArray<T>, filters: readonly FilterDescriptor<TField>[], accessors?: FieldAccessors<T, TField>, options?: LocaleOptions): ReadonlyArray<T>;
+export {};