@weasel-js/react 1.9.4 → 1.10.1

package/README.md

@@ -7,7 +7,7 @@ a value into a ref prop of either shape. No weasel domain in it.
 
 Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
 scene-graph canvas kit for React. See the
-[API reference](https://orochi235.github.io/weasel/api/).
+[API reference](https://orochi235.github.io/weasel/#pkg/react).
 
 ## Install
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Ref } from 'react';
+import { Ref, RefObject } from 'react';
 
 /**
  * Write `value` into a ref a caller passed in, whichever shape it has: call a
@@ -9,6 +9,39 @@ import { Ref } from 'react';
  */
 declare function assignRef<T>(ref: Ref<T> | undefined, value: T | null): void;
 
+/** Options for `useCanvasFocus`. */
+interface UseCanvasFocusOptions {
+    /** Initial focus state. Default `false` — handles hidden until first click. */
+    initial?: boolean;
+    /** `tabIndex` to set on the focusable element. Default `0` (focusable in
+     *  document tab order). Set to `-1` for programmatic-only focus. */
+    tabIndex?: number;
+}
+/** What `useCanvasFocus` hands back: the focus state, the props that
+ *  maintain it, and a getter for reading it from per-frame code. */
+interface CanvasFocusReturn {
+    /** Live boolean — true when the element has DOM focus. Triggers re-renders
+     *  when the focus state changes (set via React state). */
+    focused: boolean;
+    /** Spread onto the focusable element (e.g. the canvas). Includes
+     *  `tabIndex`, `onFocus`, `onBlur`. */
+    focusProps: {
+        tabIndex: number;
+        onFocus: () => void;
+        onBlur: () => void;
+    };
+    /** Stable getter for the live focused state. Use inside per-frame closures
+     *  like `RenderLayer.draw`, where the layer is constructed once and
+     *  reading `focused` directly would capture the value at construction
+     *  time. The getter always returns the current value. */
+    getFocused: () => boolean;
+    /** Imperative focus / blur. Useful for tests and programmatic control. */
+    setFocused: (next: boolean) => void;
+}
+/** Track DOM focus on the canvas, so chrome that should only show while the
+ *  canvas is focused can be gated on it. */
+declare function useCanvasFocus(options?: UseCanvasFocusOptions): CanvasFocusReturn;
+
 /**
  * A ref holding the `value` of the last **committed** render, for event
  * handlers, frame loops and other code that runs outside render and must not
@@ -19,9 +52,7 @@ declare function assignRef<T>(ref: Ref<T> | undefined, value: T | null): void;
  * interrupted by a more urgent update), and the value that render computed
  * would stay behind for the next event to read. This writes from
  * `useInsertionEffect`, so only a render that commits ever lands, and it lands
- * before any layout effect in that commit runs — a sibling's or a child's
- * `useLayoutEffect`, or a synchronous paint one of them triggers, already sees
- * it.
+ * before any layout effect in that commit runs.
  *
  * Don't read `.current` during render expecting this render's value: until the
  * commit it holds the previous committed one (on mount, this first `value`).
@@ -31,6 +62,83 @@ declare function useLatest<T>(value: T): {
     readonly current: T;
 };
 
+/**
+ * The one place weasel decides whether a frame may run, so that "a loop does no
+ * work nobody can see" holds by construction rather than by every loop author
+ * remembering. Nothing runs while the document is hidden; a loop that names an
+ * element also stops while that element is outside the viewport.
+ *
+ * A request made while suspended is held, not dropped, and re-armed when the
+ * surface comes back — so a loop never needs to poll visibility itself.
+ */
+
+/** What a loop names as its element, resolved every time the gate is consulted
+ *  so a ref filled in after mount still starts the observer. */
+type VisibleRafTarget = RefObject<Element | null> | (() => Element | null);
+/** Options for {@link useVisibleRaf}. */
+interface VisibleRafOptions {
+    /** Also gate on this element's intersection with the viewport. Omit it and
+     *  the loop is gated on document visibility alone. */
+    target?: VisibleRafTarget;
+    /**
+     * Run frames regardless of visibility. The escape hatch for a loop that is
+     * not painting for a viewer — an offscreen recording, an export driving its
+     * own frames. It is the wrong fix for a loop that stalls after a tab switch:
+     * that is a missing `request()`, and setting this hides it.
+     */
+    dangerouslyRunWhenHidden?: boolean;
+    /** Frame clock. Read live, so a test may inject one after mount. */
+    requestFrame?: (cb: FrameRequestCallback) => number;
+    cancelFrame?: (handle: number) => void;
+    /**
+     * Runs once when the loop leaves suspension, before the frame that follows
+     * it. Where a loop that measures elapsed time drops the interval it spent
+     * suspended — without it, an hour hidden arrives as one hour-long frame.
+     */
+    onResume?: () => void;
+}
+/** The handle {@link useVisibleRaf} returns. Nothing runs until `request()` is called. */
+interface VisibleRaf {
+    /** Ask for a frame. Idempotent while one is outstanding, and held rather than
+     *  dropped while suspended. Identity is stable for the component's lifetime. */
+    request(): void;
+    /** Drop the outstanding request, held or scheduled. */
+    cancel(): void;
+    /** Whether a frame would run right now. */
+    isVisible(): boolean;
+}
+/**
+ * @param frame Runs on the frame, with the timestamp the clock supplied and the
+ *   loop's own handle. A continuous loop calls `loop.request()` from inside it;
+ *   a one-shot loop does not.
+ */
+declare function useVisibleRaf(frame: (time: number, loop: VisibleRaf) => void, options?: VisibleRafOptions): VisibleRaf;
+
+/** Options for {@link useFrameClock}. */
+interface FrameClockOptions {
+    /** Stop the clock where it is. Time spent paused is not counted. */
+    paused?: boolean;
+    /** What `seconds()` reads before any frame has run. Read once, at mount. */
+    start?: number;
+    /** Frame source, as on `useVisibleRaf`. */
+    requestFrame?: (cb: FrameRequestCallback) => number;
+    cancelFrame?: (handle: number) => void;
+}
+/** A clock a paint reads without rendering. It has `subscribe`, so a render
+ *  layer can name it as its redraw source. */
+interface FrameClock {
+    /** Seconds of frames that ran: time hidden, paused, or with no subscriber is left out. */
+    seconds(): number;
+    /** Called once per frame. The clock runs while it has a subscriber. */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Elapsed time for something that animates in its paint and nowhere else: a
+ * shader uniform, a procedural layer. Each frame notifies the subscribers and
+ * changes no React state, so the component that owns it does not re-render.
+ */
+declare function useFrameClock(options?: FrameClockOptions): FrameClock;
+
 /**
  * `value`, or the one the last committed render returned when `same` says the
  * two are equal — so a caller rebuilding an equivalent object every render
@@ -41,4 +149,4 @@ declare function useStableByContent<T>(value: T, same: (a: T, b: T) => boolean):
 /** Same length, and the same element at every index. */
 declare function sameList<T>(a: readonly T[], b: readonly T[]): boolean;
 
-export { assignRef, sameList, useLatest, useStableByContent };
+export { type CanvasFocusReturn, type FrameClock, type FrameClockOptions, type UseCanvasFocusOptions, type VisibleRaf, type VisibleRafOptions, type VisibleRafTarget, assignRef, sameList, useCanvasFocus, useFrameClock, useLatest, useStableByContent, useVisibleRaf };

package/dist/index.js

@@ -1,10 +1,41 @@
-import { useRef, useInsertionEffect } from 'react';
+import { useState, useRef, useCallback, useMemo, useInsertionEffect, useLayoutEffect, useEffect } from 'react';
+import { createEmitter } from '@weasel-js/registry';
 
 // src/assignRef.ts
 function assignRef(ref, value) {
   if (typeof ref === "function") ref(value);
   else if (ref) ref.current = value;
 }
+function useCanvasFocus(options = {}) {
+  const { initial = false, tabIndex = 0 } = options;
+  const [focused, setFocusedState] = useState(initial);
+  const focusedRef = useRef(initial);
+  const onFocus = useCallback(() => {
+    if (!focusedRef.current) {
+      focusedRef.current = true;
+      setFocusedState(true);
+    }
+  }, []);
+  const onBlur = useCallback(() => {
+    if (focusedRef.current) {
+      focusedRef.current = false;
+      setFocusedState(false);
+    }
+  }, []);
+  const getFocused = useCallback(() => focusedRef.current, []);
+  const setFocused = useCallback((next) => {
+    if (focusedRef.current === next) return;
+    focusedRef.current = next;
+    setFocusedState(next);
+  }, []);
+  const focusProps = useMemo(() => ({ tabIndex, onFocus, onBlur }), [tabIndex, onFocus, onBlur]);
+  return {
+    focused,
+    focusProps,
+    getFocused,
+    setFocused
+  };
+}
 function useLatest(value) {
   const ref = useRef(value);
   useInsertionEffect(() => {
@@ -12,6 +43,138 @@ function useLatest(value) {
   });
   return ref;
 }
+var documentHidden = () => typeof document !== "undefined" && document.hidden;
+var resolveTarget = (target) => typeof target === "function" ? target() : target?.current ?? null;
+function useVisibleRaf(frame, options = {}) {
+  const frameRef = useLatest(frame);
+  const optsRef = useLatest(options);
+  const rafRef = useRef(null);
+  const pendingRef = useRef(false);
+  const suspendedRef = useRef(false);
+  const aliveRef = useRef(true);
+  const intersectingRef = useRef(true);
+  const observerRef = useRef(null);
+  const observedRef = useRef(null);
+  const handleRef = useRef(null);
+  const isVisible = useCallback(
+    () => optsRef.current.dangerouslyRunWhenHidden === true || !documentHidden() && intersectingRef.current,
+    [optsRef]
+  );
+  const cancelRaf = useCallback(() => {
+    if (rafRef.current === null) return;
+    (optsRef.current.cancelFrame ?? cancelAnimationFrame)(rafRef.current);
+    rafRef.current = null;
+  }, [optsRef]);
+  const scheduleRaf = useCallback(() => {
+    if (rafRef.current !== null || !aliveRef.current) return;
+    rafRef.current = (optsRef.current.requestFrame ?? requestAnimationFrame)((time) => {
+      rafRef.current = null;
+      if (!aliveRef.current || !pendingRef.current || !isVisible()) return;
+      pendingRef.current = false;
+      frameRef.current(time, handleRef.current);
+    });
+  }, [frameRef, isVisible, optsRef]);
+  const syncObserver = useCallback(() => {
+    const io = observerRef.current;
+    if (!io) return;
+    const el = resolveTarget(optsRef.current.target);
+    if (el === observedRef.current) return;
+    if (observedRef.current) io.unobserve(observedRef.current);
+    observedRef.current = el;
+    intersectingRef.current = true;
+    if (el) io.observe(el);
+  }, [optsRef]);
+  const syncGate = useCallback(() => {
+    if (!isVisible()) {
+      if (suspendedRef.current) return;
+      suspendedRef.current = true;
+      cancelRaf();
+      return;
+    }
+    if (!suspendedRef.current) return;
+    suspendedRef.current = false;
+    if (!aliveRef.current) return;
+    optsRef.current.onResume?.();
+    if (pendingRef.current) scheduleRaf();
+  }, [cancelRaf, isVisible, optsRef, scheduleRaf]);
+  const request = useCallback(() => {
+    if (!aliveRef.current) return;
+    syncObserver();
+    pendingRef.current = true;
+    if (!isVisible()) {
+      suspendedRef.current = true;
+      return;
+    }
+    scheduleRaf();
+  }, [isVisible, scheduleRaf, syncObserver]);
+  const cancel = useCallback(() => {
+    pendingRef.current = false;
+    cancelRaf();
+  }, [cancelRaf]);
+  useLayoutEffect(() => {
+    aliveRef.current = true;
+    document.addEventListener("visibilitychange", syncGate);
+    if (typeof IntersectionObserver !== "undefined") {
+      observerRef.current = new IntersectionObserver((entries) => {
+        intersectingRef.current = entries.some((e) => e.isIntersecting);
+        syncGate();
+      });
+      syncObserver();
+    }
+    return () => {
+      aliveRef.current = false;
+      document.removeEventListener("visibilitychange", syncGate);
+      observerRef.current?.disconnect();
+      observerRef.current = null;
+      observedRef.current = null;
+      intersectingRef.current = true;
+      cancelRaf();
+      pendingRef.current = false;
+      suspendedRef.current = false;
+    };
+  }, [cancelRaf, syncGate, syncObserver]);
+  const handle = useMemo(() => ({ request, cancel, isVisible }), [request, cancel, isVisible]);
+  useLayoutEffect(() => {
+    handleRef.current = handle;
+  }, [handle]);
+  return handle;
+}
+function useFrameClock(options = {}) {
+  const { paused = false, requestFrame, cancelFrame } = options;
+  const elapsed = useRef(options.start ?? 0);
+  const last = useRef(null);
+  const [ticked] = useState(() => createEmitter());
+  const pausedRef = useLatest(paused);
+  const loop = useVisibleRaf(
+    (now, loop2) => {
+      if (last.current !== null) elapsed.current += (now - last.current) / 1e3;
+      last.current = now;
+      ticked.emit();
+      if (ticked.size > 0 && !pausedRef.current) loop2.request();
+    },
+    { requestFrame, cancelFrame, onResume: () => {
+      last.current = null;
+    } }
+  );
+  useEffect(() => {
+    if (paused) return;
+    last.current = null;
+    if (ticked.size > 0) loop.request();
+    return () => loop.cancel();
+  }, [paused, loop, ticked]);
+  return useMemo(() => ({
+    seconds: () => elapsed.current,
+    subscribe(listener) {
+      if (ticked.size === 0) last.current = null;
+      const off = ticked.subscribe(listener);
+      if (!pausedRef.current) loop.request();
+      return () => {
+        off();
+        if (ticked.size === 0) loop.cancel();
+      };
+    }
+  }), [loop, pausedRef, ticked]);
+}
 function useStableByContent(value, same) {
   const held = useRef(value);
   const out = held.current === value || same(held.current, value) ? held.current : value;
@@ -24,6 +187,6 @@ function sameList(a, b) {
   return a.length === b.length && a.every((t, i) => t === b[i]);
 }
 
-export { assignRef, sameList, useLatest, useStableByContent };
+export { assignRef, sameList, useCanvasFocus, useFrameClock, useLatest, useStableByContent, useVisibleRaf };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/assignRef.ts","../src/useLatest.ts","../src/useStableByContent.ts"],"names":["useRef","useInsertionEffect"],"mappings":";;;AASO,SAAS,SAAA,CAAa,KAAyB,KAAA,EAAuB;AAC3E,EAAA,IAAI,OAAO,GAAA,KAAQ,UAAA,EAAY,GAAA,CAAI,KAAK,CAAA;AAAA,OAAA,IAC/B,GAAA,EAAM,GAAA,CAA8B,OAAA,GAAU,KAAA;AACzD;ACQO,SAAS,UAAa,KAAA,EAAmC;AAC9D,EAAA,MAAM,GAAA,GAAM,OAAO,KAAK,CAAA;AACxB,EAAA,kBAAA,CAAmB,MAAM;AACvB,IAAA,GAAA,CAAI,OAAA,GAAU,KAAA;AAAA,EAChB,CAAC,CAAA;AACD,EAAA,OAAO,GAAA;AACT;AClBO,SAAS,kBAAA,CAAsB,OAAU,IAAA,EAAkC;AAChF,EAAA,MAAM,IAAA,GAAOA,OAAO,KAAK,CAAA;AACzB,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,KAAY,KAAA,IAAS,IAAA,CAAK,KAAK,OAAA,EAAS,KAAK,CAAA,GAAI,IAAA,CAAK,OAAA,GAAU,KAAA;AACjF,EAAAC,mBAAmB,MAAM;AACvB,IAAA,IAAA,CAAK,OAAA,GAAU,GAAA;AAAA,EACjB,CAAC,CAAA;AACD,EAAA,OAAO,GAAA;AACT;AAGO,SAAS,QAAA,CAAY,GAAiB,CAAA,EAA0B;AACrE,EAAA,OAAO,CAAA,CAAE,MAAA,KAAW,CAAA,CAAE,MAAA,IAAU,CAAA,CAAE,KAAA,CAAM,CAAC,CAAA,EAAG,CAAA,KAAM,CAAA,KAAM,CAAA,CAAE,CAAC,CAAC,CAAA;AAC9D","file":"index.js","sourcesContent":["import type { Ref } from 'react';\n\n/**\n * Write `value` into a ref a caller passed in, whichever shape it has: call a\n * callback ref, set an object ref's `current`, ignore `null` or `undefined`.\n *\n * For a component that keeps the element (or handle) for itself and also\n * forwards it to a ref prop — call this from the component's own callback ref.\n */\nexport function assignRef<T>(ref: Ref<T> | undefined, value: T | null): void {\n  if (typeof ref === 'function') ref(value);\n  else if (ref) (ref as { current: T | null }).current = value;\n}\n","import { useInsertionEffect, useRef } from 'react';\n\n/**\n * A ref holding the `value` of the last **committed** render, for event\n * handlers, frame loops and other code that runs outside render and must not\n * re-subscribe every time `value` changes.\n *\n * Writing `ref.current = value` in a render body is not the same thing: React\n * may start a render and throw it away (a transition that suspends, a render\n * interrupted by a more urgent update), and the value that render computed\n * would stay behind for the next event to read. This writes from\n * `useInsertionEffect`, so only a render that commits ever lands, and it lands\n * before any layout effect in that commit runs — a sibling's or a child's\n * `useLayoutEffect`, or a synchronous paint one of them triggers, already sees\n * it.\n *\n * Don't read `.current` during render expecting this render's value: until the\n * commit it holds the previous committed one (on mount, this first `value`).\n * Render code should use `value` itself.\n */\nexport function useLatest<T>(value: T): { readonly current: T } {\n  const ref = useRef(value);\n  useInsertionEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n","import { useInsertionEffect, useRef } from 'react';\n\n/**\n * `value`, or the one the last committed render returned when `same` says the\n * two are equal — so a caller rebuilding an equivalent object every render\n * hands its readers one identity. Compared against the committed value only:\n * a render React throws away never becomes the one the next render keeps.\n */\nexport function useStableByContent<T>(value: T, same: (a: T, b: T) => boolean): T {\n  const held = useRef(value);\n  const out = held.current === value || same(held.current, value) ? held.current : value;\n  useInsertionEffect(() => {\n    held.current = out;\n  });\n  return out;\n}\n\n/** Same length, and the same element at every index. */\nexport function sameList<T>(a: readonly T[], b: readonly T[]): boolean {\n  return a.length === b.length && a.every((t, i) => t === b[i]);\n}\n"]}
+{"version":3,"sources":["../src/assignRef.ts","../src/useCanvasFocus.ts","../src/useLatest.ts","../src/useVisibleRaf.ts","../src/useFrameClock.ts","../src/useStableByContent.ts"],"names":["useRef","useCallback","useMemo","useState","loop","useInsertionEffect"],"mappings":"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","file":"index.js","sourcesContent":["import type { Ref } from 'react';\n\n/**\n * Write `value` into a ref a caller passed in, whichever shape it has: call a\n * callback ref, set an object ref's `current`, ignore `null` or `undefined`.\n *\n * For a component that keeps the element (or handle) for itself and also\n * forwards it to a ref prop — call this from the component's own callback ref.\n */\nexport function assignRef<T>(ref: Ref<T> | undefined, value: T | null): void {\n  if (typeof ref === 'function') ref(value);\n  else if (ref) (ref as { current: T | null }).current = value;\n}\n","/**\n * Track DOM focus on a canvas (or any focusable host element). Returns the\n * live `focused` boolean, props to spread onto the focusable element, and a\n * stable `getFocused()` getter for use inside per-frame closures (notably\n * `RenderLayer.draw`, which is constructed once but called every frame).\n *\n * No Canvas/SceneCanvas integration. Consumers compose the hook with core's\n * `gateLayer` (or their own gate) to hide affordances when blurred.\n */\nimport { useCallback, useMemo, useRef, useState } from 'react';\n\n/** Options for `useCanvasFocus`. */\nexport interface UseCanvasFocusOptions {\n  /** Initial focus state. Default `false` — handles hidden until first click. */\n  initial?: boolean;\n  /** `tabIndex` to set on the focusable element. Default `0` (focusable in\n   *  document tab order). Set to `-1` for programmatic-only focus. */\n  tabIndex?: number;\n}\n\n/** What `useCanvasFocus` hands back: the focus state, the props that\n *  maintain it, and a getter for reading it from per-frame code. */\nexport interface CanvasFocusReturn {\n  /** Live boolean — true when the element has DOM focus. Triggers re-renders\n   *  when the focus state changes (set via React state). */\n  focused: boolean;\n  /** Spread onto the focusable element (e.g. the canvas). Includes\n   *  `tabIndex`, `onFocus`, `onBlur`. */\n  focusProps: {\n    tabIndex: number;\n    onFocus: () => void;\n    onBlur: () => void;\n  };\n  /** Stable getter for the live focused state. Use inside per-frame closures\n   *  like `RenderLayer.draw`, where the layer is constructed once and\n   *  reading `focused` directly would capture the value at construction\n   *  time. The getter always returns the current value. */\n  getFocused: () => boolean;\n  /** Imperative focus / blur. Useful for tests and programmatic control. */\n  setFocused: (next: boolean) => void;\n}\n\n/** Track DOM focus on the canvas, so chrome that should only show while the\n *  canvas is focused can be gated on it. */\nexport function useCanvasFocus(options: UseCanvasFocusOptions = {}): CanvasFocusReturn {\n  const { initial = false, tabIndex = 0 } = options;\n  const [focused, setFocusedState] = useState<boolean>(initial);\n  // Every state change goes through a handler below that writes this first.\n  const focusedRef = useRef<boolean>(initial);\n\n  const onFocus = useCallback(() => {\n    if (!focusedRef.current) {\n      focusedRef.current = true;\n      setFocusedState(true);\n    }\n  }, []);\n  const onBlur = useCallback(() => {\n    if (focusedRef.current) {\n      focusedRef.current = false;\n      setFocusedState(false);\n    }\n  }, []);\n  const getFocused = useCallback(() => focusedRef.current, []);\n  const setFocused = useCallback((next: boolean) => {\n    if (focusedRef.current === next) return;\n    focusedRef.current = next;\n    setFocusedState(next);\n  }, []);\n\n  // Stable until tabIndex changes, so it can be spread onto memoized elements\n  // without retriggering downstream effects.\n  const focusProps = useMemo(() => ({ tabIndex, onFocus, onBlur }), [tabIndex, onFocus, onBlur]);\n\n  return {\n    focused,\n    focusProps,\n    getFocused,\n    setFocused,\n  };\n}\n","import { useInsertionEffect, useRef } from 'react';\n\n/**\n * A ref holding the `value` of the last **committed** render, for event\n * handlers, frame loops and other code that runs outside render and must not\n * re-subscribe every time `value` changes.\n *\n * Writing `ref.current = value` in a render body is not the same thing: React\n * may start a render and throw it away (a transition that suspends, a render\n * interrupted by a more urgent update), and the value that render computed\n * would stay behind for the next event to read. This writes from\n * `useInsertionEffect`, so only a render that commits ever lands, and it lands\n * before any layout effect in that commit runs.\n *\n * Don't read `.current` during render expecting this render's value: until the\n * commit it holds the previous committed one (on mount, this first `value`).\n * Render code should use `value` itself.\n */\nexport function useLatest<T>(value: T): { readonly current: T } {\n  const ref = useRef(value);\n  useInsertionEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n","/**\n * The one place weasel decides whether a frame may run, so that \"a loop does no\n * work nobody can see\" holds by construction rather than by every loop author\n * remembering. Nothing runs while the document is hidden; a loop that names an\n * element also stops while that element is outside the viewport.\n *\n * A request made while suspended is held, not dropped, and re-armed when the\n * surface comes back — so a loop never needs to poll visibility itself.\n */\n\nimport { type RefObject, useCallback, useLayoutEffect, useMemo, useRef } from 'react';\nimport { useLatest } from './useLatest';\n\n/** What a loop names as its element, resolved every time the gate is consulted\n *  so a ref filled in after mount still starts the observer. */\nexport type VisibleRafTarget = RefObject<Element | null> | (() => Element | null);\n\n/** Options for {@link useVisibleRaf}. */\nexport interface VisibleRafOptions {\n  /** Also gate on this element's intersection with the viewport. Omit it and\n   *  the loop is gated on document visibility alone. */\n  target?: VisibleRafTarget;\n  /**\n   * Run frames regardless of visibility. The escape hatch for a loop that is\n   * not painting for a viewer — an offscreen recording, an export driving its\n   * own frames. It is the wrong fix for a loop that stalls after a tab switch:\n   * that is a missing `request()`, and setting this hides it.\n   */\n  dangerouslyRunWhenHidden?: boolean;\n  /** Frame clock. Read live, so a test may inject one after mount. */\n  requestFrame?: (cb: FrameRequestCallback) => number;\n  cancelFrame?: (handle: number) => void;\n  /**\n   * Runs once when the loop leaves suspension, before the frame that follows\n   * it. Where a loop that measures elapsed time drops the interval it spent\n   * suspended — without it, an hour hidden arrives as one hour-long frame.\n   */\n  onResume?: () => void;\n}\n\n/** The handle {@link useVisibleRaf} returns. Nothing runs until `request()` is called. */\nexport interface VisibleRaf {\n  /** Ask for a frame. Idempotent while one is outstanding, and held rather than\n   *  dropped while suspended. Identity is stable for the component's lifetime. */\n  request(): void;\n  /** Drop the outstanding request, held or scheduled. */\n  cancel(): void;\n  /** Whether a frame would run right now. */\n  isVisible(): boolean;\n}\n\nconst documentHidden = (): boolean => typeof document !== 'undefined' && document.hidden;\n\nconst resolveTarget = (target: VisibleRafTarget | undefined): Element | null =>\n  typeof target === 'function' ? target() : (target?.current ?? null);\n\n/**\n * @param frame Runs on the frame, with the timestamp the clock supplied and the\n *   loop's own handle. A continuous loop calls `loop.request()` from inside it;\n *   a one-shot loop does not.\n */\nexport function useVisibleRaf(\n  frame: (time: number, loop: VisibleRaf) => void,\n  options: VisibleRafOptions = {},\n): VisibleRaf {\n  const frameRef = useLatest(frame);\n  const optsRef = useLatest(options);\n\n  const rafRef = useRef<number | null>(null);\n  const pendingRef = useRef(false);\n  const suspendedRef = useRef(false);\n  const aliveRef = useRef(true);\n  const intersectingRef = useRef(true);\n  const observerRef = useRef<IntersectionObserver | null>(null);\n  const observedRef = useRef<Element | null>(null);\n  const handleRef = useRef<VisibleRaf | null>(null);\n\n  const isVisible = useCallback(\n    (): boolean =>\n      optsRef.current.dangerouslyRunWhenHidden === true ||\n      (!documentHidden() && intersectingRef.current),\n    [optsRef],\n  );\n\n  const cancelRaf = useCallback(() => {\n    if (rafRef.current === null) return;\n    (optsRef.current.cancelFrame ?? cancelAnimationFrame)(rafRef.current);\n    rafRef.current = null;\n  }, [optsRef]);\n\n  const scheduleRaf = useCallback(() => {\n    if (rafRef.current !== null || !aliveRef.current) return;\n    rafRef.current = (optsRef.current.requestFrame ?? requestAnimationFrame)((time) => {\n      // Released before the frame runs, so a `request()` issued from inside it\n      // schedules the next one instead of being swallowed.\n      rafRef.current = null;\n      if (!aliveRef.current || !pendingRef.current || !isVisible()) return;\n      pendingRef.current = false;\n      frameRef.current(time, handleRef.current!);\n    });\n  }, [frameRef, isVisible, optsRef]);\n\n  /** Attaches the observer once the named element exists. Ref callbacks and\n   *  lazily-mounted hosts fill their refs after this hook's effect has run. */\n  const syncObserver = useCallback(() => {\n    const io = observerRef.current;\n    if (!io) return;\n    const el = resolveTarget(optsRef.current.target);\n    if (el === observedRef.current) return;\n    if (observedRef.current) io.unobserve(observedRef.current);\n    observedRef.current = el;\n    // An element that has gone away stops gating rather than stopping the loop.\n    intersectingRef.current = true;\n    if (el) io.observe(el);\n  }, [optsRef]);\n\n  /** Re-reads the gate after something that could have changed it. Suspending\n   *  drops the outstanding frame but keeps the request; resuming hands the\n   *  loop its rebase before re-arming. */\n  const syncGate = useCallback(() => {\n    if (!isVisible()) {\n      if (suspendedRef.current) return;\n      suspendedRef.current = true;\n      cancelRaf();\n      return;\n    }\n    if (!suspendedRef.current) return;\n    suspendedRef.current = false;\n    if (!aliveRef.current) return;\n    optsRef.current.onResume?.();\n    if (pendingRef.current) scheduleRaf();\n  }, [cancelRaf, isVisible, optsRef, scheduleRaf]);\n\n  const request = useCallback(() => {\n    if (!aliveRef.current) return;\n    syncObserver();\n    pendingRef.current = true;\n    if (!isVisible()) {\n      suspendedRef.current = true;\n      return;\n    }\n    scheduleRaf();\n  }, [isVisible, scheduleRaf, syncObserver]);\n\n  const cancel = useCallback(() => {\n    pendingRef.current = false;\n    cancelRaf();\n  }, [cancelRaf]);\n\n  // Re-armed in setup because the refs survive StrictMode's simulated remount, and\n  // a layout effect so the arming precedes the host's own layout effects — a loop\n  // driven from one of those would otherwise be declined on the second mount.\n  useLayoutEffect(() => {\n    aliveRef.current = true;\n    document.addEventListener('visibilitychange', syncGate);\n    if (typeof IntersectionObserver !== 'undefined') {\n      observerRef.current = new IntersectionObserver((entries) => {\n        intersectingRef.current = entries.some((e) => e.isIntersecting);\n        syncGate();\n      });\n      syncObserver();\n    }\n    return () => {\n      aliveRef.current = false;\n      document.removeEventListener('visibilitychange', syncGate);\n      observerRef.current?.disconnect();\n      observerRef.current = null;\n      observedRef.current = null;\n      intersectingRef.current = true;\n      cancelRaf();\n      pendingRef.current = false;\n      suspendedRef.current = false;\n    };\n  }, [cancelRaf, syncGate, syncObserver]);\n\n  // Stable identity: `requestRedraw` and friends outlive the render that made\n  // them, and consumers capture the handle.\n  const handle = useMemo(() => ({ request, cancel, isVisible }), [request, cancel, isVisible]);\n  useLayoutEffect(() => { handleRef.current = handle; }, [handle]);\n  return handle;\n}\n","import { createEmitter } from '@weasel-js/registry';\nimport { useEffect, useMemo, useRef, useState } from 'react';\nimport { useLatest } from './useLatest';\nimport { useVisibleRaf } from './useVisibleRaf';\n\n/** Options for {@link useFrameClock}. */\nexport interface FrameClockOptions {\n  /** Stop the clock where it is. Time spent paused is not counted. */\n  paused?: boolean;\n  /** What `seconds()` reads before any frame has run. Read once, at mount. */\n  start?: number;\n  /** Frame source, as on `useVisibleRaf`. */\n  requestFrame?: (cb: FrameRequestCallback) => number;\n  cancelFrame?: (handle: number) => void;\n}\n\n/** A clock a paint reads without rendering. It has `subscribe`, so a render\n *  layer can name it as its redraw source. */\nexport interface FrameClock {\n  /** Seconds of frames that ran: time hidden, paused, or with no subscriber is left out. */\n  seconds(): number;\n  /** Called once per frame. The clock runs while it has a subscriber. */\n  subscribe(listener: () => void): () => void;\n}\n\n/**\n * Elapsed time for something that animates in its paint and nowhere else: a\n * shader uniform, a procedural layer. Each frame notifies the subscribers and\n * changes no React state, so the component that owns it does not re-render.\n */\nexport function useFrameClock(options: FrameClockOptions = {}): FrameClock {\n  const { paused = false, requestFrame, cancelFrame } = options;\n  const elapsed = useRef(options.start ?? 0);\n  const last = useRef<number | null>(null);\n  const [ticked] = useState(() => createEmitter());\n  const pausedRef = useLatest(paused);\n\n  const loop = useVisibleRaf(\n    (now, loop) => {\n      if (last.current !== null) elapsed.current += (now - last.current) / 1000;\n      last.current = now;\n      ticked.emit();\n      if (ticked.size > 0 && !pausedRef.current) loop.request();\n    },\n    { requestFrame, cancelFrame, onResume: () => { last.current = null; } },\n  );\n\n  useEffect(() => {\n    if (paused) return;\n    last.current = null;\n    if (ticked.size > 0) loop.request();\n    return () => loop.cancel();\n  }, [paused, loop, ticked]);\n\n  return useMemo<FrameClock>(() => ({\n    seconds: () => elapsed.current,\n    subscribe(listener) {\n      if (ticked.size === 0) last.current = null;\n      const off = ticked.subscribe(listener);\n      if (!pausedRef.current) loop.request();\n      return () => {\n        off();\n        if (ticked.size === 0) loop.cancel();\n      };\n    },\n  }), [loop, pausedRef, ticked]);\n}\n","import { useInsertionEffect, useRef } from 'react';\n\n/**\n * `value`, or the one the last committed render returned when `same` says the\n * two are equal — so a caller rebuilding an equivalent object every render\n * hands its readers one identity. Compared against the committed value only:\n * a render React throws away never becomes the one the next render keeps.\n */\nexport function useStableByContent<T>(value: T, same: (a: T, b: T) => boolean): T {\n  const held = useRef(value);\n  const out = held.current === value || same(held.current, value) ? held.current : value;\n  useInsertionEffect(() => {\n    held.current = out;\n  });\n  return out;\n}\n\n/** Same length, and the same element at every index. */\nexport function sameList<T>(a: readonly T[], b: readonly T[]): boolean {\n  return a.length === b.length && a.every((t, i) => t === b[i]);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/react",
-  "version": "1.9.4",
+  "version": "1.10.1",
   "description": "Generic React hooks the weasel packages share: a committed-value ref and content-stable identity. No weasel domain in it.",
   "license": "MIT",
   "type": "module",
@@ -21,6 +21,9 @@
   "peerDependenciesMeta": {
     "react": { "optional": true }
   },
+  "dependencies": {
+    "@weasel-js/registry": "1.10.1"
+  },
   "author": "orochi235",
   "homepage": "https://orochi235.github.io/weasel/",
   "repository": {