@xenolithengine/graph-render-pixi 0.7.0-beta.0

package/dist/viewport-math.d.ts

@@ -0,0 +1,68 @@
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+export interface ViewportState {
+    /** World origin x-position in screen coordinates. */
+    x: number;
+    /** World origin y-position in screen coordinates. */
+    y: number;
+    /** Scale factor: 1 = 1:1, 2 = zoomed in 2× (each world unit takes 2 screen pixels). */
+    zoom: number;
+}
+export type ZoomBounds = readonly [min: number, max: number];
+export declare function screenToWorld(screen: Vec2, v: ViewportState): Vec2;
+export declare function worldToScreen(world: Vec2, v: ViewportState): Vec2;
+export declare function clampZoom(zoom: number, min: number, max: number): number;
+/**
+ * Focal zoom: scale by `factor` while keeping the world point currently under `focalScreen`
+ * anchored to that same screen point. The classic UE / Figma / VSCode-canvas zoom feel.
+ *
+ *   world_after = (screen - x') / zoom'
+ *   require: world_after === world_before for screen === focalScreen
+ *   solving: x' = focalScreen - world_before * zoom'
+ */
+export declare function zoomAt(v: ViewportState, focalScreen: Vec2, factor: number, bounds?: ZoomBounds): ViewportState;
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FitViewOptions {
+    /** Screen-space margin (px) kept clear on every side. Default 64. */
+    padding?: number;
+    /** Never zoom in past this level — keeps tiny graphs from filling the screen. Default 1. */
+    maxZoom?: number;
+    /** Never zoom out past this level. Default 0.02. */
+    minZoom?: number;
+}
+/**
+ * Compute the viewport that frames a world-space bounds rect centred inside a screen of the given
+ * size, leaving `padding` px clear on each edge. The zoom fits the more-constraining axis; the
+ * content centre is mapped to the screen centre. Zero-size bounds are handled without div-by-zero.
+ */
+export declare function fitView(bounds: Rect, screen: {
+    width: number;
+    height: number;
+}, opts?: FitViewOptions): ViewportState;
+export declare function snapToGrid(point: Vec2, cellSize: number): Vec2;
+/**
+ * Resolve a node's final position during/at the end of a drag gesture.
+ *
+ * @param initial  position when the drag started
+ * @param delta    world-space delta accumulated since the start
+ * @param snap     grid cell size, or null to disable snap (used while Alt is held)
+ */
+export declare function computeDragTarget(initial: Vec2, delta: Vec2, snap: number | null): Vec2;
+/**
+ * Resolve the uniform world-delta applied to *every* node in a multi-selection drag.
+ *
+ * Anchoring the snap to one node (the one under the cursor when the drag started) and applying
+ * the resulting delta to the rest preserves the group's internal layout. Snapping each node
+ * independently — what we did before — produced per-node rounding errors when nodes started
+ * off-grid: relative offsets drifted by up to a cell, so one node visibly "stuttered" out of
+ * formation. See drag-group regression test.
+ */
+export declare function computeGroupSnappedDelta(anchorInitial: Vec2, rawDelta: Vec2, snap: number | null): Vec2;
+//# sourceMappingURL=viewport-math.d.ts.map

package/dist/viewport-math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport-math.d.ts","sourceRoot":"","sources":["../src/viewport-math.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,CAAC,EAAE,MAAM,CAAA;IACT,qDAAqD;IACrD,CAAC,EAAE,MAAM,CAAA;IACT,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;AAI5D,wBAAgB,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,aAAa,GAAG,IAAI,CAKlE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,aAAa,GAAG,IAAI,CAKjE;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,aAAa,EAChB,WAAW,EAAE,IAAI,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,UAA2B,GAClC,aAAa,CAQf;AAED,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,IAAI,EACZ,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACzC,IAAI,GAAE,cAAmB,GACxB,aAAa,CAqBf;AAaD,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ9D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,IAAI,EACnB,QAAQ,EAAE,IAAI,EACd,IAAI,EAAE,MAAM,GAAG,IAAI,GAClB,IAAI,CAON"}

package/dist/viewport-math.js

@@ -0,0 +1,106 @@
+const DEFAULT_BOUNDS = [0.05, 16];
+export function screenToWorld(screen, v) {
+    return {
+        x: (screen.x - v.x) / v.zoom,
+        y: (screen.y - v.y) / v.zoom,
+    };
+}
+export function worldToScreen(world, v) {
+    return {
+        x: world.x * v.zoom + v.x,
+        y: world.y * v.zoom + v.y,
+    };
+}
+export function clampZoom(zoom, min, max) {
+    if (zoom < min)
+        return min;
+    if (zoom > max)
+        return max;
+    return zoom;
+}
+/**
+ * Focal zoom: scale by `factor` while keeping the world point currently under `focalScreen`
+ * anchored to that same screen point. The classic UE / Figma / VSCode-canvas zoom feel.
+ *
+ *   world_after = (screen - x') / zoom'
+ *   require: world_after === world_before for screen === focalScreen
+ *   solving: x' = focalScreen - world_before * zoom'
+ */
+export function zoomAt(v, focalScreen, factor, bounds = DEFAULT_BOUNDS) {
+    const targetZoom = clampZoom(v.zoom * factor, bounds[0], bounds[1]);
+    const worldFocal = screenToWorld(focalScreen, v);
+    return {
+        zoom: targetZoom,
+        x: focalScreen.x - worldFocal.x * targetZoom,
+        y: focalScreen.y - worldFocal.y * targetZoom,
+    };
+}
+/**
+ * Compute the viewport that frames a world-space bounds rect centred inside a screen of the given
+ * size, leaving `padding` px clear on each edge. The zoom fits the more-constraining axis; the
+ * content centre is mapped to the screen centre. Zero-size bounds are handled without div-by-zero.
+ */
+export function fitView(bounds, screen, opts = {}) {
+    const padding = opts.padding ?? 64;
+    const maxZoom = opts.maxZoom ?? 1;
+    const minZoom = opts.minZoom ?? 0.02;
+    const availW = Math.max(1, screen.width - padding * 2);
+    const availH = Math.max(1, screen.height - padding * 2);
+    const fitZoom = bounds.width > 0 && bounds.height > 0
+        ? Math.min(availW / bounds.width, availH / bounds.height)
+        : maxZoom;
+    const zoom = clampZoom(fitZoom, minZoom, maxZoom);
+    const cx = bounds.x + bounds.width / 2;
+    const cy = bounds.y + bounds.height / 2;
+    return {
+        zoom,
+        x: screen.width / 2 - cx * zoom,
+        y: screen.height / 2 - cy * zoom,
+    };
+}
+/**
+ * Snap a point to the nearest multiple of `cellSize` on each axis. Used by drag to give the
+ * UE-style "feels continuous but actually quantised" feel. `cellSize === 1` rounds to integer
+ * pixels; pass `Number.EPSILON` (or skip the call) for true continuous motion.
+ */
+/** Round-half-away-from-zero so snap is symmetric: 2.5 → 3, −2.5 → −3 (JS Math.round goes 2.5 → 3
+ *  but −2.5 → −2, which makes drag feel jerky around the origin). */
+function roundAwayFromZero(n) {
+    return n >= 0 ? Math.round(n) : -Math.round(-n);
+}
+export function snapToGrid(point, cellSize) {
+    if (!(cellSize > 0)) {
+        throw new Error(`snapToGrid: cellSize must be > 0, got ${cellSize}`);
+    }
+    const sx = roundAwayFromZero(point.x / cellSize) * cellSize;
+    const sy = roundAwayFromZero(point.y / cellSize) * cellSize;
+    // Normalise -0 to +0 so callers don't trip on Object.is(-0, 0) === false.
+    return { x: sx === 0 ? 0 : sx, y: sy === 0 ? 0 : sy };
+}
+/**
+ * Resolve a node's final position during/at the end of a drag gesture.
+ *
+ * @param initial  position when the drag started
+ * @param delta    world-space delta accumulated since the start
+ * @param snap     grid cell size, or null to disable snap (used while Alt is held)
+ */
+export function computeDragTarget(initial, delta, snap) {
+    const raw = { x: initial.x + delta.x, y: initial.y + delta.y };
+    return snap === null ? raw : snapToGrid(raw, snap);
+}
+/**
+ * Resolve the uniform world-delta applied to *every* node in a multi-selection drag.
+ *
+ * Anchoring the snap to one node (the one under the cursor when the drag started) and applying
+ * the resulting delta to the rest preserves the group's internal layout. Snapping each node
+ * independently — what we did before — produced per-node rounding errors when nodes started
+ * off-grid: relative offsets drifted by up to a cell, so one node visibly "stuttered" out of
+ * formation. See drag-group regression test.
+ */
+export function computeGroupSnappedDelta(anchorInitial, rawDelta, snap) {
+    if (snap === null)
+        return rawDelta;
+    const anchorTarget = snapToGrid({ x: anchorInitial.x + rawDelta.x, y: anchorInitial.y + rawDelta.y }, snap);
+    return { x: anchorTarget.x - anchorInitial.x, y: anchorTarget.y - anchorInitial.y };
+}
+//# sourceMappingURL=viewport-math.js.map

package/dist/viewport-math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport-math.js","sourceRoot":"","sources":["../src/viewport-math.ts"],"names":[],"mappings":"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"}

package/dist/viewport.d.ts

@@ -0,0 +1,28 @@
+import { type Unsubscribe } from '@xenolithengine/graph-core';
+import { type Vec2, type ViewportState, type ZoomBounds } from './viewport-math.js';
+/**
+ * Minimal shape of the object Viewport applies state to. PIXI Container satisfies this — we only
+ * touch `scale.{x,y}` and `position.{x,y}`. Keeping the abstraction tiny lets us unit-test the
+ * Viewport without a WebGL context (any plain object with `scale`/`position` works).
+ */
+export interface ApplyTarget {
+    scale: {
+        x: number;
+        y: number;
+    };
+    position: {
+        x: number;
+        y: number;
+    };
+}
+export declare class Viewport {
+    #private;
+    constructor(target: ApplyTarget, initial?: ViewportState);
+    get state(): ViewportState;
+    setState(state: ViewportState): void;
+    pan(dx: number, dy: number): void;
+    zoomAt(focal: Vec2, factor: number, bounds?: ZoomBounds): void;
+    reset(): void;
+    on(handler: (state: ViewportState) => void): Unsubscribe;
+}
+//# sourceMappingURL=viewport.d.ts.map

package/dist/viewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../src/viewport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAA;AAC3E,OAAO,EAEL,KAAK,IAAI,EACT,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAA;AAE3B;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/B,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACnC;AAQD,qBAAa,QAAQ;;gBAKP,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,aAA6B;IAMvE,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAapC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAKjC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI;IAI9D,KAAK,IAAI,IAAI;IAIb,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,WAAW;CAUzD"}

package/dist/viewport.js

@@ -0,0 +1,47 @@
+import { EventEmitter } from '@xenolithengine/graph-core';
+import { zoomAt as zoomAtMath, } from './viewport-math.js';
+const DEFAULT_STATE = { x: 0, y: 0, zoom: 1 };
+export class Viewport {
+    #target;
+    #events = new EventEmitter();
+    #state;
+    constructor(target, initial = DEFAULT_STATE) {
+        this.#target = target;
+        this.#state = { ...initial };
+        this.#apply();
+    }
+    get state() {
+        return { ...this.#state };
+    }
+    setState(state) {
+        if (this.#state.x === state.x &&
+            this.#state.y === state.y &&
+            this.#state.zoom === state.zoom) {
+            return;
+        }
+        this.#state = { ...state };
+        this.#apply();
+        this.#events.emit('viewport:changed', this.state);
+    }
+    pan(dx, dy) {
+        if (dx === 0 && dy === 0)
+            return;
+        this.setState({ ...this.#state, x: this.#state.x + dx, y: this.#state.y + dy });
+    }
+    zoomAt(focal, factor, bounds) {
+        this.setState(zoomAtMath(this.#state, focal, factor, bounds));
+    }
+    reset() {
+        this.setState(DEFAULT_STATE);
+    }
+    on(handler) {
+        return this.#events.on('viewport:changed', handler);
+    }
+    #apply() {
+        this.#target.scale.x = this.#state.zoom;
+        this.#target.scale.y = this.#state.zoom;
+        this.#target.position.x = this.#state.x;
+        this.#target.position.y = this.#state.y;
+    }
+}
+//# sourceMappingURL=viewport.js.map

package/dist/viewport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.js","sourceRoot":"","sources":["../src/viewport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAoB,MAAM,4BAA4B,CAAA;AAC3E,OAAO,EACL,MAAM,IAAI,UAAU,GAIrB,MAAM,oBAAoB,CAAA;AAY3B,MAAM,aAAa,GAAkB,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;AAM5D,MAAM,OAAO,QAAQ;IACV,OAAO,CAAa;IACpB,OAAO,GAAG,IAAI,YAAY,EAAU,CAAA;IAC7C,MAAM,CAAe;IAErB,YAAY,MAAmB,EAAE,UAAyB,aAAa;QACrE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,OAAO,EAAE,CAAA;QAC5B,IAAI,CAAC,MAAM,EAAE,CAAA;IACf,CAAC;IAED,IAAI,KAAK;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;IAC3B,CAAC;IAED,QAAQ,CAAC,KAAoB;QAC3B,IACE,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,EAC/B,CAAC;YACD,OAAM;QACR,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,CAAA;QAC1B,IAAI,CAAC,MAAM,EAAE,CAAA;QACb,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;IACnD,CAAC;IAED,GAAG,CAAC,EAAU,EAAE,EAAU;QACxB,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC;YAAE,OAAM;QAChC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IACjF,CAAC;IAED,MAAM,CAAC,KAAW,EAAE,MAAc,EAAE,MAAmB;QACrD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/D,CAAC;IAED,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAA;IAC9B,CAAC;IAED,EAAE,CAAC,OAAuC;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAA;IACrD,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAA;QACvC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAA;QACvC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;QACvC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;IACzC,CAAC;CACF"}

package/dist/virtualize.d.ts

@@ -0,0 +1,55 @@
+import type { Rect } from './geom.js';
+import { type ViewportState } from './viewport-math.js';
+/** Virtualization only kicks in past the threshold — at or below it, the graph renders 1:1 (zero
+ *  risk for ordinary graphs). */
+export declare function shouldVirtualize(nodeCount: number, threshold: number): boolean;
+/**
+ * Whether to draw nodes in level-of-detail (simplified) form at the current zoom, with hysteresis:
+ * enter LOD below `enter`, leave it only above `exit` (exit > enter). The band between the two stops
+ * the detail level flip-flopping when the zoom sits right at the threshold during a gesture.
+ */
+export declare function useLOD(zoom: number, currentlyLOD: boolean, enter: number, exit: number): boolean;
+export type LODLevel = 'full' | 'sprite' | 'flat';
+export interface LODThresholds {
+    /** flat↔sprite boundary: enter flat below lowEnter, leave flat above lowExit (lowExit > lowEnter). */
+    lowEnter: number;
+    lowExit: number;
+    /** sprite↔full boundary: enter full above highExit, leave full below highEnter (highExit > highEnter). */
+    highEnter: number;
+    highExit: number;
+}
+/**
+ * Three-tier level of detail with independent hysteresis on each boundary:
+ *  - close zoom → 'full'   (real nodes)
+ *  - mid zoom   → 'sprite' (one baked texture per node TYPE — recognisable, cheap, no LG overlap RTs)
+ *  - far zoom   → 'flat'   (single batch of rects)
+ * `current` is the level in effect, used to apply hysteresis at whichever boundary the zoom is near.
+ */
+export declare function lodLevel(zoom: number, current: LODLevel, t: LODThresholds): LODLevel;
+/** World-space AABB of the screen viewport, inflated by `marginPx` screen pixels on every side
+ *  (the overscan buffer, expressed in screen px so it stays constant regardless of zoom). */
+export declare function visibleWorldRect(screenW: number, screenH: number, viewport: ViewportState, marginPx: number): Rect;
+/** Bucket a world point into a grid cell key at the given cell size. */
+export declare function cellKey(x: number, y: number, cell: number): string;
+/** Every grid-cell key a world rect overlaps — used to gather only the nodes near the viewport
+ *  instead of scanning the whole graph each frame (the O(N)-per-frame trap on huge graphs). */
+export declare function cellsForRect(rect: Rect, cell: number): string[];
+export interface Reconciliation {
+    /** Non-live nodes that entered the inner rect — create a view for these. */
+    show: string[];
+    /** Live nodes that left the outer rect — destroy their view (back to data only). */
+    hide: string[];
+}
+/**
+ * Decide which node views to create / destroy this pass, with hysteresis.
+ *
+ * - A node intersecting `inner` and not yet live → show (create).
+ * - A live node no longer intersecting `outer` → hide (destroy).
+ * - Anything in the band between (live, outside inner but inside outer) is left untouched.
+ *
+ * `rects` are world-space node AABBs; `live` is the set of node ids that currently have a view.
+ */
+export declare function reconcileVisibleNodes(rects: ReadonlyArray<{
+    id: string;
+} & Rect>, live: ReadonlySet<string>, inner: Rect, outer: Rect): Reconciliation;
+//# sourceMappingURL=virtualize.d.ts.map

package/dist/virtualize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualize.d.ts","sourceRoot":"","sources":["../src/virtualize.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAErC,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAEtE;iCACiC;AACjC,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGhG;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEjD,MAAM,WAAW,aAAa;IAC5B,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,0GAA0G;IAC1G,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,aAAa,GAAG,QAAQ,CAMpF;AAED;6FAC6F;AAC7F,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,GACf,IAAI,CASN;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;+FAC+F;AAC/F,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ/D;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,oFAAoF;IACpF,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,EAC3C,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EACzB,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,IAAI,GACV,cAAc,CAYhB"}

package/dist/virtualize.js

@@ -0,0 +1,96 @@
+// Viewport virtualization (#59): keep a live PIXI view only for nodes near the viewport, so GPU
+// memory is O(visible) instead of O(total) — the fix for the ~5000-node crash. These are the PURE
+// pieces (no PIXI, fully unit-tested); the editor wires them to its #views map and viewport changes.
+//
+// Hysteresis is the key to smoothness: a node is CREATED when it reaches the inner (overscan)
+// rect, but only DESTROYED when it leaves the larger outer rect. The band between them means a node
+// hovering at the edge during a pan is not churned create/destroy every frame — the thing that would
+// cause flicker and stutter.
+import { rectIntersects } from './geom.js';
+import { screenToWorld } from './viewport-math.js';
+/** Virtualization only kicks in past the threshold — at or below it, the graph renders 1:1 (zero
+ *  risk for ordinary graphs). */
+export function shouldVirtualize(nodeCount, threshold) {
+    return nodeCount > threshold;
+}
+/**
+ * Whether to draw nodes in level-of-detail (simplified) form at the current zoom, with hysteresis:
+ * enter LOD below `enter`, leave it only above `exit` (exit > enter). The band between the two stops
+ * the detail level flip-flopping when the zoom sits right at the threshold during a gesture.
+ */
+export function useLOD(zoom, currentlyLOD, enter, exit) {
+    if (currentlyLOD)
+        return zoom < exit;
+    return zoom < enter;
+}
+/**
+ * Three-tier level of detail with independent hysteresis on each boundary:
+ *  - close zoom → 'full'   (real nodes)
+ *  - mid zoom   → 'sprite' (one baked texture per node TYPE — recognisable, cheap, no LG overlap RTs)
+ *  - far zoom   → 'flat'   (single batch of rects)
+ * `current` is the level in effect, used to apply hysteresis at whichever boundary the zoom is near.
+ */
+export function lodLevel(zoom, current, t) {
+    const flat = current === 'flat' ? zoom < t.lowExit : zoom < t.lowEnter;
+    if (flat)
+        return 'flat';
+    const full = current === 'full' ? zoom > t.highEnter : zoom > t.highExit;
+    if (full)
+        return 'full';
+    return 'sprite';
+}
+/** World-space AABB of the screen viewport, inflated by `marginPx` screen pixels on every side
+ *  (the overscan buffer, expressed in screen px so it stays constant regardless of zoom). */
+export function visibleWorldRect(screenW, screenH, viewport, marginPx) {
+    const topLeft = screenToWorld({ x: -marginPx, y: -marginPx }, viewport);
+    const bottomRight = screenToWorld({ x: screenW + marginPx, y: screenH + marginPx }, viewport);
+    return {
+        x: topLeft.x + 0, // normalise -0 → 0
+        y: topLeft.y + 0,
+        width: bottomRight.x - topLeft.x,
+        height: bottomRight.y - topLeft.y,
+    };
+}
+/** Bucket a world point into a grid cell key at the given cell size. */
+export function cellKey(x, y, cell) {
+    return `${Math.floor(x / cell)},${Math.floor(y / cell)}`;
+}
+/** Every grid-cell key a world rect overlaps — used to gather only the nodes near the viewport
+ *  instead of scanning the whole graph each frame (the O(N)-per-frame trap on huge graphs). */
+export function cellsForRect(rect, cell) {
+    const x0 = Math.floor(rect.x / cell);
+    const y0 = Math.floor(rect.y / cell);
+    const x1 = Math.floor((rect.x + rect.width) / cell);
+    const y1 = Math.floor((rect.y + rect.height) / cell);
+    const keys = [];
+    for (let cx = x0; cx <= x1; cx++)
+        for (let cy = y0; cy <= y1; cy++)
+            keys.push(`${cx},${cy}`);
+    return keys;
+}
+/**
+ * Decide which node views to create / destroy this pass, with hysteresis.
+ *
+ * - A node intersecting `inner` and not yet live → show (create).
+ * - A live node no longer intersecting `outer` → hide (destroy).
+ * - Anything in the band between (live, outside inner but inside outer) is left untouched.
+ *
+ * `rects` are world-space node AABBs; `live` is the set of node ids that currently have a view.
+ */
+export function reconcileVisibleNodes(rects, live, inner, outer) {
+    const show = [];
+    const hide = [];
+    for (const r of rects) {
+        const isLive = live.has(r.id);
+        if (!isLive) {
+            if (rectIntersects(r, inner))
+                show.push(r.id);
+        }
+        else {
+            if (!rectIntersects(r, outer))
+                hide.push(r.id);
+        }
+    }
+    return { show, hide };
+}
+//# sourceMappingURL=virtualize.js.map

package/dist/virtualize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualize.js","sourceRoot":"","sources":["../src/virtualize.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,kGAAkG;AAClG,qGAAqG;AACrG,EAAE;AACF,8FAA8F;AAC9F,oGAAoG;AACpG,qGAAqG;AACrG,6BAA6B;AAG7B,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAsB,MAAM,oBAAoB,CAAA;AAEtE;iCACiC;AACjC,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,SAAiB;IACnE,OAAO,SAAS,GAAG,SAAS,CAAA;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,YAAqB,EAAE,KAAa,EAAE,IAAY;IACrF,IAAI,YAAY;QAAE,OAAO,IAAI,GAAG,IAAI,CAAA;IACpC,OAAO,IAAI,GAAG,KAAK,CAAA;AACrB,CAAC;AAaD;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAiB,EAAE,CAAgB;IACxE,MAAM,IAAI,GAAG,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAA;IACtE,IAAI,IAAI;QAAE,OAAO,MAAM,CAAA;IACvB,MAAM,IAAI,GAAG,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAA;IACxE,IAAI,IAAI;QAAE,OAAO,MAAM,CAAA;IACvB,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;6FAC6F;AAC7F,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,OAAe,EACf,QAAuB,EACvB,QAAgB;IAEhB,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,QAAQ,CAAC,CAAA;IACvE,MAAM,WAAW,GAAG,aAAa,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,EAAE,QAAQ,CAAC,CAAA;IAC7F,OAAO;QACL,CAAC,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,EAAE,mBAAmB;QACrC,CAAC,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC;QAChB,KAAK,EAAE,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;QAChC,MAAM,EAAE,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;KAClC,CAAA;AACH,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,OAAO,CAAC,CAAS,EAAE,CAAS,EAAE,IAAY;IACxD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAA;AAC1D,CAAC;AAED;+FAC+F;AAC/F,MAAM,UAAU,YAAY,CAAC,IAAU,EAAE,IAAY;IACnD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACpC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACpC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;IACnD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAA;IACpD,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,KAAK,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE;QAAE,KAAK,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;IAC5F,OAAO,IAAI,CAAA;AACb,CAAC;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA2C,EAC3C,IAAyB,EACzB,KAAW,EACX,KAAW;IAEX,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC7B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC/C,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAChD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AACvB,CAAC"}

package/dist/widget-renderer.d.ts

@@ -0,0 +1,150 @@
+import { Container } from 'pixi.js';
+import { type Node, type WidgetSpec, type WidgetStyle } from '@xenolithengine/graph-core';
+import type { XenTokens } from '@xenolithengine/graph-theme-xen';
+/** Context handed to a custom widget's draw/pointer callbacks. Coords are widget-local CSS px.
+ *  Theme colours (`accent`/`text`/`muted`) come from the resolved widget tokens so a canvas widget
+ *  can match the active theme (gold on Xen, cyan on Liquid Glass) instead of hardcoding — unless
+ *  the widget's own `style` overrode them. */
+export interface CustomWidgetContext {
+    value: unknown;
+    node: Node;
+    width: number;
+    height: number;
+    accent: string;
+    text: string;
+    muted: string;
+}
+/** Canvas-draw custom widget — paints into a 2D canvas we own (uploaded to a texture; the primary,
+ *  perf-friendly path, no foreignObject). `onPointer` returns the new value (or undefined for no
+ *  change) during a drag; the editor commits it. */
+export interface CanvasWidgetController {
+    draw(ctx: CanvasRenderingContext2D, c: CustomWidgetContext): void;
+    onPointer?(phase: 'down' | 'move' | 'up', x: number, y: number, c: CustomWidgetContext): unknown;
+}
+/** DOM-mounted custom widget — the editor positions a real HTML element over the widget (in screen
+ *  space, kept in sync with pan/zoom/drag). This is the contract the React/Vue/Svelte adapters wrap
+ *  (mount a framework component into `el`); vanilla implements it directly. `setValue` commits
+ *  (undoable). `update` fires on external value changes. Return a cleanup fn from `mount` or
+ *  implement `unmount`. */
+export interface DomWidgetController {
+    mount(el: HTMLElement, c: CustomWidgetContext & {
+        setValue: (v: unknown) => void;
+    }): void | (() => void);
+    update?(c: CustomWidgetContext): void;
+    unmount?(): void;
+}
+/** A custom widget controller — either canvas-draw (fast, WebGL texture) or DOM-mounted (arbitrary
+ *  HTML / framework component). `editor.registerWidget(name, controller)` accepts either. */
+export type CustomWidgetController = CanvasWidgetController | DomWidgetController;
+export declare function isDomWidgetController(c: CustomWidgetController): c is DomWidgetController;
+/** Fully-resolved widget visuals: the theme's widget tokens with a widget's own `style` override
+ *  applied on top. Both the WebGL renderer and the editor's DOM editor resolve through this so a
+ *  per-widget override customises every surface consistently. */
+export interface ResolvedWidgetStyle {
+    bg: string;
+    bgHover: string;
+    bgFocused: string;
+    track: string;
+    fill: string;
+    fillAlpha: number;
+    text: string;
+    label: string;
+    placeholder: string;
+    border: string;
+    borderFocused: string;
+    selection: string;
+    knob: string;
+    radius: number;
+    paddingX: number;
+    paddingY: number;
+    borderWidth: number;
+    toggleWidth: number;
+    toggleHeight: number;
+}
+export declare function resolveWidgetStyle(tokens: XenTokens, override?: WidgetStyle): ResolvedWidgetStyle;
+/** The active widget theme as CSS custom properties. The editor sets these on each DOM-mounted
+ *  custom widget's host element, so a widget author (any framework, or vanilla) can style with
+ *  `var(--xeno-accent)`, `var(--xeno-bg)`, … and look correct in every theme — and restyle for free
+ *  when the theme changes. This is the basis for a theme-agnostic widget/plugin ecosystem. */
+export declare function widgetCssVars(c: ResolvedWidgetStyle): Record<string, string>;
+/** The active theme as panel/control CSS custom properties. The editor sets these on the host root
+ *  so in-editor chrome — `<XenolithPanel>`, `<XenolithControls>`, buttons, any framework component
+ *  portalled into `editor.overlayRoot` — styles with `var(--xeno-panel)`, `var(--xeno-accent)`, …
+ *  and restyles for free on `setTheme`. Complements `widgetCssVars` (per-widget input surfaces);
+ *  shares the `--xeno-accent`/`--xeno-text`/`--xeno-muted`/`--xeno-border`/`--xeno-radius` vocabulary. */
+export declare function themeCssVars(tokens: XenTokens): Record<string, string>;
+export interface WidgetLayoutTokens {
+    node: {
+        headerHeight: number;
+    };
+    /** `diameter` + `labelGap` make widget rects share the same content columns as the pin labels
+     *  above them (left edge at the leftmost pin's label x, right edge at the rightmost) — `paddingX`
+     *  is used as a fallback only when pin geometry is absent (legacy callers). */
+    pin: {
+        rowSpacing: number;
+        rowHeight: number;
+        diameter?: number;
+        labelGap?: number;
+    };
+    header: {
+        toPinsGap: number;
+    };
+    widget: {
+        rowHeight: number;
+        gap: number;
+        paddingX: number;
+    };
+}
+export interface WidgetRect {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Context used to resolve pin-bound widget visibility against the live graph: which pins are
+ *  connected (drives `'whenDisconnected'` hiding) and what value the runtime currently produces
+ *  on a connected pin (drives `'always'` widgets that display live data). */
+export interface ComputeWidgetRectsCtx {
+    /** True when the IN-pin identified by `pinKey` (matched against pin label, then id) has ≥1
+     *  incoming edge. */
+    isPinConnected: (pinKey: string) => boolean;
+    /** When a host runtime is loaded, returns the value currently flowing into the bound pin
+     *  (i.e. the upstream node's last produced output). A `'always'` (display) widget reads this
+     *  in preference to its stored state when the pin is connected. Undefined when no runtime is
+     *  attached or the value isn't available. */
+    pinLiveValue?: (pinKey: string) => unknown;
+}
+/** Pick the value a widget should display this frame. The contract: a widget bound to an IN-pin
+ *  with `visibility:'always'` is a DISPLAY widget — when the pin is wired it shows the upstream
+ *  runtime value (via the host's `pinLiveValue` callback); otherwise it shows its stored state.
+ *  Applies to BOTH custom and built-in widgets (slider/number/text/combo/color/toggle) — the
+ *  promise is the same regardless of widget type. */
+export declare function resolveDisplayValue(spec: WidgetSpec, node: Node, ctx?: {
+    isPinConnected: (k: string) => boolean;
+    pinLiveValue?: (k: string) => unknown;
+}): unknown;
+/** Local-space rects for every visible widget. The canon: every widget is bound to one IN-pin
+ *  (via `widgetBindKey`) and renders INSIDE that pin's row — pin dot + label on the left, control
+ *  on the right. `button` widgets aren't pin-bound — they stack in an "actions row" under the pin
+ *  block. Visibility per widget follows `widgetVisibility`: input controls hide on connect, custom
+ *  widgets display live runtime values when connected.  Returns rects in source order; pin-bound
+ *  ones whose pin can't be resolved (or is hoisted to the header) are silently skipped. */
+export declare function computeWidgetRects(node: Node, width: number, tokens: WidgetLayoutTokens, ctx?: ComputeWidgetRectsCtx): WidgetRect[];
+export interface WidgetHit {
+    id: string;
+    spec: WidgetSpec;
+    rect: WidgetRect;
+}
+export interface WidgetsView {
+    container: Container;
+    rects: WidgetRect[];
+    /** Hit-test a node-local point; returns the widget under it (skips disabled / button-less). */
+    widgetHit(localX: number, localY: number): WidgetHit | null;
+    /** Cheaply refresh one widget's visual to a new value (used during live slider/number drag). */
+    update(id: string, value: unknown): void;
+}
+/** Builds the WebGL widget rows for a node's expanded form. Pure PIXI — interaction is wired by the
+ *  editor against `widgetHit`. */
+export declare function renderWidgets(node: Node, width: number, tokens: XenTokens, layoutTokens: WidgetLayoutTokens, customWidgets?: ReadonlyMap<string, CustomWidgetController>, ctx?: ComputeWidgetRectsCtx): WidgetsView;
+//# sourceMappingURL=widget-renderer.d.ts.map

package/dist/widget-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-renderer.d.ts","sourceRoot":"","sources":["../src/widget-renderer.ts"],"names":[],"mappings":"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"}