@vibecook/ice 0.1.0 → 0.2.0

package/dist/types/packages/kernel/src/layout.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Pure auto-layout math (2026-07-17, James: cards dropped into a folder "just
+ * pile up on each other" — and, later, an explicit desktop-style Clean Up).
+ *
+ * Two primitives, two products, one law each:
+ *  - `insertSlot` — place ONE newcomer near a drop hint without moving
+ *    anything: newcomers get a free slot, incumbents never move. Consumed by
+ *    the drop-consume path (l3-behave). Candidates are edge-aligned to the
+ *    incumbents (flush right/below/left/above with a gutter), so successive
+ *    drops grow aligned rows and columns instead of a global imposed grid.
+ *  - `packLayout` — bottom-left candidate packing for the explicit
+ *    "Clean Up" command (v2 2026-07-17, James: shelves were "not really
+ *    efficient" and selection packs "overlay on top of unselected widgets"):
+ *    items flow in reading order (current y, then x, then index) and each
+ *    takes the lowest-then-leftmost free spot, so small cards fill the air
+ *    beside tall ones instead of opening a new shelf. `obstacles` rects are
+ *    honored as immovable — a scoped pack flows AROUND bystanders. Still
+ *    "my mess, straightened": deterministic, anchored at the cluster's own
+ *    top-left, idempotent on packed input (pinned by test).
+ *  - `layerGraph` — the Unreal-Blueprint-style arrange for WIRED widgets:
+ *    Sugiyama-lite layered layout (longest-path ranks along edge direction,
+ *    barycenter ordering, columns left→right, vertically centered). Callers
+ *    lay out each connected component with this and pack the resulting
+ *    blocks with `packLayout`.
+ *
+ * Plain structs in, plain structs out (Law 13): no ECS, no DOM, no camera.
+ * All coordinates live in ONE frame — callers convert (container-local for
+ * folder drops, world for canvas clean-up) before and after.
+ */
+export interface LayoutRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface LayoutSize {
+    readonly w: number;
+    readonly h: number;
+}
+export interface LayoutPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Nearest free slot to `hint` for a `size` newcomer among `incumbents`.
+ *
+ * The hint wins verbatim when it is already free (a deliberate drop into
+ * empty space is user intent — don't second-guess it). Otherwise candidates
+ * flush against each incumbent's edges (top- and far-aligned variants) are
+ * ranked by squared distance to the hint; ties resolve to the first-seen
+ * candidate (stable in incumbent order — deterministic across runs). The
+ * fallback — a spot gutter-right of EVERYTHING — cannot crowd anyone, so a
+ * slot always exists.
+ */
+export declare function insertSlot(incumbents: readonly LayoutRect[], size: LayoutSize, hint: LayoutPoint, gutter: number): {
+    x: number;
+    y: number;
+};
+export interface PackOpts {
+    readonly gutter: number;
+    /** Pack origin; defaults to the items' current bbox top-left (the cluster stays put). */
+    readonly origin?: LayoutPoint;
+    /**
+     * Band wrap width; defaults to a near-square derivation (√(total area × 1.6),
+     * never narrower than the widest item). Soft: an item that fits nowhere
+     * inside the band still places (lowest spot, band ignored) rather than
+     * failing.
+     */
+    readonly maxWidth?: number;
+    /**
+     * Immovable rects the pack must flow AROUND (e.g. unselected widgets when
+     * arranging a selection). Never returned, never moved, never crowded.
+     */
+    readonly obstacles?: readonly LayoutRect[];
+}
+/**
+ * Bottom-left candidate packing: items in reading order of their CURRENT
+ * positions (strict y, then x, then input index) each take the
+ * lowest-then-leftmost free spot from the candidate set (the origin, plus
+ * gutter-flush right-of and below-of every placed/obstacle rect, plus the
+ * band-left row start under each). Dense with mixed sizes — small cards fill
+ * the air beside tall ones — and obstacle-aware. Returns placements parallel
+ * to the input array.
+ */
+export declare function packLayout(items: readonly LayoutRect[], opts: PackOpts): Array<{
+    x: number;
+    y: number;
+}>;
+export interface LayerGraphOpts {
+    /** Horizontal gap between columns (leave room for wires to breathe). */
+    readonly gapX: number;
+    /** Vertical gap between nodes inside a column. */
+    readonly gapY: number;
+    /**
+     * Wrap the column run into stacked BANDS when the unwrapped width would
+     * exceed this (carriage-return style: each band flows left→right, bands
+     * stack top→down with a 2×gapY separator). Omit for a single band — a
+     * graph is inherently wide and only wraps when the caller says the canvas
+     * band demands it.
+     */
+    readonly maxWidth?: number;
+}
+/**
+ * Layered graph layout (Sugiyama-lite) — the Unreal-Blueprint-style arrange
+ * for wired widgets. Rank = longest path from the sources along edge
+ * direction (a DFS drops back edges, so cycles are safe); columns flow
+ * left→right; nodes stack top→down within a column. Ordering = alternating
+ * barycenter sweeps with the BEST ordering kept (counted wire crossings),
+ * then the classic transpose refinement (adjacent swaps that strictly
+ * reduce crossings) — not provably minimal, but the standard practical
+ * pair. Columns center vertically on their band's tallest. Placements are
+ * relative to (0,0) — callers anchor the block. Deterministic: all
+ * orderings tie-break on node index.
+ */
+export declare function layerGraph(nodes: readonly LayoutSize[], edges: readonly (readonly [number, number])[], opts: LayerGraphOpts): Array<{
+    x: number;
+    y: number;
+}>;

package/dist/types/packages/kernel/src/nav-flight.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Nav-flight math (design-006 §2/§4 — the portal zoom, T1 camera-flight half).
+ *
+ * Pure math, no ECS/DOM. Conventions are coords.ts's (Law 13): camera {x,y} =
+ * world point at the viewport top-left, zoom = screen px per world unit,
+ * `screen = (world − cam)·zoom`.
+ *
+ * The portal embedding: a container's content coordinates are FRAME-LOCAL
+ * (design-001 §5.1) — the transition DEFINES the embedding by mapping the
+ * arrival camera's visible rect onto the container's body rect (`portalAffine`,
+ * aspect-fit, centers aligned). With that affine fixed, both transition layers
+ * ride ONE camera: the destination frame renders under `c(t)` directly; the
+ * departed frame renders under `c(t) ∘ A` where A maps departed-frame coords
+ * into destination-frame coords. Continuity at the cut is exact by
+ * construction (`solveFlightStart`), and no drift is possible mid-flight —
+ * there is no second clock.
+ *
+ * Numerics locked by the mock (2026-07-15, three rounds of field testing):
+ *  - the progress spring uses the CLOSED-FORM critically-damped solution —
+ *    semi-implicit Euler diverges once ω·dt nears 1 (a fast exit response on
+ *    one dropped frame sent the mock's camera to zoom 1501);
+ *  - the path interpolates zoom in LOG space (constant perceived zoom
+ *    velocity — van Wijk & Nuij) with the view center linear in 1/zoom, which
+ *    is exactly an anchored zoom whenever a fixed screen point exists;
+ *  - flights beyond `maxOctaves` must be depth-capped (`capFlightStart`):
+ *    sweeping a DOM plane's raster scale ~30× in one flight outruns
+ *    Chromium's async tile re-raster (stale/missing tiles, persisting at
+ *    rest) — the capped flight is presented as a crossfade-through-zoom.
+ */
+import type { CameraState } from "./coords";
+import type { Rect } from "./shapes";
+/** Uniform scale + translate: `A(q) = o + q·s`. */
+export interface PortalAffine {
+    readonly s: number;
+    readonly ox: number;
+    readonly oy: number;
+}
+/** The world rect a camera shows through a viewport. */
+export declare function visibleRect(cam: CameraState, vpW: number, vpH: number): Rect;
+/**
+ * The portal embedding: map `arrival` (the world rect the arrival camera will
+ * show, in the CHILD frame's coords) onto `portal` (the container's body rect,
+ * in the PARENT frame's coords). Aspect-FIT with centers aligned (design-006
+ * §8.3 — the card chrome absorbs the letterbox).
+ */
+export declare function portalAffine(arrival: Rect, portal: Rect): PortalAffine;
+export declare function invertAffine(a: PortalAffine): PortalAffine;
+/** `(outer ∘ inner)(q) = outer(inner(q))` — for multi-level exit portals. */
+export declare function composeAffine(outer: PortalAffine, inner: PortalAffine): PortalAffine;
+/**
+ * Continuity solve: the camera `c0` (in the DESTINATION frame) under which
+ * departed-frame content mapped through `A` (departed → destination coords)
+ * renders EXACTLY as it did under `camPre` (in the departed frame) the instant
+ * before the cut. Derivation: a departed point q renders at
+ * `(A(q) − c0)·z0 = q·(A.s·z0) + (A.o − c0)·z0`; matching `(q − camPre)·zPre`
+ * coefficient-wise gives z0 and the origin below. Zoom limits deliberately do
+ * NOT apply here — flight paths transit far outside the user-gesture band
+ * (design-006 §3.1); only the ARRIVAL camera is clamped by the caller.
+ */
+export declare function solveFlightStart(A: PortalAffine, camPre: CameraState): CameraState;
+/** Zoom distance in octaves — the flight-length measure (design-006 §4/§5). */
+export declare function flightOctaves(from: CameraState, to: CameraState): number;
+/**
+ * Depth-cap a flight start (design-006 §5): beyond `maxOctaves`, clamp the
+ * start zoom to `capFactor ×` the arrival zoom (dive direction preserved),
+ * keeping the exact start's view CENTER — the portal anchor — so the motion
+ * still comes from/goes to the right place. `capped: true` means the caller
+ * must present the flight as a crossfade (frozen departing cover + incoming
+ * fade-in): geometric continuity is unpresentable at that raster-scale swing.
+ */
+export declare function capFlightStart(exact: CameraState, arrival: CameraState, vpW: number, vpH: number, maxOctaves: number, capFactor: number): {
+    c0: CameraState;
+    capped: boolean;
+};
+/**
+ * The flight path `c(p)`, p ∈ [0,1]: zoom log-lerped (constant perceived zoom
+ * velocity); view CENTER linear in 1/zoom — exactly an anchored zoom whenever
+ * a fixed screen point exists between the endpoints, a graceful blend
+ * otherwise. Endpoints are exact: c(0) = c0, c(1) = c1.
+ */
+export declare function flightCamera(c0: CameraState, c1: CameraState, p: number, vpW: number, vpH: number): CameraState;
+/**
+ * One step of the critically-damped progress spring toward 1, in CLOSED FORM:
+ * with u = 1 − p, the exact solution is `u(t) = (u₀ + Bt)·e^(−ωt)`,
+ * `B = −v₀ + ω·u₀`. Unconditionally stable at ANY dt — the discretized form
+ * (semi-implicit Euler) diverges once ω·dt approaches 1, which one dropped
+ * frame at a fast response reaches easily (mock-measured, 2026-07-15).
+ * From rest (v=0) the approach is monotonic: p never overshoots 1.
+ */
+export declare function springStep(p: number, v: number, omega: number, dtSec: number): {
+    p: number;
+    v: number;
+};

package/dist/types/packages/r3f/src/bridge.d.ts

@@ -3,15 +3,16 @@
  *
  * Owns everything ENGINE-facing: the module-side island state, the island
  * registry (scene+camera handles the frame pass iterates), per-island dirt
- * observers, the `r3fInvalidator` reflector, `useIslandFrame` callbacks, the
- * render write trap, and entity-death cleanup. Everything GL-facing (FBO
- * pool, quads, the actual passes) lives in `GLViews`, whose lifetime is the
- * Canvas/context's — the bridge outlives Canvas remounts (HMR) and carries
- * the invalidation wiring across them.
+ * observers, the `r3fInvalidator`/`r3fAdvance` reflectors, `useIslandFrame`
+ * callbacks, the render write trap, and entity-death cleanup. Everything
+ * GL-facing (FBO pool, quads, the actual passes) lives in `GLViews`, whose
+ * lifetime is the Canvas/context's — the bridge outlives Canvas remounts
+ * (HMR) and carries the frame wiring across them.
  *
  * Two-level invalidation, mechanized:
  * - COMPOSITE dirt (cheap — re-run the frame pass, sample cached textures):
- *   camera/viewport via the reflector; per-island Position/StackZ Tier-3;
+ *   camera/viewport via the reflector; per-island Position Tier-3; the frame
+ *   ChildOf reorder wake (petition 8 — quad renderOrder is sibling order);
  *   island enter/exit via register/unregister. All call `requestFrame()`.
  * - ISLAND dirt (expensive — repaint the FBO): per-island props-group and
  *   Size Tier-3 → `bumpPaint()` + `requestFrame()`; the animation signal
@@ -20,11 +21,28 @@
  *   `Camera.gesturing`; the gesture-end camera write re-fires the reflector,
  *   so the once-at-gesture-end repaint needs no extra machinery).
  *
+ * REFLECT-PHASE ADVANCE (design-004 §3 amendment, 2026-07-20 — the pan-lag
+ * fix): the composite render is driven FROM the engine's reflect phase, not
+ * from R3F's demand loop. `requestFrame()` only latches `wantsFrame`; the
+ * `r3fAdvance` reflector (`always: true` — registered right after the
+ * observed invalidator so same-flush dirt is consumed) calls the wired
+ * `renderNow` (R3F `advance`) synchronously. DOM plane transforms and the GL
+ * composite therefore commit in the SAME task and present in the same frame.
+ * The prior wiring (`invalidate()` → R3F's own rAF) could only arm R3F for
+ * the NEXT frame, and rAF registration order between the two loops is sticky
+ * luck — field-measured on 2026-07-20: R3F rendering the PREVIOUS frame's
+ * camera while the DOM plane showed the current one, a permanent one-frame
+ * smear under fast pans. Ambient animation rides the same seam: the pass
+ * reports its self-sustain plan via `schedulePass`, and the due-time check
+ * replaces the old wake-up timer (the engine loop runs every frame anyway).
+ * The Canvas must mount `frameloop="never"` — a self-scheduling loop would
+ * re-render out of phase again.
+ *
  * Runtime-three-free (type-only imports): unit tests drive the bridge with a
  * real world and fake scene/camera handles, no GL context.
  */
 import type { OrthographicCamera, Scene } from "three";
-import { type Engine, type Entity } from "@ice/core";
+import { type Engine, type Entity, type SiblingOrderIndex } from "@ice/core";
 import { type IslandStateStore } from "./island-state";
 import { type RenderWriteTrap } from "./dev-write-trap";
 export interface IslandHandle {
@@ -36,11 +54,22 @@ export type IslandFrameCallback = (dtMs: number) => void;
 export interface GLBridgeOpts {
     /** Arm the zero-render→ECS-writes trap (DEV builds / traces). Default false. */
     readonly devAssertRenderWrites?: boolean;
+    /**
+     * Injected monotonic clock for the ambient-animation due-time (tests pass a
+     * stub — the pool's injected-`now` precedent). Default `performance.now`.
+     */
+    readonly now?: () => number;
 }
 export interface GLBridge {
     readonly engine: Engine;
     readonly state: IslandStateStore;
     readonly renderAssert: RenderWriteTrap;
+    /**
+     * The frame ordinal cache (petition 8): the compositor pass reads quad
+     * renderOrder from it, and its `ordinals()` read resets the staleness the
+     * bridge's reorder wake filters on — bridge and pass MUST share it.
+     */
+    readonly order: SiblingOrderIndex;
     /**
      * Island mount (the `<Island>` component): registers the scene/camera pair,
      * stamps `animatedDecl` from the widget type, and arms the per-island dirt
@@ -54,14 +83,46 @@ export interface GLBridge {
     /** Subscribe a paint-time callback; holds an animation ref while live. */
     addFrameCallback(entity: Entity, cb: IslandFrameCallback): () => void;
     frameCallbacksFor(entity: Entity): readonly IslandFrameCallback[];
-    /** Composite invalidation — schedule a frame pass (coalesced). */
+    /**
+     * Composite invalidation — latch a frame pass (coalesced). Consumed by the
+     * `r3fAdvance` reflector on the NEXT engine flush: dirt raised during a
+     * step (observers, the invalidator reflector) renders the SAME frame; dirt
+     * raised outside a step (React effects) renders on the next tick.
+     */
     requestFrame(): void;
     /** Island invalidation — this island must repaint (props/size/manual dirt). */
     bumpPaint(entity: Entity): void;
-    /** Composite-quad lift scale (1 = rest). Scales the CARD on the canvas, corners intact. */
-    setCompositeScale(entity: Entity, scale: number): void;
-    /** GLViews wires R3F's demand-loop `invalidate` here (null on unmount). */
-    setInvalidate(fn: (() => void) | null): void;
+    /**
+     * Composite-quad lift scale (1 = rest). Scales the CARD on the canvas,
+     * corners intact. Sets the TARGET: the compositor pass eases the drawn
+     * value there over `durationMs` (default 180 — the DOM card-lift spring;
+     * 0 snaps). Mid-flight retargets restart from the current drawn value.
+     */
+    setCompositeScale(entity: Entity, scale: number, durationMs?: number): void;
+    /**
+     * Composite-quad opacity (1 = rest) — the lift's fade twin. MULTIPLIES the
+     * widget's durable `Opacity` cell in the pass (presentation-transient over
+     * the doc fact). Sets the TARGET: the pass eases the drawn value there over
+     * `durationMs` (default 180; 0 snaps); mid-flight retargets restart from the
+     * current drawn value.
+     */
+    setCompositeOpacity(entity: Entity, opacity: number, durationMs?: number): void;
+    /**
+     * GLViews wires R3F's `advance` here (null on unmount). Called ONLY by the
+     * `r3fAdvance` reflector, synchronously inside the engine's reflect phase —
+     * the same task the DOM reflectors write in, so both surfaces present the
+     * same camera. While unwired, latched dirt survives and renders on the
+     * first flush after (re)mount.
+     */
+    setRenderNow(fn: ((nowMs: number) => void) | null): void;
+    /**
+     * The pass reports how the frame loop continues (`selfSustainPlan`):
+     * `"now"` latches an immediate next frame (lift eases, stagger backlogs —
+     * native refresh); a number arms the ambient-animation due-time (the
+     * `maxAnimationFps` cap — replaces the old wake-up timer); `"none"` parks.
+     * Each pass re-reports, so the due-time is always the LAST pass's plan.
+     */
+    schedulePass(plan: "none" | "now" | number): void;
     /** Tear down reflector + observers + state (doc close / app teardown). */
     uninstall(): void;
 }

package/dist/types/packages/r3f/src/composite-material.d.ts

@@ -9,9 +9,18 @@ import type { Texture } from "three";
 export declare class CompositeMaterial extends ShaderMaterial {
     private readonly mapUniform;
     private readonly opacityUniform;
+    private readonly draggedRectUniform;
+    private readonly isDraggedUniform;
     constructor();
     /** Bind the island's FBO texture (null clears). */
     setMap(map: Texture | null): void;
     /** Composite opacity. Pass-through — no clamping; callers pass valid 0..1. */
     setOpacity(opacity: number): void;
+    /**
+     * Drag clip, composite-space min/max (v1's uDraggedRect re-cut from screen
+     * space). (0,0,0,0) = inactive. Mutates the vec4 in place — no allocation.
+     */
+    setDraggedRect(minX: number, minY: number, maxX: number, maxY: number): void;
+    /** True on the dragged card's own quad — exempt from the clip. */
+    setIsDragged(isDragged: boolean): void;
 }

package/dist/types/packages/r3f/src/compositor-pass.d.ts

@@ -21,6 +21,17 @@ export interface QuadLike {
     setTexture(t: unknown): void;
     setVisible(v: boolean): void;
     setRenderOrder(n: number): void;
+    /**
+     * Composite opacity, 0..1 (design-004 §3: the neutral composite's whole
+     * per-widget fact) — the pass passes `Opacity` cell × eased fade channel.
+     */
+    setOpacity(o: number): void;
+    /**
+     * Drag clip (v1 RFC-003, composite-space): non-exempt quads discard
+     * fragments inside the rect so a dragged card's P1 DOM chrome shows
+     * through. (0,0,0,0, false) = inactive.
+     */
+    setDragClip(minX: number, minY: number, maxX: number, maxY: number, exempt: boolean): void;
 }
 export interface QuadsLike {
     ensure(key: number): QuadLike;
@@ -70,6 +81,15 @@ export interface PassContext {
     readonly compositeScene: object;
     readonly maxFboBytes: number;
     readonly maxRepaintsPerFrame: number;
+    /**
+     * Idle ceiling on island paint resolution (design-004 §3 amendment,
+     * 2026-07-14): new paints allocate at `min(pixelRatio, maxPaintDpr) × band`.
+     * On a dpr-2 display the composite's bilinear upscale from a 1.5× texture is
+     * visually indistinguishable (A/B knot crops) while Hot repaint cost drops
+     * ~22 %. Composes with the gesture drop (pixelRatio is already 1 while
+     * gesturing) and with zoom bands. `Infinity` = uncapped.
+     */
+    readonly maxPaintDpr: number;
     readonly dtMs: number;
 }
 export interface PassStats {
@@ -79,5 +99,7 @@ export interface PassStats {
     evicted: number;
     fboBytes: number;
     anyHot: boolean;
+    /** A composite ease (lift scale or fade) is mid-flight — caller re-invalidates (composite-only frames). */
+    liftAnimating: boolean;
 }
 export declare function runCompositorPass(ctx: PassContext): PassStats;

package/dist/types/packages/r3f/src/gl-root.d.ts

@@ -10,6 +10,22 @@ export interface GLViewsProps {
     readonly maxFboBytes?: number;
     /** Repaint stagger per composited frame (v1 default 4). */
     readonly maxRepaintsPerFrame?: number;
+    /**
+     * Ambient-animation rate cap (default 60; `Infinity` = uncapped). Applies
+     * ONLY to self-sustained frames — Hot islands and stagger backlogs park the
+     * loop between paints instead of spinning at native refresh (5 Hot islands
+     * at 120 Hz dpr-2 measured 96 % GPU duty at idle, 2026-07-14). Lift eases
+     * and externally invalidated frames (camera, drags, props dirt) still run
+     * at display rate. Approximate: frames land on the vsync grid.
+     */
+    readonly maxAnimationFps?: number;
+    /**
+     * Idle paint-DPR ceiling (default 1.5; `Infinity` = uncapped): island FBOs
+     * allocate at `min(pixelRatio, maxPaintDpr) × band`. On dpr-2 displays the
+     * composite's bilinear upscale from 1.5× is visually indistinguishable
+     * (2026-07-14 A/B) and cuts Hot repaint cost ~22 %.
+     */
+    readonly maxPaintDpr?: number;
     /**
      * Shared IBL: stamped as `scene.environment` on EVERY island's private
      * scene (arrival/change repaints all islands). Load it app-side (e.g.
@@ -17,5 +33,64 @@ export interface GLViewsProps {
      * fine; islands paint unlit-by-IBL and repaint when it lands.
      */
     readonly environment?: Texture | null;
+    /**
+     * GL frame profiling (2026-07-13): fires once per composited frame with the
+     * pass's real costs. CPU/counts/pass-shape are engine-measured every
+     * profiled frame; GPU ms rides stats-gl's headless `StatsProfiler`
+     * (EXT_disjoint_timer_query / WebGPU timestamps — 0 where unsupported, e.g.
+     * Safari without its flag), DYNAMICALLY imported on first use so the
+     * dependency costs nothing when profiling is off. Feed the numbers to the
+     * devtools profiler HUD as lanes (`devtools.lane("gpu", s.gpuMs)`).
+     */
+    readonly onFrameStats?: (stats: GlFrameStats) => void;
+}
+/**
+ * One profiled composite frame — see {@link GLViewsProps.onFrameStats}.
+ * MIRRORED structurally as `GlPanelStats` in @ice/devtools (which cannot
+ * import r3f under the walls) — keep the shapes aligned.
+ */
+export interface GlFrameStats {
+    /** Whole-pass main-thread ms (reconcile + island paints + composite). */
+    readonly cpuMs: number;
+    /** GPU ms summed across the pass's render calls (0 until queries resolve / unsupported). */
+    readonly gpuMs: number;
+    /** stats-gl smoothed fps (0 until the profiler is live). */
+    readonly fps: number;
+    /** `renderer.info` aggregated across ALL of this pass's render calls. */
+    readonly drawCalls: number;
+    readonly triangles: number;
+    readonly points: number;
+    readonly lines: number;
+    /** Live compiled shader programs (renderer-lifetime, not per-frame). */
+    readonly programs: number;
+    readonly geometries: number;
+    readonly textures: number;
+    /** Virtual texturing: live island render targets + their summed resolution. */
+    readonly renderTargets: number;
+    readonly renderMegaPixels: number;
+    readonly fboBytes: number;
+    readonly fboBudgetBytes: number;
+    /** Island phase census (the demand/retention state machine, design-004 §3/§7). */
+    readonly islands: {
+        readonly total: number;
+        readonly hot: number;
+        readonly warm: number;
+        readonly waking: number;
+        readonly cold: number;
+        readonly dormant: number;
+    };
+    /** Live targets per painted zoom band ("×1", "×0.5", …) — the LOD downgrade census. */
+    readonly bandHistogram: Readonly<Record<string, number>>;
+    /** This pass's shape (PassStats). */
+    readonly repainted: number;
+    readonly pendingPaints: number;
+    readonly evicted: number;
+    /** LOD context: camera zoom → hysteresis band → the DPR new paints get. */
+    readonly zoom: number;
+    readonly band: number;
+    readonly effectiveDpr: number;
+    /** Scene population: Visible vs Culled widgets (all surfaces). */
+    readonly visibleWidgets: number;
+    readonly culledWidgets: number;
 }
-export declare function GLViews({ engine, bridge, store, maxFboBytes, maxRepaintsPerFrame, environment, }: GLViewsProps): ReactElement;
+export declare function GLViews({ engine, bridge, store, maxFboBytes, maxRepaintsPerFrame, maxAnimationFps, maxPaintDpr, environment, onFrameStats, }: GLViewsProps): ReactElement;

package/dist/types/packages/r3f/src/gl-router.d.ts

@@ -56,5 +56,15 @@ export interface GLPointerRouterDeps {
 export interface GLPointerRouter {
     /** The adapter's `glRoute` seam. True = island content claimed the event. */
     route(kind: "down" | "move" | "up" | "cancel", screenX: number, screenY: number, native: PointerEvent): boolean;
+    /**
+     * Hover-time verdict as of the LAST routed `move` (design-002 §8 amendment,
+     * 2026-07-18): the pick chain under the pointer holds claim-capable island
+     * content — a mesh whose handlers include `onPointerDown`/`onClick` (the
+     * claim/click paths; hover-only handlers like the shapes swarm's move reader
+     * do NOT count — they never opt a down out). True for the whole life of an
+     * island capture. Feed it into the adapter's `GLRouteVerdict.overInteractive`
+     * on moves; presentation truth only, never a routing input.
+     */
+    overInteractive(): boolean;
 }
 export declare function createGLPointerRouter({ world, bridge, index }: GLPointerRouterDeps): GLPointerRouter;

package/dist/types/packages/r3f/src/index.d.ts

@@ -6,11 +6,12 @@
 export { createGLBridge, type GLBridge, type GLBridgeOpts, type IslandHandle, type IslandFrameCallback } from "./bridge";
 export { createIslandStateStore, type IslandRenderState, type IslandStateStore, type PaintedAt } from "./island-state";
 export { runCompositorPass, type CompCameraLike, type GlLike, type IslandCameraLike, type PassContext, type PassStats, type PoolLike, type QuadLike, type QuadsLike, type TargetLike, } from "./compositor-pass";
-export { GLViews, type GLViewsProps } from "./gl-root";
+export { GLViews, type GLViewsProps, type GlFrameStats } from "./gl-root";
 export { Island, type IslandProps } from "./island";
-export { IslandContext, useIslandContext, useIslandFrame, useIslandInvalidate, useIslandLift, type IslandContextValue, } from "./use-island-frame";
+export { IslandContext, useIslandContext, useIslandFrame, useIslandInvalidate, useIslandLift, useIslandOpacity, type IslandContextValue, } from "./use-island-frame";
 export { RenderTargetPool, type PoolEntryInfo } from "./pool";
 export { ResourceRegistry } from "./resource-registry";
 export { CompositeMaterial } from "./composite-material";
 export { createRenderWriteTrap, type RenderWriteTrap } from "./dev-write-trap";
 export { createGLPointerRouter, type GLPointerRouter, type GLPointerRouterDeps, type IslandPointerEvent, } from "./gl-router";
+export { captureWidgetPreviews, type CapturePreviewOpts } from "./preview-capture";

package/dist/types/packages/r3f/src/island-state.d.ts

@@ -39,14 +39,58 @@ export interface IslandRenderState {
      * every pass (5 Hot vs cap 4 froze the shapes card, 2026-07-12).
      */
     lastPaintSeq: number;
+    /**
+     * Animation time OWED to this island's `useIslandFrame` callbacks: every
+     * pass a Hot island is paint-eligible adds the pass dtMs; the paint that
+     * finally runs delivers the whole balance and zeroes it. Without this, a
+     * stagger-deferred island simply LOST the deferred passes' time — 5 Hot vs
+     * cap 4 ran every animation at 4/5 speed (2026-07-20 rate probe), violating
+     * design-004's "the cap changes cadence, never speed". Freeze semantics are
+     * preserved: frozen islands are not paint-eligible, so a stage hold still
+     * PAUSES animation rather than banking it.
+     */
+    pendingDtMs: number;
     /**
      * Composite-quad scale (lift-on-hold): scales the CARD on the canvas —
      * texture, rounded alpha corners and all — instead of the scene content
      * (which the card-sized frustum would crop into hard corners, 2026-07-12
      * field report). ≠1 also pops render order over neighbors.
+     *
+     * This is the DRAWN value: the compositor pass eases it toward
+     * `liftTarget` (dtMs-driven spring). GL widgets have no CSS transitions, so
+     * the DOM-lift parity (2026-07-13 field report: "GL lift snaps") lives in
+     * the pass, not in userland.
      */
     compositeScale: number;
+    /** Where the lift is headed; `setCompositeScale` retargets from the drawn value. */
+    liftTarget: number;
+    /** Drawn value at (re)target time — the ease runs liftFrom → liftTarget. */
+    liftFrom: number;
+    /** Accumulated pass dtMs since the last retarget; ≥ liftMs ⇒ settled. */
+    liftElapsedMs: number;
+    /** Transition duration in ms; 0 = snap (the pre-ease behavior). */
+    liftMs: number;
+    /**
+     * Composite-quad opacity channel (the lift's fade twin): the DRAWN value the
+     * pass eases toward `opacityTarget` and MULTIPLIES with the widget's durable
+     * `Opacity` cell — presentation-transient (chrome-grade, e.g. the drag-lift
+     * fade) stacked over the doc-level fact, never written to ECS.
+     */
+    compositeOpacity: number;
+    /** Where the fade is headed; `setCompositeOpacity` retargets from the drawn value. */
+    opacityTarget: number;
+    /** Drawn value at (re)target time — the ease runs opacityFrom → opacityTarget. */
+    opacityFrom: number;
+    /** Accumulated pass dtMs since the last retarget; ≥ opacityMs ⇒ settled. */
+    opacityElapsedMs: number;
+    /** Transition duration in ms; 0 = snap. */
+    opacityMs: number;
 }
+/**
+ * Default lift transition — the GL twin of the DOM card-lift idiom (180ms
+ * springy pop; the curve itself lives in the compositor pass).
+ */
+export declare const LIFT_DEFAULT_MS = 180;
 export interface IslandStateStore {
     /** Get-or-create (Cold, unpainted). */
     ensure(key: number): IslandRenderState;

package/dist/types/packages/r3f/src/preview-capture.d.ts

@@ -0,0 +1,19 @@
+import type { Texture, WebGLRenderer } from "three";
+export interface CapturePreviewOpts {
+    /** Types to capture (default: every registered gl-surface widget). */
+    readonly types?: readonly string[];
+    /**
+     * Shared IBL. Prefer the FACTORY form: PMREM textures live on the GPU of
+     * the renderer that generated them (no CPU image), so the app's main-canvas
+     * env is EMPTY on the capture renderer (field bug 2026-07-19 — black
+     * metals). The factory receives the capture renderer and builds the env
+     * there (e.g. `(gl) => new PMREMGenerator(gl).fromScene(new RoomEnvironment(), 0.04).texture`).
+     * A plain Texture is accepted for same-renderer/CPU-backed cases.
+     */
+    readonly environment?: Texture | ((gl: WebGLRenderer) => Texture | null) | null;
+    /** Pixel density of the capture (default: fit 512px on the long side, ≤2). */
+    readonly scale?: number;
+    /** Frames advanced before the capture (animations reach a live pose). */
+    readonly settleFrames?: number;
+}
+export declare function captureWidgetPreviews(opts?: CapturePreviewOpts): Promise<string[]>;

package/dist/types/packages/r3f/src/self-sustain.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Self-sustain scheduling for the demand loop (design-004 §3 animation-rate
+ * amendment, 2026-07-14).
+ *
+ * When the ONLY reason to run another frame is ambient animation (Hot islands
+ * or a stagger backlog), the loop no longer re-invalidates at native refresh:
+ * on a 120 Hz panel that was 5 always-Hot islands × 120 paints/sec ≈ 96 % GPU
+ * duty at idle — the fan. Instead the next pass is scheduled `1000/maxFps` ms
+ * after the last pass STARTED, so ambient animation runs at ~`maxFps` and the
+ * GPU idles between frames.
+ *
+ * What stays at native refresh:
+ *  - lift eases (`liftAnimating`) — 180 ms of interaction feedback;
+ *  - every EXTERNALLY invalidated frame (camera, drag, props dirt): the
+ *    bridge's `requestFrame` path is untouched, so interaction still runs at
+ *    display rate and Hot islands ride along uncapped while it lasts.
+ *
+ * The cap is approximate: the wake-up is a timeout and the actual frame lands
+ * on the next vsync after it. {@link RATE_CAP_SLACK_MS} pulls the timeout half
+ * a 120 Hz vsync early so the following vsync is the intended one, not one
+ * past it (naive `interval` scheduling on a 120 Hz grid yields 40 fps, not 60).
+ */
+/** Timeout lead so the post-timeout vsync lands on the target boundary. */
+export declare const RATE_CAP_SLACK_MS = 4;
+export interface SelfSustainStats {
+    readonly anyHot: boolean;
+    readonly pendingPaints: number;
+    readonly liftAnimating: boolean;
+}
+/**
+ * Decide how the demand loop continues after a pass.
+ *
+ * @param stats        The pass's self-sustain signals.
+ * @param elapsedMs    ms since the pass started (schedule anchor).
+ * @param maxFps       Animation rate cap; `Infinity` restores uncapped.
+ * @returns `"none"` (park), `"now"` (invalidate immediately), or the timeout
+ *          delay in ms before invalidating.
+ */
+export declare function selfSustainPlan(stats: SelfSustainStats, elapsedMs: number, maxFps: number): "none" | "now" | number;