@vibecook/ice 0.1.0

package/dist/types/packages/dom/src/pointer-adapter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The real L0 pointer adapter (design-003 §2–§3; replaces the M3 demo-input scaffold).
+ *
+ * Translates DOM pointer / wheel / keyboard events into normalized `InputEvent`s
+ * and ONLY enqueues them (Law 2: adapters enqueue, they never touch the world —
+ * this file imports no ECS state and writes nothing). `pointerIngest` drains the
+ * queue once per tick and turns the facts into world state.
+ *
+ * Details that matter:
+ *  - stable pointer ids: `"mouse"` for the one mouse, `"touch:<pointerId>"` per
+ *    contact, `"pen"` — ingest keys pointer entities off these (design-003 §2);
+ *  - container-relative CSS px (the kernel screen space) via getBoundingClientRect;
+ *  - `setPointerCapture` on down so a drag keeps delivering outside the element;
+ *  - Space is the pan modifier (design-003 §4.4): tracked here and threaded onto
+ *    every event's `mods.space`; keydown/keyup emit a `key` fact only when the
+ *    modifier tuple actually changes, and Space `preventDefault`s to stop page scroll;
+ *  - wheel `preventDefault`s: a ctrl-wheel / trackpad pinch becomes `wheel.pinch`
+ *    (the zoom signal), a plain wheel becomes dx/dy (deltaMode lines → px ×16);
+ *  - window blur enqueues a synthetic `cancel` for every pointer still down
+ *    (design-003 §8) — the browser will not send the pointerups.
+ *
+ * Widget opt-out (the pinned widget-event contract, design-002 §8 / design-004 §4):
+ * on `pointerdown` ONLY, if the event's target chain (up to the container) crosses
+ * a native interactive (input/textarea/select/button/a[href]/contenteditable/
+ * media[controls]) or an explicit `[data-canvas-interactive]`, the down fact is
+ * flagged `surfaceHandled: true` — the fact still lands (the one input path is
+ * absolute), but recognizer-spawn/arbitration skip it (`HandledByWidget` flows
+ * through L0). `stopPropagation()` inside widget content is the OTHER boundary:
+ * a stopped event never reaches the container listener, so it never becomes a
+ * canvas fact at all — that is the design, not a gap.
+ */
+import { type InputQueue } from "@ice/core";
+import type { CanvasHost } from "./host";
+/**
+ * The router GL path's adapter seam (design-004 §4). The GL plane is
+ * `pointer-events: none` — its events land HERE, and the injected router
+ * (built by @ice/r3f; the adapter stays ECS-free) performs the synchronous
+ * point-pick + island raycast + synthetic dispatch at event time. Returning
+ * `true` means island content claimed the event (stopPropagation'd or held
+ * under island capture): the fact still lands — flagged `surfaceHandled`, so
+ * recognizers skip it via `HandledByWidget` — the same contract as the
+ * native-interactive opt-out.
+ */
+export type GLRoute = (kind: "down" | "move" | "up" | "cancel", screenX: number, screenY: number, native: PointerEvent) => boolean;
+export interface PointerAdapterOpts {
+    readonly glRoute?: GLRoute;
+}
+export declare function attachPointerAdapter(host: CanvasHost, queue: InputQueue, opts?: PointerAdapterOpts): () => void;

package/dist/types/packages/dom/src/reflectors/chrome.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The chrome reflector (design-004 §5 chrome plane P4; post-notify, SCREEN-space).
+ *
+ * Draws the engine's pooled chrome entities plus the out-of-ECS marquee buffer
+ * into a dedicated, non-transformed overlay plane above the content plane:
+ *  - each `SelectionBox` entity → a 1px outline rect (its world x,y,w,h mapped to
+ *    screen via `worldToScreen` × zoom);
+ *  - each `HandleSpec` entity → an 8×8 screen-px square CENTERED on the handle's
+ *    world AABB center (the handle's world size is zoom-scaled for picking; the
+ *    drawn size is screen-constant);
+ *  - the `marqueeBuffer.rect` (world) → a rect while non-null.
+ *
+ * P4 is screen-space by design (design-004 §2 rescope): unlike the content plane
+ * (one camera transform), chrome is recomputed per camera change — small N. This
+ * reflector therefore reads the `Camera` resource directly (an acknowledged
+ * small-N screen-space camera consumer).
+ *
+ * `always: true`, not observer-driven: the marquee buffer has no ECS stamp to
+ * observe, so the reflector must get a chance every frame. A cheap early-out
+ * keeps it idle-free — it returns immediately when there is nothing to draw AND
+ * nothing was drawn last frame (so a cleared selection still gets one flush to
+ * remove its nodes). Style writes are change-only (per-node geometry cache) and
+ * counted by `writes()` — the churn instrument, mirroring the other reflectors.
+ *
+ * Law 10: reflectors write output only, never read layout or write ECS — this
+ * flush touches only the overlay plane's node styles.
+ */
+import { type MarqueeBuffer, type ReflectorDef, type World } from "@ice/core";
+import type { CanvasHost } from "../host";
+export declare function createChromeReflector(host: CanvasHost, _world: World, marqueeBuffer: MarqueeBuffer): ReflectorDef & {
+    writes(): number;
+    dispose(): void;
+};

package/dist/types/packages/dom/src/reflectors/cursor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The cursor reflector (design-003 §7 L4 cursor projection; v1 approach:
+ * local cursor = OS cursor via one `style.cursor` write).
+ *
+ * `createCursorSync` resolves the cursor string into closure state every
+ * `derive` tick with no observable ECS stamp (a plain string, not a
+ * component/resource write), so there is nothing for `observe` to watch —
+ * hence `always: true` with an internal last-value cache, mirroring the
+ * "cheap-overlay style" carve-out `ReflectorDef.always` exists for. The cache
+ * is what keeps the write ONE-per-change: `flush` runs every frame, but
+ * `host.container.style.cursor` is only touched when `readCursor()` differs
+ * from the last-applied value.
+ *
+ * Law 10: reflectors run post-notify, write output only, never read layout
+ * or write ECS — this flush touches only `host.container.style`.
+ */
+import type { ReflectorDef } from "@ice/core";
+import type { CanvasHost } from "../host";
+export declare function createCursorReflector(host: CanvasHost, readCursor: () => string): ReflectorDef & {
+    writes(): number;
+};

package/dist/types/packages/dom/src/reflectors/dom-widgets.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The DOM widget HOST reflector (design-004 §2 host pipeline; design-002 §5
+ * `domWidgets`).
+ *
+ * This is the reflector-owned HALF of the widget runtime: it reconciles a host
+ * `<div>` per mounted widget against the engine's mount store and paints its
+ * world-unit geometry. The OTHER half — the React portal list — is owned by a
+ * hook subscribed to the SAME store (design-004 §2, decision 3); this file never
+ * touches React. Each host carries an inner `data-ice-content` element that the
+ * portal targets, so the two halves meet only at that node.
+ *
+ * Store, not query: membership (enter/exit) and the culled-but-kept-mounted
+ * `hidden` flag are ENGINE-side decisions (cull + keep-mounted LRU, mount-store.ts)
+ * published through a `useSyncExternalStore` snapshot. That store has NO ECS stamp
+ * for a reflector `observe` to watch, so — like the cursor reflector — this one is
+ * `always: true` and does its own cheap dirt detection:
+ *  - **membership**: `store.getSnapshot()` identity is O(1); the snapshot changes
+ *    IFF membership or a hidden flag changed, so an unchanged snapshot skips the
+ *    reconcile entirely;
+ *  - **geometry**: a private observer on `[Position, Size]` sets a dirty flag, so
+ *    the (change-only) geometry pass runs only when a widget actually moved/resized
+ *    — a still scene touches no DOM. Effective size is `MeasuredSize` where present
+ *    and non-zero, else `Size` (design-004 §2). (MeasuredSize changes ride a
+ *    dedicated observer; the note below is historical:
+ *    picked up on the next Position/Size stamp or membership change; the ResizeObserver
+ *    measurement path — a later slice — will arm its own dirt.)
+ *  - **drag-promote** (P3): a private observer on `[Grab]` membership sets a dirty
+ *    flag; a host whose entity holds `Grab` re-parents content→lifted plane and back
+ *    on release. Re-parenting MOVES the host node (with its content child), which
+ *    PRESERVES the React portal — the portal targets the content node, and moving a
+ *    portal's container node does not remount it, so widget React state survives the
+ *    lift. While ANY host is lifted, every host's content element is inerted
+ *    (`pointer-events: none`, the pinned inert-during-drag contract, design-004 §4).
+ *
+ * Law 10: reflectors run post-notify, write output only, never read layout or
+ * write ECS — this flush touches only host `<div>` style/attributes/parentage.
+ */
+import { type Entity, type ReflectorDef, type WidgetMountStore, type World } from "@ice/core";
+/** The two planes a host can live in (design-004 §1: P1 content, P3 lifted). */
+export interface DomWidgetsHost {
+    readonly contentPlane: HTMLElement;
+    readonly liftedPlane: HTMLElement;
+}
+export interface DomWidgetsReflector extends ReflectorDef {
+    /** The entity's content element (the `data-ice-content` portal target), or undefined if not hosted. */
+    hostFor(entity: Entity): HTMLElement | undefined;
+    /** Live host count (= mounted widgets, visible + kept-mounted). */
+    hostCount(): number;
+    /** Geometry writes so far — one per enter, one per changed host, zero for unchanged (churn instrument). */
+    geometryWrites(): number;
+    /** Tear down the private observers (call when unregistering the reflector before the world dies). */
+    dispose(): void;
+}
+export declare function createDomWidgetsReflector(host: DomWidgetsHost, world: World, store: WidgetMountStore): DomWidgetsReflector;

package/dist/types/packages/dom/src/reflectors/graybox.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The gray-box reflector (design-002 §5 reflector doctrine; M3 exit gate).
+ *
+ * A minimal enter/update/exit reconciler: it mirrors every `Position` + `Size`
+ * entity to an absolutely-positioned div inside the content plane, laying each
+ * out in WORLD units (`left/top/width/height` in world coordinates) — the
+ * plane's single camera transform (see plane-transform.ts) does the screen
+ * mapping, so this reflector never touches the camera and never reads layout
+ * (Law 10). It is the stand-in for real widget rendering until the widget
+ * runtime lands (M4+); "gray box" = deterministic per-entity fill, no content.
+ *
+ * Reconciliation, dirty-driven on the `Position`/`Size` query (design-002 §5):
+ *  - enter: create a div (fill hashed from the entity handle), write geometry,
+ *    stage it in a DocumentFragment (one plane append per flush — 10k mounts do
+ *    not thrash layout);
+ *  - update: compare against a per-entity geometry cache and rewrite ONLY the
+ *    entities whose world geometry actually changed;
+ *  - exit: remove divs for entities absent from this flush.
+ *
+ * `styleWrites()` counts entities whose geometry was (re)written this flush (one
+ * per enter, one per changed entity, zero for unchanged) — the churn instrument
+ * the M3 tests assert: change one entity ⇒ exactly one style write. `nodeCount()`
+ * is the live div count. Because the reflector is dirty-driven, a static frame
+ * does not flush at all, so neither counter moves.
+ */
+import { type ReflectorDef } from "@ice/core";
+import type { CanvasHost } from "../host";
+export declare function createGrayboxReflector(host: CanvasHost): ReflectorDef & {
+    styleWrites(): number;
+    nodeCount(): number;
+};

package/dist/types/packages/dom/src/reflectors/grid.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The grid reflector (design-004 §1 P0 ground plane; M6).
+ *
+ * Ports v1's dot-grid shader VERBATIM from
+ * `../../../infinite-canvas/packages/infinite-canvas/src/webgl/renderers/GridRenderer.ts`:
+ * the fragment shader body (world reconstruction from `gl_FragCoord`, three
+ * fade-staged spacing levels, max-composited anti-aliased dots) is copied
+ * unchanged from GridRenderer.ts:45-115, and `DEFAULT_GRID_CONFIG` from
+ * GridRenderer.ts:27-35. v1 drove this through three.js (`ShaderMaterial` +
+ * `WebGLRenderer`), but `@ice/dom` may not import three (the `dom-only-core-
+ * kernel` cruiser rule: core + kernel only) — so this reflector talks to a raw
+ * WebGL2/WebGL1 context directly. Same GLSL, same uniforms, same math; only the
+ * plumbing that fed them (three's abstractions) is gone. The vertex shader is
+ * simplified from a vec3 attribute (three's default) to vec2 — geometry only,
+ * no shading logic, so "verbatim" is unaffected.
+ *
+ * P0 is a WebGL `<canvas>` mounted as the FIRST child of the host container
+ * (design-004 §1: "ground" sits under P1's content-DOM). It is sized to the
+ * container's CSS box × devicePixelRatio via a ResizeObserver — its own,
+ * independent hit-path; the reflector's `flush` never reads layout (Law 10),
+ * only the RO callback does, and only in response to the browser's own resize
+ * notification. Camera uniforms (world top-left + zoom) come from the `Camera`
+ * RESOURCE, mirroring plane-transform.ts's `observe` pattern; unlike P1's
+ * single CSS transform, this plane recomputes per-pixel in the shader — the
+ * world is regenerated from `gl_FragCoord` every draw, so there are no seams
+ * at any zoom/pan.
+ *
+ * Fault isolation, locally too: `getContext` returns `null` in headless/happy-
+ * dom (jsdom/happy-dom implement `<canvas>` but not WebGL) — `available()`
+ * reports that, and `flush()` is a permanent, silent no-op. GL setup and every
+ * draw call are wrapped so a driver/context-loss failure degrades to
+ * `available() === false` rather than a throwing reflector (the registry has
+ * its own fault isolation — a skipped frame on throw — but a reflector that
+ * throws every single frame is still noise, design-002 §5).
+ */
+import { type ReflectorDef } from "@ice/core";
+export interface GridConfig {
+    /** World-unit spacings for up to 3 grid levels [fine, medium, coarse]. */
+    spacings: [number, number, number];
+    /** Dot RGB color as [r, g, b] in 0-1 range. */
+    dotColor: [number, number, number];
+    /** Base dot opacity multiplier (0-1). */
+    dotAlpha: number;
+    /** CSS-pixel range where a grid level fades in: [start, end]. */
+    fadeIn: [number, number];
+    /** CSS-pixel range where a grid level fades out: [start, end]. */
+    fadeOut: [number, number];
+    /** Dot radius range in CSS pixels [min, max]. Scaled by DPR internally. */
+    dotRadius: [number, number];
+    /** Per-level opacity weight: level i gets (base + i * step). */
+    levelWeight: [number, number];
+}
+/** Verbatim from GridRenderer.ts:27-35 (tuned to match Apple Freeform / FigJam). */
+export declare const DEFAULT_GRID_CONFIG: GridConfig;
+interface GridHost {
+    readonly container: HTMLElement;
+}
+export declare function createGridReflector(host: GridHost, opts?: Partial<GridConfig>): ReflectorDef & {
+    available(): boolean;
+    dispose(): void;
+    configure(next: Partial<GridConfig>): void;
+};
+export {};

package/dist/types/packages/dom/src/reflectors/plane-transform.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The plane-transform reflector (design-002 §5 `planeTransform`; M3 exit gate,
+ * widened for the M6 lifted plane).
+ *
+ * Observes the `Camera` RESOURCE and nothing else. Each flush reads the camera,
+ * derives the ONE per-plane CSS transform via kernel `planeCssTransform` (the
+ * sole owner of that math — Law 13), and writes it to EVERY camera-transformed
+ * DOM plane in a SINGLE `style.transform` assignment each. Panning the whole
+ * canvas is therefore O(1) in the DOM: one transform write per plane per moving
+ * frame, independent of node count — the property that makes an infinite canvas
+ * of 10k gray boxes pan at frame rate.
+ *
+ * The input is widened to `{ contentPlane; liftedPlane? }` (design-004 §1: P1 +
+ * P3 share the one camera). A `CanvasHost` still satisfies it structurally, so
+ * M3 callers are unchanged; M6 passes both planes and the lifted plane (P3)
+ * tracks the content plane (P1) exactly, so a promoted widget keeps its world
+ * position across the content→lifted re-parent.
+ *
+ * `transformWrites()` is the M3 instrument: because the reflector is dirty-
+ * driven on the Camera resource (equality-suppressed — design-002 §5), a static
+ * camera flushes zero times and the counter stays flat; every distinct camera
+ * value bumps it exactly once. The frame-contract tests assert both halves.
+ *
+ * Law 10: reflectors run post-notify, write output only, and NEVER read layout
+ * or write ECS — this flush touches only `host.contentPlane.style`.
+ */
+import { type ReflectorDef } from "@ice/core";
+/**
+ * The camera-transformed DOM plane(s). A `CanvasHost` satisfies this
+ * structurally (M3 backward compat); M6 passes `liftedPlane` too so P3 tracks P1.
+ */
+export interface CameraPlanes {
+    readonly contentPlane: HTMLElement;
+    readonly liftedPlane?: HTMLElement;
+}
+export declare function createPlaneTransformReflector(host: CameraPlanes): ReflectorDef & {
+    transformWrites(): number;
+};

package/dist/types/packages/dom/src/reflectors/remote-cursors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * P5 — remote cursors (design-004 §1: screen-space DOM, "remote cursors are
+ * always custom nodes"; design-003 §7).
+ *
+ * Renders one pooled node per REMOTE cursor entity (`CursorVisual` kind
+ * "remote" + world `Position`, derived by core's remote-cursors system from
+ * presence peers; `Follows` names the peer whose `PresenceInfo` supplies
+ * color + label). Screen-space by design: an acknowledged small-N
+ * camera→position consumer (design-002 §5 rescope), recomputed on camera or
+ * cursor dirt only. The plane mounts LAST in the container, above chrome;
+ * `pointer-events: none` throughout — cursors are never hit-testable.
+ */
+import { type ReflectorDef, type World } from "@ice/core";
+import type { CanvasHost } from "../host";
+export interface RemoteCursorsReflector {
+    readonly reflector: ReflectorDef;
+    /** Remove the plane + pool (doc close / HMR). */
+    destroy(): void;
+}
+export declare function createRemoteCursorsReflector(host: CanvasHost, world: World): RemoteCursorsReflector;

package/dist/types/packages/dom/src/reflectors/wires.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The wires reflector (design-004 §1 P0 "WIRES" pass; design-001 §5.3).
+ *
+ * P0 is the ground stratum: the grid canvas paints first, the wires canvas next
+ * (this file), the content plane on top. Wires therefore render UNDER widget
+ * content — a node graph's edges sit behind its nodes — with no z-index
+ * bookkeeping: the wires canvas is inserted immediately before the content plane
+ * (after the grid canvas), so DOM order is the strata order (§1: stacking is
+ * stratified). Like the grid, it is a SCREEN-space canvas covering the full
+ * viewport; the camera is applied per-draw via the kernel `worldToScreen` seam
+ * rather than by a CSS plane transform, so panning re-strokes the curves at any
+ * zoom with no seams.
+ *
+ * Wire geometry NEVER reads a port ENTITY (design-001 §5.3): endpoints resolve
+ * from the wire's `WireFrom`/`WireTo` widgets (durable `Position`/`Size`) and the
+ * two `WirePorts` ids looked up against the widget type's static port schema
+ * (`PrefabId` -> `widgets.get(type).ports`); the kernel `portAnchor` places each
+ * anchor on the widget rect and `wireCubic` builds the curve. Because that path
+ * touches only durable geometry + the type registry — never a runtime port
+ * entity — a wire whose endpoint is CULLED (off-viewport, no DOM host, no
+ * materialized port) still draws by construction. This mirrors core's audited
+ * `systems/l1-wires.ts` endpoint resolver, so pick and render agree. The connect-
+ * drag preview and the materialized port dots share this one canvas.
+ *
+ * Change-only (design-002 §5): the reflector is `always: true` (the connect
+ * preview is an out-of-ECS buffer with no ECS stamp, exactly like the marquee
+ * buffer the chrome reflector consumes), but a full re-stroke happens only when
+ * something visible changed — private observers on Camera / [Position,Size] /
+ * [Wire] / [Selected] / ports / [RoutedConnect] arm a dirty flag, and the preview
+ * buffer is diffed by value each frame. A static scene with an idle preview
+ * re-strokes zero times after first paint.
+ *
+ * Fault isolation mirrors the grid: `getContext("2d")` returns `null` in happy-
+ * dom (and on context loss), so `available()` reports false and `flush` is a
+ * permanent silent no-op; every draw is wrapped so a driver failure degrades to
+ * unavailable rather than a throwing reflector (design-002 §5).
+ *
+ * Law 10: reflectors run post-notify, write output only, never read layout or
+ * write ECS — this flush touches only the wires canvas 2D context.
+ */
+import { type ReflectorDef, type World } from "@ice/core";
+import type { CanvasHost } from "../host";
+/**
+ * The connect-drag preview buffer (structural mirror of the core
+ * `WirePreviewBuffer` the graph-systems slice produces in
+ * `core/src/systems/l3-connect.ts`, exposed on `installInteractionStack` as
+ * `wirePreview`). Coords are WORLD-space; `active` gates drawing; `compatible`
+ * picks solid (snapped to a compatible port) vs dashed (free / incompatible).
+ *
+ * TODO(integration): once core exports its buffer type, import it here and drop
+ * this local — the lead reconciles field names if they diverge.
+ */
+export interface WirePreview {
+    /** Source anchor (world). */
+    sx: number;
+    sy: number;
+    /** Target / cursor (world). */
+    tx: number;
+    ty: number;
+    active: boolean;
+    compatible: boolean;
+}
+/** Minimal-neutral wire styling (design-004 §6 chrome is subdued; wires defer to content). */
+export interface WiresConfig {
+    /** Default wire stroke (CSS color). */
+    wireColor: string;
+    /** Accent stroke for a Selected wire. */
+    selectedColor: string;
+    wireWidth: number;
+    selectedWidth: number;
+    /** Materialized-port dot radius (CSS px) + colors (idle vs during a connect drag). */
+    portRadius: number;
+    portColor: string;
+    portActiveColor: string;
+}
+export declare const DEFAULT_WIRES_CONFIG: WiresConfig;
+export interface WiresReflector extends ReflectorDef {
+    /** False under happy-dom / on context loss — flush is then a silent no-op. */
+    available(): boolean;
+    /** Full re-stroke count (the churn instrument): one per frame that actually redrew, zero on a static idle scene. */
+    redraws(): number;
+    /** Detach the canvas + tear down the private observers and ResizeObserver. */
+    dispose(): void;
+}
+export declare function createWiresReflector(host: CanvasHost, world: World, opts?: {
+    readPreview?: () => WirePreview;
+    config?: Partial<WiresConfig>;
+}): WiresReflector;

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * Port-anchor math (design-001 §5.3): wire geometry NEVER reads port entities —
+ * anchors are pure functions over the widget rect + the port declaration, so
+ * culled endpoints work by construction.
+ */
+import type { Rect, Vec2 } from "./shapes";
+export type PortSide = "n" | "e" | "s" | "w";
+export interface PortSlot {
+    side: PortSide;
+    /** 0-based position among the ports sharing this side. */
+    index: number;
+    /** Total ports on this side. */
+    count: number;
+}
+/** World-space anchor point: ports distribute evenly along their side. */
+export declare function portAnchor(widget: Rect, slot: PortSlot): Vec2;
+/** Outward unit direction of a side (wire tangent stubs, Y-down world). */
+export declare function sideDirection(side: PortSide): Vec2;

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

@@ -0,0 +1,38 @@
+/**
+ * Cubic-bezier wire geometry: construction from port anchors, conservative
+ * AABB (for the spatial index), and sampled distance (for picking — wires rank
+ * below widgets, design-003 §3).
+ */
+import { type PortSide } from "./anchors";
+import type { AABB, Vec2 } from "./shapes";
+export interface Cubic {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x3: number;
+    y3: number;
+}
+/**
+ * Wire curve between two anchors: tangent stubs leave each port along its
+ * side's outward direction, scaled with distance (min stub keeps short wires
+ * readable).
+ */
+export declare function wireCubic(from: Vec2, fromSide: PortSide, to: Vec2, toSide: PortSide, stubScale?: number, minStub?: number): Cubic;
+/** Point on the curve at t ∈ [0, 1] (Bernstein form). */
+export declare function cubicPoint(c: Cubic, t: number): Vec2;
+/**
+ * Conservative bounds: the control-point hull contains the curve (convex-hull
+ * property). Cheap and index-friendly; exact extrema are unnecessary for
+ * culling/picking prefilters.
+ */
+export declare function cubicAABB(c: Cubic): AABB;
+/** 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;
+/**
+ * Min distance from a point to the curve via polyline sampling. 32 samples is
+ * ample for hit thresholds of a few px; error shrinks with curve flatness.
+ */
+export declare function distanceToCubic(px: number, py: number, c: Cubic, samples?: number): number;

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

@@ -0,0 +1,67 @@
+/**
+ * THE coordinate seam (Law 13): every conversion between screen, world, and
+ * island (widget-local GL) space lives here — including the ONE Y-flip.
+ * v1 duplicated this math in three places; nothing outside this module may
+ * re-derive it.
+ *
+ * Conventions:
+ * - screen: CSS px, canvas-container-relative, Y-down. DPR never enters world
+ *   math (it exists only in GL uniforms / FBO sizing — see zoom-bands).
+ * - world:  world units, Y-down. `Camera.{x,y}` is the WORLD point at the
+ *   viewport's top-left; `zoom` is screen px per world unit.
+ * - island: widget-local GL space — CENTER origin, Y-UP, world-unit scale.
+ *   (v1 VirtualWidget convention; the only Y-flip in the codebase.)
+ */
+import type { Rect, Vec2 } from "./shapes";
+export interface CameraState {
+    x: number;
+    y: number;
+    zoom: number;
+}
+export declare function screenToWorld(screenX: number, screenY: number, camera: CameraState): Vec2;
+export declare function worldToScreen(worldX: number, worldY: number, camera: CameraState): Vec2;
+/**
+ * Zoom about a fixed screen point (v1 `zoomAtPoint`): the world point under
+ * `(screenX, screenY)` stays under it after the zoom change.
+ * 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;
+/**
+ * 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),
+ * the plane carries `transform: translate(tx px, ty px) scale(scale)` with
+ * `transform-origin: 0 0` — so a child at world point p lands at
+ * `p·zoom + t = (p − camera)·zoom`, i.e. exactly `worldToScreen(p)`.
+ */
+export declare function planeCssTransform(camera: CameraState): {
+    tx: number;
+    ty: number;
+    scale: number;
+};
+/** World → island (center-origin, Y-up). THE Y-flip, direction one. */
+export declare function worldToIsland(worldX: number, worldY: number, widget: Rect): Vec2;
+/** Island → world. THE Y-flip, direction two. */
+export declare function islandToWorld(islandX: number, islandY: number, widget: Rect): Vec2;
+/**
+ * Camera → the P2 composite ortho frustum + camera position (world units,
+ * Y-up scene). `left/top` pin the viewport's top-left to `Camera.{x,y}`
+ * exactly like `planeCssTransform` does for the DOM planes: the frustum spans
+ * `viewport / zoom` world units and the camera sits at the world origin
+ * offset, so a quad at `worldRectToComposite(rect)` lands on the same screen
+ * pixels as a DOM host at `rect` under the plane transform.
+ */
+export declare function compositeCameraFrustum(camera: CameraState, viewportW: number, viewportH: number): {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    x: number;
+    y: number;
+};
+/** World rect → composite-quad center + scale in the Y-up P2 scene. */
+export declare function worldRectToComposite(rect: Rect): {
+    x: number;
+    y: number;
+    sx: number;
+    sy: number;
+};

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

@@ -0,0 +1,23 @@
+/**
+ * FBO-pool eviction policy — ported from v1 `eviction.ts` (pure part of the
+ * pool). Priority: Cold(0) < Warm(1) < Dormant(2); LRU within a phase;
+ * Hot/Waking are never evicted even under an impossible budget.
+ */
+export type IslandPhase = "Hot" | "Warm" | "Waking" | "Cold" | "Dormant";
+export interface EvictionCandidate<Id> {
+    id: Id;
+    phase: IslandPhase;
+    bytes: number;
+    lastUsedMs: number;
+}
+/**
+ * The island phase truth table (design-004 §3; v1 `computePhase` verbatim —
+ * RFC-002 pinned it with tests). `active` is the nested-canvas membership
+ * signal (always true until M8); `hasFbo` splits Warm (retained texture,
+ * composite-ready) from Waking (must paint before compositing) — after an
+ * eviction a re-entering island comes back as Waking, after a plain cull
+ * round-trip it comes back Warm from the retained texture.
+ */
+export declare function computeIslandPhase(active: boolean, visible: boolean, animating: boolean, hasFbo: boolean): IslandPhase;
+/** Ordered ids to release so total bytes ≤ budget. Pure. */
+export declare function selectEvictions<Id>(candidates: EvictionCandidate<Id>[], totalBytes: number, maxBytes: number): Id[];

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

@@ -0,0 +1,13 @@
+/**
+ * @ice/kernel — pure math. Plain structs in, plain structs out.
+ * Import wall: nothing but `rbush` (named exception — zero-dep R-tree).
+ */
+export declare const KERNEL_VERSION = "0.0.0";
+export * from "./shapes";
+export * from "./coords";
+export * from "./snap";
+export * from "./spatial-index";
+export * from "./zoom-bands";
+export * from "./eviction";
+export * from "./anchors";
+export * from "./bezier";

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

@@ -0,0 +1,22 @@
+/** Plain geometric structs shared across the kernel. Ported from v1 `ecs/math.ts`. */
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface AABB {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export declare function rectToAABB(r: Rect): AABB;
+export declare function aabbToRect(a: AABB): Rect;
+export declare function intersectsAABB(a: AABB, b: AABB): boolean;
+export declare function pointInAABB(px: number, py: number, a: AABB): boolean;
+export declare function clamp(value: number, min: number, max: number): number;