@wow-two-beta/ui-vue 0.0.4 → 0.0.6

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

@@ -1 +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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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/screen/ScreenEnvironment.ts","../../../src/foundation/screen/Fullscreen.ts","../../../src/foundation/screen/hooks/UseFullscreen.ts","../../../src/foundation/screen/WakeLock.ts","../../../src/foundation/screen/hooks/UseWakeLock.ts","../../../src/foundation/screen/ScreenOrientation.ts","../../../src/foundation/screen/hooks/UseOrientation.ts","../../../src/foundation/screen/enums/ScreenFailureCode.ts","../../../src/foundation/screen/enums/OrientationLockFailureCode.ts"],"sourcesContent":["/**\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","import { toError } from '../errors';\n\nimport { getDocument, isFunction, readMember } from './ScreenEnvironment';\nimport type { ScreenFailure, ScreenRequestResult } from './ScreenOutcome';\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. Safari's prefixed form returns `undefined` rather than a promise. */\ntype FullscreenCall = (this: unknown) => Promise<void> | void;\n\n/** Classifies explicit platform evidence; ambiguous TypeError failures retain their diagnostics. */\nfunction classifyFullscreenRejection(cause: unknown): ScreenFailure {\n  const error = toError(cause);\n\n  if (GestureRejectionPattern.test(error.message)) 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 while transient user activation remains active. Failure diagnostics distinguish an explicit\n * activation rejection from permission refusals and ambiguous platform errors.\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<ScreenRequestResult> {\n  const doc = getDocument();\n  if (doc === undefined) return { ok: false, failure: { status: 'unsupported' } };\n\n  const target = element ?? (readMember(doc, 'documentElement') as Element | null | undefined);\n  if (target === null || target === undefined) return { ok: false, failure: { status: 'unsupported' } };\n\n  const request = pickPrefixed(target, 'requestFullscreen', 'webkitRequestFullscreen');\n  if (request === undefined) return { ok: false, failure: { 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 { ok: true, value: undefined };\n  } catch (error) {\n    return { ok: false, failure: 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<ScreenRequestResult> {\n  const doc = getDocument();\n  if (doc === undefined) return { ok: false, failure: { status: 'unsupported' } };\n\n  const exit = pickPrefixed(doc, 'exitFullscreen', 'webkitExitFullscreen');\n  if (exit === undefined) return { ok: false, failure: { status: 'unsupported' } };\n\n  if (getFullscreenElement() === null) return { ok: true, value: undefined };\n\n  try {\n    await exit.call(doc);\n    return { ok: true, value: undefined };\n  } catch (error) {\n    return { ok: false, failure: 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<ScreenRequestResult> {\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","import { onMounted, onScopeDispose, shallowRef, toValue, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport {\n  enterFullscreen,\n  exitFullscreen,\n  isFullscreen,\n  isFullscreenSupported,\n  onFullscreenChange,\n  toggleFullscreen,\n} from '../Fullscreen';\nimport type { ScreenRequestResult } from '../ScreenOutcome';\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<ScreenRequestResult>;\n\n  /** Leaves fullscreen. Resolves to `ok` when nothing was presented. Never throws. */\n  readonly exit: () => Promise<ScreenRequestResult>;\n\n  /** Exits when presented, enters otherwise. Call from a user gesture. Never throws. */\n  readonly toggle: () => Promise<ScreenRequestResult>;\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(target?: MaybeRefOrGetter<Element | null | undefined>): 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<ScreenRequestResult> => enterFullscreen(toValue(target) ?? undefined);\n  const exit = (): Promise<ScreenRequestResult> => exitFullscreen();\n  const toggle = (): Promise<ScreenRequestResult> => toggleFullscreen(toValue(target) ?? undefined);\n\n  return { isFullscreen: active, supported, enter, exit, toggle };\n}\n","import { toError } from '../errors';\n\nimport { getDocument, getNavigator, isFunction, readMember } from './ScreenEnvironment';\nimport type { ScreenFailure, ScreenStatus, ScreenRequestResult } from './ScreenOutcome';\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<ScreenRequestResult<WakeLockHandle>> {\n  const nav = getNavigator();\n  if (nav === undefined) return { ok: false, failure: { 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 { ok: false, failure: { status: 'unsupported' } };\n\n  try {\n    const sentinel = await request.call(wakeLock, type);\n    return { ok: true, value: toWakeLockHandle(sentinel, type) };\n  } catch (error) {\n    return { ok: false, failure: 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.ok) void result.value.release();\n        return;\n      }\n\n      if (result.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.failure.status,\n        error: result.failure.status === 'unsupported' ? null : result.failure.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","import { onMounted, onScopeDispose, shallowRef, toValue, watch, type MaybeRefOrGetter, type ShallowRef } 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","import type { OrientationLockResult } from './models/OrientationLockResult';\nimport type { OrientationLockFailure } from './models/OrientationLockFailure';\n\nimport { toError } from '../errors';\n\nimport { getScreen, isFunction, readMember } from './ScreenEnvironment';\nimport type { ScreenRequestResult } from './ScreenOutcome';\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];\nexport type { OrientationLockFailure } from './models/OrientationLockFailure';\nexport type { OrientationLockResult } from './models/OrientationLockResult';\n\n/** The `status` discriminant of an {@link OrientationLockResult}. */\nexport type OrientationLockStatus = 'ok' | OrientationLockFailure['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: ReadonlyArray<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): OrientationLockFailure {\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 { ok: false, failure: { status: 'unsupported' } };\n\n  try {\n    await lock.call(screenOrientation, orientation);\n    return { ok: true, value: undefined };\n  } catch (error) {\n    return { ok: false, failure: 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(): ScreenRequestResult {\n  const screenOrientation = getScreenOrientation();\n\n  const unlock = readMember(screenOrientation, 'unlock') as OrientationUnlockCall | undefined;\n  if (!isFunction(unlock) || unlock === undefined) return { ok: false, failure: { status: 'unsupported' } };\n\n  try {\n    unlock.call(screenOrientation);\n    return { ok: true, value: undefined };\n  } catch (error) {\n    // `unlock()` has no fullscreen precondition, so the widened leg cannot apply here — a throw is a plain failure.\n    return { ok: false, failure: { 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","import { 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 { ScreenRequestResult } from '../ScreenOutcome';\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: () => ScreenRequestResult;\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 = (): ScreenRequestResult => unlockOrientation();\n\n  return { orientation, angle, supported, lock, unlock };\n}\n","/** Closed failure vocabulary for ScreenFailure. */\nexport const ScreenFailureCode = {\n  Unsupported: 'unsupported',\n  Denied: 'denied',\n  RequiresGesture: 'requires-gesture',\n  Failed: 'failed',\n} as const;\n\nexport type ScreenFailureCode = (typeof ScreenFailureCode)[keyof typeof ScreenFailureCode];\n","import { ScreenFailureCode } from './ScreenFailureCode';\n\n/** Closed failure vocabulary for OrientationLockFailure. */\nexport const OrientationLockFailureCode = {\n  ...ScreenFailureCode,\n  RequiresFullscreen: 'requires-fullscreen',\n} as const;\n\nexport type OrientationLockFailureCode = (typeof OrientationLockFailureCode)[keyof typeof OrientationLockFailureCode];\n"],"names":["doc"],"mappings":"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"}

package/dist/foundation/screen/models/OrientationLockFailure.d.ts

@@ -0,0 +1,7 @@
+import { OrientationLockFailureCode } from '../enums/OrientationLockFailureCode';
+import { ScreenFailure } from '../ScreenOutcome';
+/** Expected reasons the operation could not produce its requested value. */
+export type OrientationLockFailure = ScreenFailure | {
+    readonly status: typeof OrientationLockFailureCode.RequiresFullscreen;
+    readonly error: Error;
+};

package/dist/foundation/screen/models/OrientationLockResult.d.ts

@@ -0,0 +1,3 @@
+import { Result } from '../../results';
+import { OrientationLockFailure } from './OrientationLockFailure';
+export type OrientationLockResult = Result<void, OrientationLockFailure>;

package/dist/foundation/screen/models/ScreenFailure.d.ts

@@ -0,0 +1,14 @@
+import { ScreenFailureCode } from '../enums/ScreenFailureCode';
+/** Expected reasons the operation could not produce its requested value. */
+export type ScreenFailure = {
+    readonly status: typeof ScreenFailureCode.Unsupported;
+} | {
+    readonly status: typeof ScreenFailureCode.Denied;
+    readonly error: Error;
+} | {
+    readonly status: typeof ScreenFailureCode.RequiresGesture;
+    readonly error: Error;
+} | {
+    readonly status: typeof ScreenFailureCode.Failed;
+    readonly error: Error;
+};

package/dist/foundation/screen/models/ScreenRequestResult.d.ts

@@ -0,0 +1,4 @@
+import { Result } from '../../results';
+import { ScreenFailure } from './ScreenFailure';
+/** The completed operation, carrying either its value or its typed failure. */
+export type ScreenRequestResult<TValue = void> = Result<TValue, ScreenFailure>;

package/dist/foundation/selection/hooks/UseFilters.d.ts

@@ -0,0 +1,34 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { FilterDescriptor } from '../models/Filter';
+/** Options accepted by {@link useFilters}. All are optional; the default is an uncontrolled empty filter set. */
+export interface UseFiltersOptions<TField extends string = string> {
+    /** The controlled clause list. Pass to own the filter state; omit for uncontrolled. */
+    filters?: MaybeRefOrGetter<ReadonlyArray<FilterDescriptor<TField>> | undefined>;
+    /** The initial clause list when uncontrolled. Read once; ignored while `filters` is passed. */
+    defaultFilters?: MaybeRefOrGetter<ReadonlyArray<FilterDescriptor<TField>> | undefined>;
+    /** Fires with the next clause list whenever it changes. */
+    onFiltersChange?: (filters: ReadonlyArray<FilterDescriptor<TField>>) => void;
+}
+/** The filter state and bound operations returned by {@link useFilters}. */
+export interface FilterControls<TField extends string = string> {
+    /** The current clauses, AND-ed. Feed to `applyFilters` / `filterPredicate`. */
+    readonly filters: ComputedRef<ReadonlyArray<FilterDescriptor<TField>>>;
+    /** Replaces the whole clause list — the escape hatch for several clauses on one field. */
+    readonly setFilters: (filters: ReadonlyArray<FilterDescriptor<TField>>) => void;
+    /** Upserts a clause by field, keeping its position when it already exists. */
+    readonly setFilter: (filter: FilterDescriptor<TField>) => void;
+    /** Drops every clause on a field. */
+    readonly removeFilter: (field: TField) => void;
+    /** Drops every clause. */
+    readonly clear: () => void;
+    /** The first clause on a field, or `undefined` — what a filter-bar control reads to render its value. */
+    readonly filterFor: (field: TField) => FilterDescriptor<TField> | undefined;
+}
+/**
+ * Binds the filter model to reactive state, controlled or uncontrolled.
+ *
+ * Controlled when `filters` resolves to a defined value: the composable stores nothing and only calls
+ * `onFiltersChange` — the shape a server-side filtered list wants, where the clauses round-trip through a
+ * query.
+ */
+export declare function useFilters<TField extends string = string>(options?: UseFiltersOptions<TField>): FilterControls<TField>;

package/dist/foundation/selection/hooks/UseSelection.d.ts

@@ -0,0 +1,54 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { SelectionMode, SelectionKey, SelectionState, SelectionStatus, SelectRangeOptions } from '../models/Selection';
+/** Options accepted by {@link useSelection}. All are optional; the default is an uncontrolled multi-select. */
+export interface UseSelectionOptions<TKey extends SelectionKey> {
+    /** The selection mode. Defaults to `'multiple'`. */
+    mode?: MaybeRefOrGetter<SelectionMode | undefined>;
+    /** The controlled selected keys. Pass to own the selection; omit for uncontrolled. */
+    selectedKeys?: MaybeRefOrGetter<ReadonlyArray<TKey> | undefined>;
+    /** The initial selected keys when uncontrolled. Read once; ignored while `selectedKeys` is passed. */
+    defaultSelectedKeys?: MaybeRefOrGetter<ReadonlyArray<TKey> | undefined>;
+    /** Fires with the next key list whenever the selection actually changes. */
+    onSelectionChange?: (keys: ReadonlyArray<TKey>) => void;
+}
+/** The selection state and bound operations returned by {@link useSelection}. */
+export interface SelectionControls<TKey extends SelectionKey> {
+    /** The current immutable snapshot — pass to the pure model for anything not covered here. */
+    readonly state: ComputedRef<SelectionState<TKey>>;
+    /** The selected keys in insertion order. */
+    readonly keys: ComputedRef<ReadonlyArray<TKey>>;
+    /** The mode in force. */
+    readonly mode: ComputedRef<SelectionMode>;
+    /** The number of selected keys. */
+    readonly count: ComputedRef<number>;
+    /** Reports whether a key is selected. */
+    readonly isSelected: (key: TKey) => boolean;
+    /** The tri-state for a header checkbox over the given (usually filtered) keys. */
+    readonly status: (keys: Iterable<TKey>) => SelectionStatus;
+    /** Selects a key and anchors on it. */
+    readonly select: (key: TKey) => void;
+    /** Deselects a key and anchors on it. */
+    readonly deselect: (key: TKey) => void;
+    /** Flips a key and anchors on it — the plain click. */
+    readonly toggle: (key: TKey) => void;
+    /** Adds every given key to the selection. */
+    readonly selectAll: (keys: Iterable<TKey>) => void;
+    /** Empties the selection and drops the anchor. */
+    readonly clear: () => void;
+    /** Flips every given key, leaving keys outside the set alone. */
+    readonly invert: (keys: Iterable<TKey>) => void;
+    /** The header-checkbox click over the given keys. */
+    readonly toggleAll: (keys: Iterable<TKey>) => void;
+    /** Selects the run between an explicit anchor and a target, in the surface's visual order. */
+    readonly selectRange: (anchor: TKey, target: TKey, orderedKeys: ReadonlyArray<TKey>, options?: SelectRangeOptions) => void;
+    /** The shift-click — extends from the tracked anchor to the target. */
+    readonly extend: (target: TKey, orderedKeys: ReadonlyArray<TKey>, options?: SelectRangeOptions) => void;
+}
+/**
+ * Binds the selection model to reactive state, controlled or uncontrolled.
+ *
+ * Controlled when `selectedKeys` resolves to a defined value: the composable never stores keys, it only calls
+ * `onSelectionChange` with the next list. Uncontrolled otherwise, seeded from `defaultSelectedKeys`, with
+ * `onSelectionChange` still firing so a consumer can observe without owning.
+ */
+export declare function useSelection<TKey extends SelectionKey>(options?: UseSelectionOptions<TKey>): SelectionControls<TKey>;

package/dist/foundation/selection/hooks/UseSort.d.ts

@@ -0,0 +1,36 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { SortDescriptor, SortDirection } from '../models/Sort';
+/** Options accepted by {@link useSort}. All are optional; the default is an uncontrolled single-field sort. */
+export interface UseSortOptions<TField extends string = string> {
+    /** The controlled ordering. Pass to own the sort state; omit for uncontrolled. */
+    sort?: MaybeRefOrGetter<ReadonlyArray<SortDescriptor<TField>> | undefined>;
+    /** The initial ordering when uncontrolled. Read once; ignored while `sort` is passed. */
+    defaultSort?: MaybeRefOrGetter<ReadonlyArray<SortDescriptor<TField>> | undefined>;
+    /** Fires with the next ordering whenever it changes. */
+    onSortChange?: (sort: ReadonlyArray<SortDescriptor<TField>>) => void;
+    /** The multi-field behaviour of {@link SortControls.toggle}. Defaults to `false` (one sorted field). */
+    isMulti?: MaybeRefOrGetter<boolean | undefined>;
+}
+/** The sort state and bound operations returned by {@link useSort}. */
+export interface SortControls<TField extends string = string> {
+    /** The current ordering — array order is precedence. Feed to `applySort` / `sortComparator`. */
+    readonly descriptors: ComputedRef<ReadonlyArray<SortDescriptor<TField>>>;
+    /** Advances a field through `asc → desc → none` — the header click. */
+    readonly toggle: (field: TField) => void;
+    /** Replaces the whole ordering — for a "sort by" menu that sets state outright. */
+    readonly setSort: (descriptors: ReadonlyArray<SortDescriptor<TField>>) => void;
+    /** Drops all ordering. */
+    readonly clear: () => void;
+    /** The direction applied to a field, or `null` when unsorted — drives the header's arrow and `aria-sort`. */
+    readonly directionFor: (field: TField) => SortDirection | null;
+    /** The 0-based precedence of a field, or `-1` — the multi-sort header's order badge. */
+    readonly indexFor: (field: TField) => number;
+}
+/**
+ * Binds the sort model to reactive state, controlled or uncontrolled.
+ *
+ * Controlled when `sort` resolves to a defined value: the composable stores nothing and only calls
+ * `onSortChange` — the shape a server-side sorted table wants, where the ordering round-trips through a query
+ * rather than local state.
+ */
+export declare function useSort<TField extends string = string>(options?: UseSortOptions<TField>): SortControls<TField>;

package/dist/foundation/selection/hooks/UseTypeahead.d.ts

@@ -0,0 +1,42 @@
+import { MaybeRefOrGetter } from 'vue';
+/** Resolves the typeahead item pool — a static array, a ref, or a getter read lazily on each keystroke. */
+type ItemSource<T> = MaybeRefOrGetter<ReadonlyArray<T>>;
+/** Configures {@link useTypeahead}. `T` is the item type the caller stores per option. */
+export interface UseTypeaheadOptions<T> {
+    /** Supplies the items to match against; a ref or function is re-read on every keystroke (live lists). */
+    items: ItemSource<T>;
+    /** Extracts the comparable label from an item. Matching is case-insensitive on this string. */
+    getLabel: (item: T) => string;
+    /** Reports whether an item is disabled; disabled items are skipped during matching. */
+    isDisabled?: (item: T) => boolean;
+    /** Fires with the matched item and its index in the (live) item array when a keystroke resolves. */
+    onMatch: (item: T, index: number) => void;
+    /** Returns the index of the currently-active item — same-letter cycling starts after it. */
+    getActiveIndex?: () => number;
+    /** Disables the matcher when `false`; every key falls through unhandled. Defaults to `true`. */
+    enabled?: MaybeRefOrGetter<boolean>;
+    /** Idle time (ms) after which the typed buffer resets. Defaults to `500`. */
+    timeout?: MaybeRefOrGetter<number>;
+}
+/** The keyboard handler + manual reset returned by {@link useTypeahead}. */
+export interface UseTypeaheadReturn {
+    /** Feeds a keydown into the matcher. Returns `true` when consumed (caller should stop), else `false`. */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+    /** Clears the typed buffer immediately (e.g. on blur / close). */
+    reset: () => void;
+}
+/**
+ * APG-correct type-to-select matcher (WAI-ARIA listbox/combobox typeahead). Accumulates printable
+ * chars into a buffer (resets after `timeout` ms idle): a repeated single char cycles to the next
+ * label starting with it (after `getActiveIndex()`, wrap-around), else prefix-matches the whole
+ * buffer case-insensitively; disabled items skipped. On a hit `onMatch(item, index)` fires; consumed
+ * keys return `true`, others `false` to fall through. Space is typeable only while buffering (a
+ * leading Space reaches the caller). SSR-safe; reset timer cleared when the scope is disposed.
+ *
+ * `items`, `enabled` and `timeout` may each be a ref or getter and are read per keystroke, so the
+ * matcher tracks a live list without the original's options-in-a-ref indirection. The callbacks
+ * (`getLabel`, `onMatch`, …) are read off the options object at call time — pass a `reactive`
+ * options object if they must be swappable.
+ */
+export declare function useTypeahead<T>(options: UseTypeaheadOptions<T>): UseTypeaheadReturn;
+export {};

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

@@ -1,7 +1,8 @@
-export { isNullish, readField, toText, type FieldAccessor, type FieldAccessors, type LocaleOptions, } from './Field';
-export { clear, createSelection, deselect, extendSelection, invert, isSelected, select, selectAll, selectRange, selectedKeys, selectionCount, selectionStatus, toggle, toggleAll, SelectionMode, SelectionStatus, type SelectionKey, type SelectionState, type SelectRangeOptions, } from './Selection';
-export { applySort, compareValues, sortComparator, sortDirectionFor, sortIndexFor, toggleSort, SortDirection, type SortDescriptor, type ToggleSortOptions, } from './Sort';
-export { applyFilters, filterPredicate, matchesFilter, FilterOperator, type BetweenFilter, type FilterDescriptor, type InFilter, type ValueFilter, } from './Filter';
-export { useSelection, type SelectionControls, type UseSelectionOptions, } from './UseSelection';
-export { useSort, type SortControls, type UseSortOptions } from './UseSort';
-export { useFilters, type FilterControls, type UseFiltersOptions } from './UseFilters';
+export { isNullish, readField, toText, type FieldAccessor, type FieldAccessors, type LocaleOptions, } from './models/Field';
+export { clear, createSelection, deselect, extendSelection, invert, isSelected, select, selectAll, selectRange, selectedKeys, selectionCount, selectionStatus, toggle, toggleAll, SelectionMode, SelectionStatus, type SelectionKey, type SelectionState, type SelectRangeOptions, } from './models/Selection';
+export { applySort, compareValues, sortComparator, sortDirectionFor, sortIndexFor, toggleSort, SortDirection, type SortDescriptor, type ToggleSortOptions, } from './models/Sort';
+export { applyFilters, filterPredicate, matchesFilter, FilterOperator, type BetweenFilter, type FilterDescriptor, type InFilter, type ValueFilter, } from './models/Filter';
+export { useSelection, type SelectionControls, type UseSelectionOptions } from './hooks/UseSelection';
+export { useSort, type SortControls, type UseSortOptions } from './hooks/UseSort';
+export { useFilters, type FilterControls, type UseFiltersOptions } from './hooks/UseFilters';
+export * from './hooks/UseTypeahead';