@vibecook/ice 0.1.0 → 0.3.0

package/dist/types/packages/ground/src/passes/wires-collect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Wires collector — the pure ECS→triangles half of the wires pass. Port of
+ * the 2D-canvas wires reflector's drawing, kernel-tessellated:
+ *
+ * - Wire geometry NEVER reads a port ENTITY (design-001 §5.3): endpoints
+ *   resolve from the wire's `WireFrom`/`WireTo` widgets + `WirePorts` ids
+ *   against the type registry's static port schema (core `portSlots` — the
+ *   old local resolver's TODO, retired), so a CULLED endpoint still draws.
+ * - Cubics build in WORLD space then map control points through the kernel
+ *   `worldToScreen` seam — bezier curves are affine-invariant, so the mapped
+ *   cubic IS the screen curve — and `tessellateCubic` (0.25 px tolerance)
+ *   flattens with density that tracks zoom for free.
+ * - Connect preview: solid when snapped-compatible, dashed [6,4] otherwise
+ *   (dash placement from the tessellation's arc-length prefix).
+ * - Materialized port dots: triangle-fan discs, active color while any
+ *   connect drag is routed.
+ */
+import { type WirePreviewBuffer, type WiresConfig, type World } from "@ice/core";
+import type { GroundFrame } from "../pass";
+import { type TriSoup } from "./soup-collect";
+export declare const wireQ: import("@vibecook/strata-ecs").Query;
+export declare const geometryQ: import("@vibecook/strata-ecs").Query;
+export declare const measuredQ: import("@vibecook/strata-ecs").Query;
+export declare const selectedQ: import("@vibecook/strata-ecs").Query;
+export declare const portQ: import("@vibecook/strata-ecs").Query;
+export declare const routedConnectQ: import("@vibecook/strata-ecs").Query;
+/** A live connect drag moves the preview every frame — Drag value dirt covers it. */
+export declare const connectDragQ: import("@vibecook/strata-ecs").Query;
+/** Nav churn signal: Active membership flips re-collect (scope filter below). */
+export declare const activeQ: import("@vibecook/strata-ecs").Query;
+export declare function collectWires(world: World, frame: GroundFrame, config?: WiresConfig, preview?: WirePreviewBuffer): TriSoup;

package/dist/types/packages/ground/src/passes/wires.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Wires pass — the three-side wrapper over the pure `collectWires` (renders
+ * above the grid, below the guides, matching the old P0 canvas order).
+ * Dirt mirrors the old 2D reflector's observers; the connect preview rides
+ * `[RoutedConnect, Drag]` value dirt (the buffer updates exactly when the
+ * connect recognizer's Drag advances) instead of a per-frame value diff.
+ */
+import { type WirePreviewBuffer, type WiresConfig } from "@ice/core";
+import type { GroundPass } from "../pass";
+export declare function createWiresPass(initial?: Partial<WiresConfig>, readPreview?: () => WirePreviewBuffer): GroundPass;

package/dist/types/packages/ground/src/renderer.d.ts

@@ -0,0 +1,15 @@
+import type { Camera, Scene } from "three/webgpu";
+/** The layer's renderer seam — tests inject a fake (compositor `GlLike` precedent). */
+export interface GroundRendererLike {
+    readonly canvas: HTMLCanvasElement;
+    ready(): boolean;
+    failed(): boolean;
+    /** Register a one-shot "became ready" callback (fires immediately if already ready). */
+    onReady(cb: () => void): void;
+    setSize(cssW: number, cssH: number, dpr: number): void;
+    render(scene: Scene, camera: Camera): void;
+    dispose(): void;
+}
+export declare function createGroundRenderer(doc: Document, opts?: {
+    forceWebGL?: boolean;
+}): GroundRendererLike;

package/dist/types/packages/ice/src/ground.d.ts

@@ -0,0 +1 @@
+export * from "../../ground/src/index";

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

@@ -29,6 +29,21 @@ export declare function cubicPoint(c: Cubic, t: number): Vec2;
  * culling/picking prefilters.
  */
 export declare function cubicAABB(c: Cubic): AABB;
+export interface Tessellation {
+    /** Flattened polyline, interleaved [x0,y0, x1,y1, …] in the cubic's own space. */
+    points: Float32Array;
+    /** Cumulative arc length at each polyline point (same unit; [0] = 0). */
+    arcLength: Float32Array;
+}
+/**
+ * Adaptive cubic flattening + prefix arc length (2026-07-16, the @ice/ground
+ * wires pass: stroke tessellation and dash placement both ride this). Emit
+ * density follows curvature — flat spans emit one segment regardless of
+ * length; tolerance is in the cubic's OWN space (the ground renderer passes
+ * screen-px cubics with ~0.25 px tolerance, so density tracks zoom for free).
+ * `maxDepth` bounds pathological inputs (2^depth segments worst case).
+ */
+export declare function tessellateCubic(c: Cubic, tolerance?: number, maxDepth?: number): Tessellation;
 /** Distance from a point to a line segment. */
 export declare function distanceToSegment(px: number, py: number, ax: number, ay: number, bx: number, by: number): number;
 /**

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

@@ -26,6 +26,21 @@ export declare function worldToScreen(worldX: number, worldY: number, camera: Ca
  * Returns the new camera (does not mutate). Clamping is the caller's policy.
  */
 export declare function zoomAtPoint(camera: CameraState, screenX: number, screenY: number, newZoom: number): CameraState;
+/**
+ * The DEFAULT framing camera (2026-07-18, James: "do zoom to fit, but with a
+ * upper and bottom cap … should feel natural"): zoom-to-fit `content` (a
+ * world-space bbox) with `pad` px of breathing room on every side, zoom
+ * clamped into [minZoom, maxZoom] — the natural band: never so far in that
+ * one small card fills the screen, never so far out that the board turns
+ * into an ant farm. The content CENTER stays centered whether or not a cap
+ * engages. Callers own the band policy (engine default: FIT_DEFAULTS ∩ the
+ * session's hard CameraLimits) and must pass a real viewport.
+ */
+export declare function fitCamera(content: Rect, vpW: number, vpH: number, opts: {
+    pad: number;
+    minZoom: number;
+    maxZoom: number;
+}): CameraState;
 /**
  * Camera → the ONE per-plane CSS transform (design-002 §5 `planeTransform`).
  * Children are laid out in WORLD units inside the plane (left/top = world x/y),

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

@@ -0,0 +1,11 @@
+/**
+ * CSS-style cubic-bezier timing functions (pure math — kernel).
+ *
+ * `cubicBezierEase(x1, y1, x2, y2)` builds f(t): the exact curve CSS
+ * `transition-timing-function: cubic-bezier(…)` runs, so GL surfaces can
+ * match DOM transitions beat-for-beat (the composite-quad lift mirrors the
+ * DOM card lift's spring, cubic-bezier(0.2, 0.9, 0.3, 1.2)). y outside [0,1]
+ * (overshoot springs) is legal and expected; x1/x2 are clamped to [0,1] per
+ * spec so x(u) stays monotone and invertible.
+ */
+export declare function cubicBezierEase(x1: number, y1: number, x2: number, y2: number): (t: number) => number;

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

@@ -11,3 +11,6 @@ export * from "./zoom-bands";
 export * from "./eviction";
 export * from "./anchors";
 export * from "./bezier";
+export * from "./easing";
+export * from "./nav-flight";
+export * from "./layout";

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";