phase 0.0.1-alpha.1 → 0.0.2

package/dist/react.d.ts

@@ -0,0 +1,702 @@
+import { D as FrameState, T as SightReason, b as LifecycleReducedMotion, c as DegradedReason, d as LoopPhase, f as LoopReason, m as ReducedMotionBehavior, p as Quality, r as RenderPhase, s as DegradedBehavior, t as IdleOptions, v as LifecyclePhase, w as SightPhase, y as LifecycleReason } from "./index-D3epuj2x.js";
+import { ComponentProps, JSX, ReactNode, Ref, RefObject } from "react";
+
+//#region src/react/use-synced-ref/index.d.ts
+/**
+ * Ref whose `.current` is always the latest value, updated synchronously on
+ * every render. Readable from any callback or effect without triggering re-render.
+ *
+ * @example
+ * const propsRef = useSyncedRef(props);
+ * useEffect(() => {
+ *   // propsRef.current is always fresh
+ * }, []);
+ */
+declare function useSyncedRef<T>(value: T): RefObject<T>;
+//#endregion
+//#region src/react/use-stable-callback/index.d.ts
+/**
+ * Returns a function with **stable identity** that always calls the latest
+ * version of `callback`. Safe in deps arrays and as a prop to `memo()`'d children.
+ *
+ * @example
+ * const handleClick = useStableCallback((e: MouseEvent) => {
+ *   console.log(latestValue); // always fresh
+ * });
+ */
+declare function useStableCallback<Args extends unknown[], R>(callback: (...args: Args) => R): (...args: Args) => R;
+//#endregion
+//#region src/react/use-loop/index.d.ts
+/**
+ * Per-frame loop callback. Receives the current frame state. Write to refs or
+ * DOM directly. Never call React `setState` here (60 calls/sec = 60
+ * re-renders/sec).
+ */
+type LoopTickFn = (frame: FrameState) => void;
+interface UseLoopOptions<T extends Element = HTMLDivElement> {
+  /**
+   * Element to observe. Optional. When omitted, attach the returned `ref`.
+   * Pass your own ref to share it or attach it elsewhere.
+   */
+  ref?: RefObject<T | null>;
+  /**
+   * Called every frame. Write to refs or DOM directly. Never call React
+   * `setState` here (60 calls/sec = 60 re-renders/sec).
+   */
+  onTick: LoopTickFn;
+  fps?: number;
+  enabled?: boolean;
+  reducedMotion?: ReducedMotionBehavior;
+  /** Behavior when quality degrades (window blur, frame-budget). Default `'throttle'`. */
+  degraded?: DegradedBehavior;
+  /** FPS cap when `degraded` is `'throttle'`. Default `30`. */
+  degradedFps?: number;
+  intersectionOptions?: IntersectionObserverInit;
+}
+interface UseLoopResult<T extends Element = HTMLDivElement> {
+  /** Attach to the element you want to animate. */
+  ref: RefObject<T | null>;
+  phase: LoopPhase;
+  phaseReason: LoopReason;
+  quality: Quality;
+  qualityReason: DegradedReason | undefined;
+}
+/**
+ * Ref-based animation loop that never triggers re-renders from the frame loop.
+ *
+ * @example
+ * const { ref, phase } = useLoop({
+ *   onTick: (frame) => {
+ *     ref.current.style.transform = `translateX(${frame.elapsed * 0.1}px)`;
+ *   },
+ * });
+ * return <div ref={ref} />;
+ */
+declare function useLoop<T extends Element = HTMLDivElement>(options: UseLoopOptions<T>): UseLoopResult<T>;
+//#endregion
+//#region src/react/use-lifecycle/index.d.ts
+interface UseLifecycleOptions<T extends Element = HTMLDivElement> {
+  /**
+   * Element whose visibility gates the lifecycle. Optional. When omitted, attach
+   * the returned `ref`.
+   */
+  ref?: RefObject<T | null>;
+  /** Whether reduced motion pauses the lifecycle. Default `'pause'`. */
+  reducedMotion?: LifecycleReducedMotion;
+  /** Manually pause regardless of visibility (e.g. a panel opened over the animation). */
+  paused?: boolean;
+  /** When `false`, the lifecycle is torn down and reports `idle`. Default `true`. */
+  enabled?: boolean;
+  intersectionOptions?: IntersectionObserverInit;
+  /**
+   * Synchronous callback fired in the observer/MQL callback, before React
+   * schedules a render. Use to post messages to a worker or update a ref
+   * without waiting for the React commit.
+   */
+  onPhaseChange?: (phase: LifecyclePhase, reason: LifecycleReason) => void;
+}
+interface UseLifecycleResult<T extends Element = HTMLDivElement> {
+  /** Attach to the element whose visibility should gate your loop. */
+  ref: RefObject<T | null>;
+  phase: LifecyclePhase;
+  phaseReason: LifecycleReason;
+  /** Convenience: `phase === 'active'`. Drive your own render loop off this. */
+  isActive: boolean;
+}
+/**
+ * React binding for `createLifecycle`. The activation signal for loops you own.
+ *
+ * Returns `active` / `paused` so a consumer-owned render loop (WebGL, three.js, a
+ * Web Worker) can pause when off-screen or under reduced motion. When `phase`
+ * should drive the loop for you, use `useLoop` or `useCanvas` instead.
+ *
+ * @example
+ * const { ref, isActive } = useLifecycle();
+ * useEffect(() => {
+ *   if (!isActive) return;
+ *   const id = requestAnimationFrame(function render() {
+ *     renderer.render();
+ *     requestAnimationFrame(render);
+ *   });
+ *   return () => cancelAnimationFrame(id);
+ * }, [isActive]);
+ * return <canvas ref={ref} />;
+ */
+declare function useLifecycle<T extends Element = HTMLDivElement>(options?: UseLifecycleOptions<T>): UseLifecycleResult<T>;
+//#endregion
+//#region src/react/use-device-pixel-ratio/index.d.ts
+/**
+ * Reactive devicePixelRatio that updates when the user moves the window
+ * between monitors with different DPR values.
+ *
+ * Returns `1` during SSR and initial hydration, then the live value.
+ */
+declare function useDevicePixelRatio(): number;
+//#endregion
+//#region src/react/use-media/index.d.ts
+/**
+ * Subscribe to a media query via the shared MQL pool.
+ *
+ * Returns `false` during SSR and initial hydration render,
+ * then the live value from the first `useEffect`.
+ *
+ * @example
+ * const isNarrow = useMediaQuery('(max-width: 600px)');
+ */
+declare function useMediaQuery(query: string): boolean;
+//#endregion
+//#region src/react/use-reduced-motion/index.d.ts
+/**
+ * Reactive boolean that tracks the user's `prefers-reduced-motion` OS setting.
+ *
+ * Returns `false` during SSR and initial hydration, then the live value.
+ * Re-renders only when the preference changes.
+ */
+declare function usePrefersReducedMotion(): boolean;
+//#endregion
+//#region src/react/use-sight/index.d.ts
+type SightCallback = (phase: SightPhase, phaseReason: SightReason) => void;
+interface UseSightOptions<T extends Element = HTMLDivElement> extends IntersectionObserverInit {
+  /**
+   * Element to observe. Optional. When omitted, attach the returned `ref`.
+   */
+  ref?: RefObject<T | null>;
+  /** `'continuous'` keeps observing. `'once'` freezes at `'visible'` after first intersection. */
+  observe?: 'continuous' | 'once';
+  /**
+   * Called on every visibility transition. When provided, `phase` and
+   * `phaseReason` stay at initial values and no re-renders occur.
+   */
+  onVisibilityChange?: SightCallback;
+}
+interface UseSightReactiveResult<T extends Element = HTMLDivElement> {
+  ref: RefObject<T | null>;
+  phase: SightPhase;
+  phaseReason: SightReason;
+  /** Visibility phase via ref. Always current, never triggers re-render. */
+  phaseRef: RefObject<SightPhase>;
+  /** Phase reason via ref. Always current, never triggers re-render. */
+  phaseReasonRef: RefObject<SightReason>;
+}
+interface UseSightTransientResult<T extends Element = HTMLDivElement> {
+  ref: RefObject<T | null>;
+  /** Visibility phase via ref. Always current, never triggers re-render. */
+  phaseRef: RefObject<SightPhase>;
+  /** Phase reason via ref. Always current, never triggers re-render. */
+  phaseReasonRef: RefObject<SightReason>;
+}
+/** @deprecated Use `UseSightReactiveResult` or `UseSightTransientResult`. */
+type UseSightResult<T extends Element = HTMLDivElement> = UseSightReactiveResult<T>;
+/**
+ * Intersection + document visibility as a phase.
+ *
+ * Pass `onVisibilityChange` for zero-re-render mode (animation gating,
+ * many-element observation). Without it, `phase` and `phaseReason` update
+ * via state on every transition. `phaseRef`/`phaseReasonRef` are always current.
+ *
+ * @example
+ * // Reactive
+ * const { ref, phase } = useSight();
+ *
+ * // Transient (no re-renders)
+ * const { ref, phaseRef } = useSight({
+ *   onVisibilityChange: (phase) => { worker.postMessage({ visible: phase === 'visible' }); },
+ * });
+ */
+declare function useSight<T extends Element = HTMLDivElement>(options: UseSightOptions<T> & {
+  onVisibilityChange: SightCallback;
+}): UseSightTransientResult<T>;
+declare function useSight<T extends Element = HTMLDivElement>(options?: UseSightOptions<T>): UseSightReactiveResult<T>;
+//#endregion
+//#region src/react/use-size/index.d.ts
+type SizeCallback = (size: Size) => void;
+interface Size {
+  width: number;
+  height: number;
+}
+interface UseSizeOptions<T extends Element = HTMLDivElement> {
+  /**
+   * Element to measure. Optional. When omitted, attach the returned `ref`.
+   */
+  ref?: RefObject<T | null>;
+  /**
+   * Called on every resize. When provided, `size` is omitted from the return
+   * type and no re-renders occur, the right path for canvas and animation
+   * consumers that read dimensions imperatively.
+   */
+  onResize?: SizeCallback;
+}
+interface UseSizeReactiveResult<T extends Element = HTMLDivElement> {
+  ref: RefObject<T | null>;
+  /** Element dimensions via state, or `null` until first observation. */
+  size: Size | null;
+  /** Element dimensions via ref. Always current, never triggers re-render. */
+  sizeRef: RefObject<Size | null>;
+}
+interface UseSizeTransientResult<T extends Element = HTMLDivElement> {
+  ref: RefObject<T | null>;
+  /** Element dimensions via ref. Always current, never triggers re-render. */
+  sizeRef: RefObject<Size | null>;
+}
+/** @deprecated Use `UseSizeReactiveResult` or `UseSizeTransientResult`. */
+type UseSizeResult<T extends Element = HTMLDivElement> = UseSizeReactiveResult<T>;
+/**
+ * Element dimensions via the shared ResizeObserver singleton.
+ *
+ * Pass `onResize` for zero-re-render mode (canvas, animation loops).
+ * Without it, `size` updates via state on every dimension change.
+ * `sizeRef` is always current in both modes.
+ *
+ * @example
+ * // Reactive (re-renders on resize)
+ * const { ref, size } = useSize();
+ *
+ * // Transient (no re-renders — read sizeRef in onTick/draw)
+ * const { ref, sizeRef } = useSize({ onResize: (s) => applySize(s) });
+ */
+declare function useSize<T extends Element = HTMLDivElement>(options: UseSizeOptions<T> & {
+  onResize: SizeCallback;
+}): UseSizeTransientResult<T>;
+declare function useSize<T extends Element = HTMLDivElement>(options?: UseSizeOptions<T>): UseSizeReactiveResult<T>;
+//#endregion
+//#region src/react/use-container-query/index.d.ts
+interface ContainerBreakpoint {
+  minWidth?: number;
+  maxWidth?: number;
+  minHeight?: number;
+  maxHeight?: number;
+}
+interface UseContainerQueryOptions<T extends Element = HTMLDivElement> {
+  /**
+   * Element to measure. Optional. When omitted, attach the returned `ref`.
+   */
+  ref?: RefObject<T | null>;
+}
+interface UseContainerQueryResult<T extends Element = HTMLDivElement> {
+  /** Attach to the element you want to match against the breakpoint. */
+  ref: RefObject<T | null>;
+  /** Whether the element currently matches the breakpoint. */
+  matches: boolean;
+}
+/**
+ * Returns whether an element matches a size-based container breakpoint.
+ *
+ * Unlike `useSize` (which re-renders on every pixel of resize), this hook only
+ * re-renders when the match result changes, i.e. when the element crosses a
+ * breakpoint boundary. Uses the shared ResizeObserver singleton.
+ *
+ * @example
+ * const { ref, matches } = useContainerQuery({ minWidth: 600 });
+ * return <div ref={ref}>{matches ? 'wide' : 'narrow'}</div>;
+ */
+declare function useContainerQuery<T extends Element = HTMLDivElement>(breakpoint: ContainerBreakpoint, options?: UseContainerQueryOptions<T>): UseContainerQueryResult<T>;
+//#endregion
+//#region src/react/use-scroll-progress/index.d.ts
+type ScrollProgressCallback = (progress: number) => void;
+interface UseScrollProgressOptions<T extends Element = HTMLDivElement> {
+  /**
+   * Element to observe. Optional. When omitted, attach the returned `ref`.
+   */
+  ref?: RefObject<T | null>;
+  /** Number of evenly-spaced thresholds. Default 20 (~5% granularity). */
+  steps?: number;
+  root?: Element | null;
+  rootMargin?: string;
+  /**
+   * Called on every threshold crossing. When provided, `progress` stays `0`
+   * and no re-renders occur, the right path for scroll-driven animation
+   * consumers that read progress imperatively.
+   */
+  onProgress?: ScrollProgressCallback;
+}
+interface UseScrollProgressReactiveResult<T extends Element = HTMLDivElement> {
+  ref: RefObject<T | null>;
+  /** Fraction of the element currently visible (0–1). */
+  progress: number;
+  /** Fraction visible via ref. Always current, never triggers re-render. */
+  progressRef: RefObject<number>;
+}
+interface UseScrollProgressTransientResult<T extends Element = HTMLDivElement> {
+  ref: RefObject<T | null>;
+  /** Fraction visible via ref. Always current, never triggers re-render. */
+  progressRef: RefObject<number>;
+}
+/** @deprecated Use `UseScrollProgressReactiveResult` or `UseScrollProgressTransientResult`. */
+type UseScrollProgressResult<T extends Element = HTMLDivElement> = UseScrollProgressReactiveResult<T>;
+/**
+ * Element visibility ratio (0–1) via the shared IntersectionObserver pool.
+ *
+ * Pass `onProgress` for zero-re-render mode (scroll-driven animation).
+ * Without it, `progress` updates via state at each threshold crossing.
+ * `progressRef` is always current in both modes.
+ *
+ * @example
+ * // Reactive (re-renders at threshold crossings)
+ * const { ref, progress } = useScrollProgress();
+ *
+ * // Transient (no re-renders — read progressRef in onTick)
+ * const { ref, progressRef } = useScrollProgress({
+ *   onProgress: (p) => { el.style.opacity = String(p); },
+ * });
+ */
+declare function useScrollProgress<T extends Element = HTMLDivElement>(options: UseScrollProgressOptions<T> & {
+  onProgress: ScrollProgressCallback;
+}): UseScrollProgressTransientResult<T>;
+declare function useScrollProgress<T extends Element = HTMLDivElement>(options?: UseScrollProgressOptions<T>): UseScrollProgressReactiveResult<T>;
+//#endregion
+//#region src/react/use-render-state/index.d.ts
+/**
+ * Track whether the browser is rendering an element or skipping it under
+ * `content-visibility` (e.g. a `Defer` subtree). Returns `'rendered'` until the
+ * browser reports otherwise.
+ *
+ * Use it to pause raw, non-phase work (a hand-written rAF loop, `setInterval`)
+ * when the subtree stops painting. phase loops self-pause off-screen already.
+ * Has no layout effect. Safe for CLS.
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null);
+ * const phase = useRenderState(ref);
+ * useEffect(() => {
+ *   if (phase === 'skipped') clock.pause();
+ *   else clock.resume();
+ * }, [phase]);
+ * return <Defer ref={ref}><Heavy /></Defer>;
+ */
+declare function useRenderState<T extends Element = HTMLDivElement>(ref: RefObject<T | null>): RenderPhase;
+//#endregion
+//#region src/react/use-idle/index.d.ts
+/**
+ * Returns `false`, then `true` once the browser is idle after mount. Use it to
+ * defer non-critical work or mounting until the main thread is free.
+ *
+ * SSR-safe: returns `false` on the server and during the first client render.
+ *
+ * @example
+ * const idle = useIdle();
+ * return idle ? <Analytics /> : null;
+ */
+declare function useIdle(options?: IdleOptions): boolean;
+//#endregion
+//#region src/react/use-when-idle/index.d.ts
+/**
+ * Run a callback once, when the browser is idle after mount. The effect-shaped
+ * counterpart to `useIdle`. Use it for side effects (prefetching a chunk,
+ * warming a cache, `import()`) rather than rendering.
+ *
+ * Cancels automatically on unmount, and always calls the latest `callback`
+ * without re-subscribing. SSR-safe: nothing runs on the server.
+ *
+ * @example
+ * // Prefetch a heavy panel during idle time so it opens instantly later.
+ * useWhenIdle(() => void import('./chat-panel'));
+ */
+declare function useWhenIdle(callback: () => void, options?: IdleOptions): void;
+//#endregion
+//#region src/react/use-canvas/index.d.ts
+interface Size$1 {
+  width: number;
+  height: number;
+}
+/**
+ * Per-frame canvas draw callback. Receives the 2D context, frame state, and
+ * current element size. Draw directly to the canvas. Never call React
+ * `setState` here.
+ */
+type CanvasDrawFn = (ctx: CanvasRenderingContext2D, frame: FrameState, size: Size$1) => void;
+interface UseCanvasOptions {
+  containerRef: RefObject<Element | null>;
+  canvasRef: RefObject<HTMLCanvasElement | null>;
+  /**
+   * Called every frame with the 2D context, frame state, and current element size.
+   * Draw directly to the canvas. Never call React `setState` here.
+   */
+  draw: CanvasDrawFn;
+  fps?: number;
+  enabled?: boolean;
+  reducedMotion?: ReducedMotionBehavior;
+  /** Behavior when quality degrades. Default `'throttle'`. For heavy GPU work, `'pause'` is often the right call. */
+  degraded?: DegradedBehavior;
+  /** FPS cap when `degraded` is `'throttle'`. Default `30`. */
+  degradedFps?: number;
+}
+interface UseCanvasResult {
+  restart: () => void;
+  phase: LoopPhase;
+  phaseReason: LoopReason;
+  quality: Quality;
+  qualityReason: DegradedReason | undefined;
+}
+/**
+ * Canvas-specific animation with DPR-aware sizing, ResizeObserver coalescing,
+ * context management, and GPU context loss recovery.
+ *
+ * @example
+ * useCanvas({
+ *   containerRef,
+ *   canvasRef,
+ *   draw: (ctx, frame, size) => {
+ *     ctx.clearRect(0, 0, size.width, size.height);
+ *     // render...
+ *   },
+ * });
+ */
+declare function useCanvas(options: UseCanvasOptions): UseCanvasResult;
+//#endregion
+//#region src/react/use-tween/index.d.ts
+interface UseTweenOptions {
+  target: number;
+  duration?: number;
+  delay?: number;
+  easing?: (progress: number) => number;
+  enabled?: boolean;
+  /** Default: `'complete'`. Tweens jump to target under reduced motion. */
+  reducedMotion?: ReducedMotionBehavior;
+}
+/**
+ * Animate a value from its current position to `target` over `duration`.
+ *
+ * Uses `useState` per frame. Appropriate for cheap renders (counters, opacity,
+ * progress bars). For batch animations, use `useLoop` with ref-based DOM writes.
+ *
+ * @remarks
+ * Unlike `createTicker`/`createLoop`, `useTween` drives its own rAF rather than
+ * the shared frame-locked clock. It's a finite, self-completing tween whose value
+ * must land in React state, so it doesn't need cross-loop visual sync, strong
+ * pause, or delta clamping. Routing it through the shared clock would add bundle
+ * weight for no benefit.
+ *
+ * @example
+ * const value = useTween({ target: 100, duration: 500 });
+ */
+declare function useTween(options: UseTweenOptions): number;
+//#endregion
+//#region src/react/use-presence/index.d.ts
+type PresencePhase = 'idle' | 'entered' | 'exiting' | 'exited';
+type PresenceReason = 'initial' | 'show' | 'hide' | 'animation-end' | 'interrupted';
+type PresenceMode = 'mount' | 'reveal';
+interface UsePresenceOptions {
+  show: boolean;
+  mode?: PresenceMode;
+  /** Controls first-mount behavior. `'animate'` (default): enter animation plays. `'instant'`: appears immediately. */
+  enter?: 'animate' | 'instant';
+  /** Safety-net timeout in ms if transitionend/animationend doesn't fire during exit. Default 5000. */
+  exitDuration?: number;
+  /** Whether to respect the user's reduced motion preference. Default `'respect'`. */
+  reducedMotion?: 'respect' | 'ignore';
+}
+interface UsePresenceResult {
+  phase: PresencePhase;
+  phaseReason: PresenceReason;
+  /** Convenience: `phase !== 'idle' && phase !== 'exited'` for conditional rendering in mount mode. */
+  mounted: boolean;
+  ref: RefObject<Element | null>;
+  /** Whether the component should stamp `data-enter="animate"`. Accounts for enter option + reduced motion. */
+  enter: 'animate' | 'instant';
+}
+/**
+ * Composable presence primitive for mount/unmount lifecycle with CSS transitions.
+ *
+ * Enter animations use CSS `@starting-style`, gated by `data-enter="animate"`.
+ * Exit animations are JS-coordinated: waits for `transitionend`/`animationend`
+ * before unmounting.
+ *
+ * @example
+ * const { phase, ref, mounted, enter } = usePresence({ show: isOpen });
+ * if (!mounted) return null;
+ * return (
+ *   <div ref={ref} data-phase={phase} data-enter={enter === 'animate' ? 'animate' : undefined}
+ *     className="transition-opacity data-[enter=animate]:starting:opacity-0 data-[phase=exiting]:opacity-0" />
+ * );
+ */
+declare function usePresence(options: UsePresenceOptions): UsePresenceResult;
+//#endregion
+//#region src/react/presence/index.d.ts
+interface PresenceProps extends ComponentProps<'div'> {
+  show: boolean;
+  mode?: PresenceMode;
+  /** Controls first-mount behavior. `'animate'` (default): enter animation plays. `'instant'`: appears immediately. */
+  enter?: 'animate' | 'instant';
+  /** Safety-net timeout in ms if transitionend/animationend doesn't fire during exit. Default 5000. */
+  exitDuration?: number;
+  /** Whether to respect the user's reduced motion preference. Default `'respect'`. */
+  reducedMotion?: 'respect' | 'ignore';
+  ref?: Ref<HTMLDivElement>;
+}
+/**
+ * Renders a `div` that manages its own mounting lifecycle.
+ *
+ * Stamps `data-phase` for exit animations and `data-enter="animate"` to gate
+ * CSS `@starting-style` enter animations. Reduced motion is handled automatically.
+ *
+ * @example
+ * <Presence
+ *   show={isOpen}
+ *   className="transition-opacity data-[enter=animate]:starting:opacity-0 data-[phase=exiting]:opacity-0"
+ * >
+ *   Modal content
+ * </Presence>
+ */
+declare function Presence({
+  show,
+  mode,
+  enter: enterOption,
+  exitDuration,
+  reducedMotion,
+  ref: forwardedRef,
+  children,
+  ...divProps
+}: PresenceProps): JSX.Element | null;
+//#endregion
+//#region src/react/when-visible/index.d.ts
+interface WhenVisibleProps extends ComponentProps<'div'> {
+  /** IntersectionObserver rootMargin. Default `'200px'` (generous headroom for preloading). */
+  rootMargin?: string;
+  /** IntersectionObserver threshold. */
+  threshold?: number | number[];
+  /** IntersectionObserver root element. */
+  root?: Element | null;
+  /** Content shown while awaiting intersection. Sentinel div is always rendered for IO. */
+  fallback?: ReactNode;
+  /** Forwarded to the rendered div in both states (the sentinel before visible, the entered div after). Populated at mount. */
+  ref?: Ref<HTMLDivElement>;
+}
+/**
+ * Mounts children when the element enters the viewport. One-shot (once
+ * triggered, stays mounted).
+ *
+ * Enter animation uses CSS `@starting-style`, gated by `data-enter="animate"`.
+ * Reduced motion is automatic: the attribute is not stamped when the user
+ * prefers reduced motion.
+ *
+ * @example
+ * <WhenVisible rootMargin="200px" className="transition-opacity data-[enter=animate]:starting:opacity-0">
+ *   <HeavyChart />
+ * </WhenVisible>
+ */
+declare function WhenVisible({
+  rootMargin,
+  threshold,
+  root,
+  fallback,
+  children,
+  ref: forwardedRef,
+  ...divProps
+}: WhenVisibleProps): JSX.Element;
+//#endregion
+//#region src/react/when-idle/index.d.ts
+interface WhenIdleProps extends ComponentProps<'div'> {
+  /** Max ms to wait before mounting even if no idle period occurs. */
+  timeout?: number;
+  /** Content shown until the browser is idle. */
+  fallback?: ReactNode;
+  ref?: Ref<HTMLDivElement>;
+}
+/**
+ * Mounts children once the browser is idle after first paint. One-shot (once
+ * mounted, stays mounted). Use it to defer non-critical UI off the critical path.
+ *
+ * Children are not server-rendered (idle never fires during SSR), so reserve
+ * this for non-critical content. For viewport-gated mounting use `WhenVisible`;
+ * to keep content in the DOM but skip painting use `Defer`.
+ *
+ * Enter animation uses CSS `@starting-style`, gated by `data-enter="animate"`.
+ * Reduced motion is automatic: the attribute is not stamped when the user
+ * prefers reduced motion.
+ *
+ * @example
+ * <WhenIdle fallback={<Skeleton />}>
+ *   <SecondaryPanel />
+ * </WhenIdle>
+ */
+declare function WhenIdle({
+  timeout,
+  fallback,
+  children,
+  ref: forwardedRef,
+  ...divProps
+}: WhenIdleProps): JSX.Element;
+//#endregion
+//#region src/react/defer/index.d.ts
+interface DeferProps extends Omit<ComponentProps<'div'>, 'style'> {
+  /**
+   * Approximate size reserved before first paint (any CSS length, e.g. `'800px'`).
+   * After the first render the browser remembers the real size. Default `'1000px'`.
+   */
+  estimatedHeight?: string;
+  ref?: Ref<HTMLDivElement>;
+}
+/**
+ * Skip the browser's rendering work (style, layout, paint) for off-screen
+ * content via `content-visibility: auto`. Pure CSS, no JS, no observer.
+ *
+ * Children stay in the DOM and are server-rendered (SEO- and CLS-safe).
+ * `contain-intrinsic-size: auto <estimatedHeight>` reserves space so the
+ * scrollbar does not jump. Defers rendering only, not hydration or mounting.
+ *
+ * The render-skip styles are encapsulated and cannot be overridden. There is
+ * no `style` prop. Style the wrapper with `className`; this keeps the
+ * no-layout-shift guarantee intact.
+ *
+ * @example
+ * <Defer estimatedHeight="600px" className="my-section">
+ *   <ArticleSection />
+ * </Defer>
+ *
+ * @remarks
+ * Animations inside a `Defer` keep running while paint is skipped. phase loops
+ * self-pause off-screen on their own; for raw rAF/interval work, gate it with
+ * `useRenderState`.
+ */
+declare function Defer({
+  estimatedHeight,
+  children,
+  ref,
+  ...divProps
+}: DeferProps): JSX.Element;
+//#endregion
+//#region src/react/swap/index.d.ts
+interface SwapProps extends ComponentProps<'div'> {
+  active: string;
+  exitDuration?: number;
+  children: ReactNode;
+}
+/**
+ * Coordinated exit-then-enter transitions for N states.
+ * Only one state is entering or exiting at a time (no overlap).
+ *
+ * The current state fully exits before the new state enters. Rapid changes
+ * (A->B->C during A's exit) skip intermediate states and jump to the latest.
+ *
+ * @example
+ * <Swap active={success ? 'success' : 'form'}>
+ *   <Swap.State id="form" className="transition-all data-[phase=exiting]:opacity-0">
+ *     <Form />
+ *   </Swap.State>
+ *   <Swap.State id="success" className="transition-all data-[enter=animate]:starting:opacity-0">
+ *     <SuccessMessage />
+ *   </Swap.State>
+ * </Swap>
+ */
+declare function SwapRoot({
+  active,
+  exitDuration,
+  children,
+  ...divProps
+}: SwapProps): JSX.Element;
+interface SwapStateProps extends ComponentProps<'div'> {
+  id: string;
+  ref?: Ref<HTMLDivElement>;
+}
+declare function SwapState({
+  id,
+  ref: forwardedRef,
+  children,
+  ...divProps
+}: SwapStateProps): JSX.Element | null;
+declare const Swap: typeof SwapRoot & {
+  State: typeof SwapState;
+};
+//#endregion
+export { type CanvasDrawFn, type ContainerBreakpoint, Defer, type DeferProps, type IdleOptions, type LifecyclePhase, type LifecycleReason, type LifecycleReducedMotion, type LoopTickFn, Presence, type PresenceMode, type PresencePhase, type PresenceProps, type PresenceReason, type RenderPhase, type ScrollProgressCallback, type SightCallback, type Size, type SizeCallback, Swap, type SwapProps, type SwapStateProps, type UseCanvasOptions, type UseCanvasResult, type UseContainerQueryOptions, type UseContainerQueryResult, type UseLifecycleOptions, type UseLifecycleResult, type UseLoopOptions, type UseLoopResult, type UsePresenceOptions, type UsePresenceResult, type UseScrollProgressOptions, type UseScrollProgressReactiveResult, type UseScrollProgressResult, type UseScrollProgressTransientResult, type UseSightOptions, type UseSightReactiveResult, type UseSightResult, type UseSightTransientResult, type UseSizeOptions, type UseSizeReactiveResult, type UseSizeResult, type UseSizeTransientResult, type UseTweenOptions, WhenIdle, type WhenIdleProps, WhenVisible, type WhenVisibleProps, useCanvas, useContainerQuery, useDevicePixelRatio, useIdle, useLifecycle, useLoop, useMediaQuery, usePrefersReducedMotion, usePresence, useRenderState, useScrollProgress, useSight, useSize, useStableCallback, useSyncedRef, useTween, useWhenIdle };
+//# sourceMappingURL=react.d.ts.map