cursedbelt 0.0.0 → 2.3.0

package/src/react/keep-awake/KeepAwake.tsx

@@ -0,0 +1,32 @@
+import { useEffect, useRef } from 'react';
+import type { KeepAwakeStatus } from './keepAwakeEngine';
+import { useKeepAwake, type UseKeepAwakeOptions } from './useKeepAwake';
+
+export interface KeepAwakeProps extends UseKeepAwakeOptions {
+  /** Observe what actually took hold — for a status chip, a dev overlay, or a test. */
+  readonly onStatusChange?: (status: KeepAwakeStatus) => void;
+}
+
+/**
+ * Drop-in, renders nothing: mount it on any page that must not let the machine sleep.
+ *
+ * ```tsx
+ * <KeepAwake />
+ * ```
+ *
+ * All the behavior (and the browser rules behind it) lives in `useKeepAwake` /
+ * `keepAwakeEngine`. This exists so a page needs no hook plumbing — the fallback video
+ * element is created imperatively on `document.body`, so there is nothing to render and
+ * nothing to lay out.
+ */
+export const KeepAwake = ({ onStatusChange, ...options }: KeepAwakeProps = {}): null => {
+  const status = useKeepAwake(options);
+  // Ref'd so an inline `onStatusChange` lambda can't turn every parent render into
+  // another notification; `status` keeps a stable identity between engine emissions.
+  const notify = useRef(onStatusChange);
+  notify.current = onStatusChange;
+  useEffect(() => {
+    notify.current?.(status);
+  }, [status]);
+  return null;
+};

package/src/react/keep-awake/index.ts

@@ -0,0 +1,11 @@
+export { KeepAwake, type KeepAwakeProps } from './KeepAwake';
+export {
+  createKeepAwakeEngine,
+  type KeepAwakeEngine,
+  type KeepAwakeEngineOptions,
+  type KeepAwakeSource,
+  type KeepAwakeStatus,
+  type KeepAwakeVideoMode,
+} from './keepAwakeEngine';
+export { createSilentClipUrl, SILENT_CLIP_BASE64, SILENT_CLIP_MIME } from './silentClip';
+export { useKeepAwake, type UseKeepAwakeOptions, type UseKeepAwakeResult } from './useKeepAwake';

package/src/react/keep-awake/keepAwakeEngine.spec.ts

@@ -0,0 +1,311 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { createKeepAwakeEngine, type KeepAwakeStatus } from './keepAwakeEngine';
+
+/** Let the engine's `await`ed chain (request → play → emit) settle. */
+const flush = async (): Promise<void> => {
+  for (let i = 0; i < 8; i += 1) await Promise.resolve();
+};
+
+interface FakeSentinel {
+  released: boolean;
+  release: () => Promise<void>;
+  addEventListener: (type: string, fn: () => void) => void;
+  removeEventListener: (type: string, fn: () => void) => void;
+  fireRelease: () => void;
+}
+
+const fakeSentinel = (): FakeSentinel => {
+  const listeners = new Set<() => void>();
+  return {
+    released: false,
+    release() {
+      this.released = true;
+      return Promise.resolve();
+    },
+    addEventListener: (_type, fn) => {
+      listeners.add(fn);
+    },
+    removeEventListener: (_type, fn) => {
+      listeners.delete(fn);
+    },
+    fireRelease: () => {
+      for (const fn of listeners) fn();
+    },
+  };
+};
+
+const setWakeLock = (value: unknown): void => {
+  Object.defineProperty(navigator, 'wakeLock', { value, configurable: true });
+};
+
+const setVisibility = (state: DocumentVisibilityState): void => {
+  Object.defineProperty(document, 'visibilityState', { value: state, configurable: true });
+};
+
+/**
+ * happy-dom's HTMLMediaElement has no real pipeline, so `play()` is stubbed per test —
+ * resolved for "autoplay allowed", rejected for "blocked, needs a gesture".
+ */
+const stubPlay = (impl: () => Promise<void>): void => {
+  (HTMLMediaElement.prototype as unknown as { play: () => Promise<void> }).play = impl;
+};
+
+const videosInBody = (): HTMLVideoElement[] => Array.from(document.querySelectorAll('video'));
+
+afterEach(() => {
+  setWakeLock(undefined);
+  setVisibility('visible');
+  for (const el of videosInBody()) el.remove();
+  delete document.documentElement.dataset.keepAwake;
+});
+
+describe('createKeepAwakeEngine', () => {
+  /**
+   * 🔴 The `data-keep-awake` stamp, and this is the only case in the file whose subject is
+   * OBSERVABILITY rather than behaviour.
+   *
+   * Everything else about this component is invisible: it renders nothing, a
+   * `WakeLockSentinel` is not a node, and the fallback element is equally present playing or
+   * not. So an app can mount `<KeepAwake />`, have it fail on every load, and no browser
+   * smoke in the fleet can tell — which is exactly the shape of failure that survives for
+   * months. The attribute is what makes "is this page actually holding the machine awake"
+   * an assertion instead of an assumption, so it is pinned here in all three states.
+   */
+  test('stamps which mechanism is holding the display on <html>', async () => {
+    const sentinel = fakeSentinel();
+    setWakeLock({ request: () => Promise.resolve(sentinel) });
+
+    const engine = createKeepAwakeEngine();
+    engine.start();
+    await flush();
+    expect(document.documentElement.dataset.keepAwake).toBe('wake-lock');
+
+    // Holding nothing is written as `none`, never left blank: absent and not-holding are
+    // different facts, and only the first one means "this was never mounted".
+    engine.stop();
+    setWakeLock(undefined);
+    stubPlay(() => Promise.resolve());
+    const fallback = createKeepAwakeEngine();
+    fallback.start();
+    await flush();
+    expect(document.documentElement.dataset.keepAwake).toBe('video');
+
+    fallback.stop();
+    expect(document.documentElement.dataset.keepAwake).toBeUndefined();
+  });
+
+  test('a page that is holding NOTHING says so rather than staying silent', async () => {
+    setWakeLock(undefined);
+    stubPlay(() => Promise.reject(new Error('NotAllowedError: blocked')));
+
+    const engine = createKeepAwakeEngine();
+    engine.start();
+    await flush();
+
+    expect(engine.status.active).toBe(false);
+    expect(document.documentElement.dataset.keepAwake).toBe('none');
+    engine.stop();
+  });
+
+  test('takes a screen wake lock and does not start the video fallback in auto mode', async () => {
+    const sentinel = fakeSentinel();
+    const request = mock(() => Promise.resolve(sentinel));
+    setWakeLock({ request });
+    const seen: KeepAwakeStatus[] = [];
+
+    const engine = createKeepAwakeEngine({ onStatus: (s) => seen.push(s) });
+    engine.start();
+    await flush();
+
+    expect(request).toHaveBeenCalledWith('screen');
+    expect(engine.status.wakeLock).toBe('held');
+    expect(engine.status.source).toBe('wake-lock');
+    expect(engine.status.active).toBe(true);
+    expect(videosInBody()).toHaveLength(0);
+    expect(seen.at(-1)?.active).toBe(true);
+
+    engine.stop();
+    expect(sentinel.released).toBe(true);
+  });
+
+  test('falls back to a video configured the way the engines actually require', async () => {
+    setWakeLock(undefined);
+    stubPlay(() => Promise.resolve());
+
+    const engine = createKeepAwakeEngine();
+    engine.start();
+    await flush();
+
+    expect(engine.status.wakeLock).toBe('unsupported');
+    expect(engine.status.video).toBe('playing');
+    expect(engine.status.source).toBe('video');
+
+    const [video] = videosInBody();
+    expect(video).toBeDefined();
+    expect(video?.dataset.keepAwake).toBe('fallback');
+    // WebKit's shouldDisableSleep() bails on a looping element…
+    expect(video?.hasAttribute('loop')).toBe(false);
+    // …and on a muted one, or one at volume 0 (canProduceAudio() === false).
+    expect(video?.muted).toBe(false);
+    expect(video?.volume).toBeGreaterThan(0);
+    expect(video?.hasAttribute('playsinline')).toBe(true);
+    // Never `display:none` — see the note in keepAwakeEngine.ts.
+    expect(video?.style.display).not.toBe('none');
+    expect(video?.src.length).toBeGreaterThan(0);
+
+    engine.stop();
+    expect(videosInBody()).toHaveLength(0);
+  });
+
+  test('muted mode really does mute (and so gives up the Safari path)', async () => {
+    setWakeLock(undefined);
+    stubPlay(() => Promise.resolve());
+
+    const engine = createKeepAwakeEngine({ silentVideo: true });
+    engine.start();
+    await flush();
+
+    expect(videosInBody()[0]?.muted).toBe(true);
+    engine.stop();
+  });
+
+  test('a rejected request arms a one-shot gesture retry (the Safari path)', async () => {
+    const sentinel = fakeSentinel();
+    let allow = false;
+    const request = mock(() =>
+      allow
+        ? Promise.resolve(sentinel)
+        : Promise.reject(new DOMException('Permission was denied', 'NotAllowedError')),
+    );
+    setWakeLock({ request });
+    stubPlay(() => Promise.reject(new DOMException('blocked', 'NotAllowedError')));
+
+    const engine = createKeepAwakeEngine();
+    engine.start();
+    await flush();
+
+    expect(engine.status.wakeLock).toBe('blocked');
+    expect(engine.status.needsGesture).toBe(true);
+    expect(engine.status.error).toContain('NotAllowedError');
+
+    allow = true;
+    stubPlay(() => Promise.resolve());
+    document.dispatchEvent(new Event('pointerdown'));
+    await flush();
+
+    expect(engine.status.wakeLock).toBe('held');
+    expect(engine.status.needsGesture).toBe(false);
+
+    // One-shot: the listener is gone, so a second gesture must not re-request.
+    const callsAfterGrant = request.mock.calls.length;
+    document.dispatchEvent(new Event('pointerdown'));
+    await flush();
+    expect(request.mock.calls.length).toBe(callsAfterGrant);
+
+    engine.stop();
+  });
+
+  test('a play() that never settles does not block the gesture retry', async () => {
+    // The WebKit shape, and a bug this engine actually had: a blocked autoplay leaves
+    // play()'s promise PENDING rather than rejecting, so anything that awaits it stalls.
+    // If acquire() stalls, its in-flight guard swallows the gesture retry and the page
+    // is stuck on the weaker fallback forever.
+    const sentinel = fakeSentinel();
+    let allow = false;
+    const request = mock(() =>
+      allow
+        ? Promise.resolve(sentinel)
+        : Promise.reject(new DOMException('needs activation', 'NotAllowedError')),
+    );
+    setWakeLock({ request });
+    stubPlay(() => new Promise<void>(() => {}));
+
+    const engine = createKeepAwakeEngine();
+    engine.start();
+    await flush();
+    expect(engine.status.needsGesture).toBe(true);
+
+    allow = true;
+    document.dispatchEvent(new Event('pointerdown'));
+    await flush();
+
+    expect(engine.status.wakeLock).toBe('held');
+    // …and the now-superfluous fallback is torn down, not left running.
+    expect(videosInBody()).toHaveLength(0);
+
+    engine.stop();
+  });
+
+  test('re-acquires after the UA releases the lock on a tab switch', async () => {
+    const first = fakeSentinel();
+    const second = fakeSentinel();
+    let nth = 0;
+    const request = mock(() => Promise.resolve(nth++ === 0 ? first : second));
+    setWakeLock({ request });
+
+    const engine = createKeepAwakeEngine();
+    engine.start();
+    await flush();
+    expect(engine.status.wakeLock).toBe('held');
+
+    // Hidden: the UA drops the lock, and a request while hidden would reject anyway.
+    setVisibility('hidden');
+    first.fireRelease();
+    await flush();
+    expect(engine.status.wakeLock).toBe('idle');
+    expect(request.mock.calls.length).toBe(1);
+
+    setVisibility('visible');
+    document.dispatchEvent(new Event('visibilitychange'));
+    await flush();
+    expect(engine.status.wakeLock).toBe('held');
+    expect(request.mock.calls.length).toBe(2);
+
+    engine.stop();
+  });
+
+  test('always mode runs the video even while a lock is held', async () => {
+    setWakeLock({ request: () => Promise.resolve(fakeSentinel()) });
+    stubPlay(() => Promise.resolve());
+
+    const engine = createKeepAwakeEngine({ videoFallback: 'always' });
+    engine.start();
+    await flush();
+
+    expect(engine.status.wakeLock).toBe('held');
+    expect(engine.status.video).toBe('playing');
+    expect(videosInBody()).toHaveLength(1);
+
+    engine.stop();
+  });
+
+  test('never mode leaves the DOM alone even with no wake lock support', async () => {
+    setWakeLock(undefined);
+    const engine = createKeepAwakeEngine({ videoFallback: 'never' });
+    engine.start();
+    await flush();
+
+    expect(engine.status.active).toBe(false);
+    expect(videosInBody()).toHaveLength(0);
+
+    engine.stop();
+  });
+
+  test('stop() is idempotent and start() after stop() re-acquires', async () => {
+    const request = mock(() => Promise.resolve(fakeSentinel()));
+    setWakeLock({ request });
+
+    const engine = createKeepAwakeEngine();
+    engine.start();
+    await flush();
+    engine.stop();
+    engine.stop();
+    expect(engine.status.active).toBe(false);
+
+    engine.start();
+    await flush();
+    expect(engine.status.wakeLock).toBe('held');
+    expect(request.mock.calls.length).toBe(2);
+    engine.stop();
+  });
+});