@trokster/l-cursor 0.0.1

package/dist/core/engine.js

@@ -0,0 +1,492 @@
+// The generic zoom engine (THEORY.md §4–6).
+//
+// Display-agnostic: hand it a `layout()` function (radial / pack / treemap /
+// network) and it owns everything else — bounded-scale camera, referential
+// rebasing for infinite zoom, level-of-detail, and viewport culling. The only
+// thing that varies per display is the layout and the SVG shape drawn for each
+// item; the engine never knows or cares which.
+//
+// Per frame it returns ONLY the items that are on-screen and pixel-meaningful
+// (THEORY §5–6), so render cost is O(visible), independent of total tree size.
+
+import { rebaseCamera, nodeBox } from './rebase.js';
+import { ascend } from './tree.js';
+
+export function createEngine({ index, layout, camera, config = {} }) {
+	const cfg = {
+		rootSize: 500, // canonical root half-extent (S0)
+		maxDepth: 6, // how many generations to lay out below the referential
+		contextUp: 0, // lay out from this many levels ABOVE the referential, so the
+		// parent ring and siblings stay visible around you for orientation
+		treeLinks: false, // emit parent->child links for rendered nodes
+		descendAt: 0.82, // re-root inward when a child's half-extent > this * halfMin(px)
+		ascendAt: 0.34, // re-root outward when the root's half-extent < this * halfMin(px)
+		minPx: 7, // cull nodes whose half-extent is below this many px
+		openPx: 58, // a node reveals its children only once it is this big on screen
+		childPreview: false, // closed nodes carry ghost geometry of their children
+		previewPx: 16, // ...but only once the node is at least this big on screen
+		previewMax: 40, // cap on ghost children per node
+		labelPx: 13, // only draw labels above this on-screen size
+		maxScale: 100, // hard safety cap (rebasing keeps us well under this)
+		minScale: 0.008, // hard safety floor
+		layoutOpts: {},
+		...config
+	};
+
+	let viewport = { w: 1, h: 1 };
+	let rootId = config.rootId ?? index.roots[0] ?? index.byId.keys().next().value;
+	let laid = relayout(rootId);
+
+	// Absolute depth in the DATA tree (distance from the true root), cached.
+	// Layout depth shifts every time the referential rebases — anything visual
+	// keyed on it (colors!) would flip scene-wide at each re-root. Absolute depth
+	// is stable forever.
+	const absDepths = new Map();
+	function absDepthOf(id) {
+		if (absDepths.has(id)) return absDepths.get(id);
+		const chain = [];
+		let cur = id;
+		while (cur != null && !absDepths.has(cur)) {
+			chain.push(cur);
+			cur = index.parent.get(cur);
+		}
+		let d = cur != null ? absDepths.get(cur) : -1;
+		for (let i = chain.length - 1; i >= 0; i--) absDepths.set(chain[i], ++d);
+		return absDepths.get(id);
+	}
+	// Anchor = the screen point the user is zooming toward (cursor / pinch
+	// centroid). Rebasing dives into whatever sits under it. Null => viewport
+	// center (used for pan / programmatic moves).
+	let anchor = null;
+	function setAnchor(x, y) {
+		anchor = { x, y };
+	}
+	function clearAnchor() {
+		anchor = null;
+	}
+
+	function relayout(id) {
+		// Lay out from `contextUp` levels above the referential: the referential's
+		// parent and siblings then exist in the layout and stay on screen at the
+		// edges. Rebasing is unaffected — it pivots on any node alive in both
+		// frames, and the referential always is. Depth extends by the same amount
+		// so the subtree below the referential keeps its full budget.
+		const layoutRoot = ascend(index, id, cfg.contextUp);
+		return layout(index, layoutRoot, {
+			rootSize: cfg.rootSize,
+			maxDepth: cfg.maxDepth + cfg.contextUp,
+			...cfg.layoutOpts
+		});
+	}
+
+	function setViewport(w, h) {
+		viewport = { w: Math.max(1, w), h: Math.max(1, h) };
+	}
+
+	// Camera that places the current root at ~`frac` of the viewport, centered.
+	// Rects fit per-axis (the cell fills the viewport, anisotropic — the treemap
+	// zoom feel); circles fit uniformly on the smaller viewport dimension. A
+	// uniform fit on a rect's short side would overflow the long axis past the
+	// descend threshold and chain-descend through dominant children.
+	function fitCamera(frac = 0.82) {
+		const root = laid.nodes.get(rootId);
+		const b = nodeBox(root);
+		let sx, sy;
+		if (root.kind === 'rect') {
+			sx = (frac * (viewport.w / 2)) / b.hx;
+			sy = (frac * (viewport.h / 2)) / b.hy;
+		} else {
+			const half = 0.5 * Math.min(viewport.w, viewport.h);
+			sx = sy = (frac * half) / (Math.min(b.hx, b.hy) || cfg.rootSize);
+		}
+		return { sx, sy, x: viewport.w / 2 - b.cx * sx, y: viewport.h / 2 - b.cy * sy };
+	}
+	function fit(frac = 0.82) {
+		camera.set(fitCamera(frac));
+	}
+
+	// Direct child of the current root whose screen box contains (px, py).
+	// Children are disjoint within a parent, so the first hit is THE child on the
+	// path toward whatever the user is diving into.
+	function childUnder(px, py, cam) {
+		for (const cid of index.children.get(rootId) ?? []) {
+			const v = laid.nodes.get(cid);
+			if (!v) continue;
+			const b = nodeBox(v);
+			const sx = b.cx * cam.sx + cam.x;
+			const sy = b.cy * cam.sy + cam.y;
+			const rx = b.hx * cam.sx;
+			const ry = b.hy * cam.sy;
+			if (px >= sx - rx && px <= sx + rx && py >= sy - ry && py <= sy + ry) return v;
+		}
+		return null;
+	}
+
+	// Child of the current root nearest to (px, py) on screen. Fallback when the
+	// anchor sits over EMPTY interior (radial cores, packing gaps): without it,
+	// zooming into a void pegs at maxScale with nothing to descend into — a
+	// deadlock. At the cap we tunnel toward the nearest child instead — preferring
+	// children that HAVE children, since the point of tunneling is to keep
+	// unlocking levels (a leaf would just re-peg at the cap).
+	function nearestChild(px, py, cam) {
+		let best = null;
+		let bestD = Infinity;
+		let bestDeep = null;
+		let bestDeepD = Infinity;
+		for (const cid of index.children.get(rootId) ?? []) {
+			const v = laid.nodes.get(cid);
+			if (!v) continue;
+			const b = nodeBox(v);
+			const d = Math.hypot(b.cx * cam.sx + cam.x - px, b.cy * cam.sy + cam.y - py);
+			if (d < bestD) {
+				bestD = d;
+				best = v;
+			}
+			if ((index.children.get(cid) ?? []).length > 0 && d < bestDeepD) {
+				bestDeepD = d;
+				bestDeep = v;
+			}
+		}
+		return bestDeep ?? best;
+	}
+
+	// Deepest laid-out node whose screen box contains point (px, py).
+	function focusAt(px, py, cam) {
+		let best = null;
+		let bestDepth = -1;
+		for (const v of laid.nodes.values()) {
+			const b = nodeBox(v);
+			const sx = b.cx * cam.sx + cam.x;
+			const sy = b.cy * cam.sy + cam.y;
+			const rx = b.hx * cam.sx;
+			const ry = b.hy * cam.sy;
+			if (px >= sx - rx && px <= sx + rx && py >= sy - ry && py <= sy + ry) {
+				if (v.depth > bestDepth) {
+					bestDepth = v.depth;
+					best = v;
+				}
+			}
+		}
+		return best;
+	}
+
+	// Re-root inward onto `target`, preserving the on-screen image (pixel-exact).
+	function descendTo(target, cam) {
+		const oldBox = nodeBox(laid.nodes.get(target));
+		const next = relayout(target);
+		const pivot = next.nodes.get(target);
+		if (!pivot) return null;
+		const newCam = rebaseCamera(cam, oldBox, nodeBox(pivot));
+		rootId = target;
+		laid = next;
+		return newCam;
+	}
+
+	// Re-root outward onto the parent, pivoting on a node alive in both frames.
+	function ascendTo(parentId, cam, pivotId) {
+		const rootView = laid.nodes.get(rootId);
+		const oldBox = nodeBox(laid.nodes.get(pivotId) ?? rootView);
+		const next = relayout(parentId);
+		const newPivot = next.nodes.get(pivotId) ?? next.nodes.get(rootId);
+		if (!newPivot) return null;
+		const usedOldBox = next.nodes.get(pivotId) ? oldBox : nodeBox(rootView);
+		const newCam = rebaseCamera(cam, usedOldBox, nodeBox(newPivot));
+		rootId = parentId;
+		laid = next;
+		return newCam;
+	}
+
+	// How much of the viewport a node covers, 0..1. Circles: min half-extent vs
+	// the smaller viewport half. Rects: per-axis — the smaller of width-coverage
+	// and height-coverage — so a wide-but-short cell (common in treemaps, where a
+	// dominant child can span ~90% of one parent axis) doesn't trip thresholds
+	// while plenty of its surroundings are still visible.
+	function coverage(v, b, cam) {
+		if (v.kind === 'rect') {
+			return Math.min((b.hx * cam.sx) / (viewport.w / 2), (b.hy * cam.sy) / (viewport.h / 2));
+		}
+		const half = 0.5 * Math.min(viewport.w, viewport.h);
+		return Math.min(b.hx * cam.sx, b.hy * cam.sy) / half;
+	}
+
+	// Check descend/ascend thresholds and rebase if needed (THEORY §4). Loops so a
+	// fast zoom that jumps several levels settles in a single frame. Returns the
+	// camera to render with.
+	function maybeRebase(cam) {
+		const camIn = cam; // rebases/clamps create new objects; identity = unchanged
+		const half = 0.5 * Math.min(viewport.w, viewport.h);
+		const ax = anchor?.x ?? viewport.w / 2;
+		const ay = anchor?.y ?? viewport.h / 2;
+
+		for (let iter = 0; iter < 12; iter++) {
+			let changed = false;
+
+			// --- Descend one level: re-root to the child of the current root that
+			// sits under the anchor, once that child has grown to dominate. Going a
+			// single level at a time keeps the scale band tight; the loop lets a fast
+			// multi-level zoom settle in one frame. ---
+			const overCap = cam.sx > cfg.maxScale || cam.sy > cfg.maxScale;
+			const child = childUnder(ax, ay, cam);
+			if (child) {
+				const cb = nodeBox(child);
+				if (coverage(child, cb, cam) >= cfg.descendAt || overCap) {
+					const nc = descendTo(child.id, cam);
+					if (nc) {
+						cam = nc;
+						changed = true;
+						continue;
+					}
+				}
+			}
+
+			// --- Ascend one level: re-root to the parent once the root has shrunk ---
+			const parentId = index.parent.get(rootId);
+			if (parentId != null) {
+				const rootView = laid.nodes.get(rootId);
+				const rb = nodeBox(rootView);
+				const underFloor = cam.sx < cfg.minScale || cam.sy < cfg.minScale;
+				if (coverage(rootView, rb, cam) < cfg.ascendAt || underFloor) {
+					const focus = focusAt(ax, ay, cam);
+					const pivotId = focus && laid.nodes.has(focus.id) ? focus.id : rootId;
+					const nc = ascendTo(parentId, cam, pivotId);
+					if (nc) {
+						cam = nc;
+						changed = true;
+						continue;
+					}
+				}
+			}
+
+			if (!changed) break;
+		}
+
+		// Floor: at the absolute root there's nothing to ascend into, so stop the
+		// zoom-out before the root shrinks to a dot (keep it >= ~28% of viewport).
+		let floor = cfg.minScale;
+		if (index.parent.get(rootId) == null) {
+			const rb = nodeBox(laid.nodes.get(rootId));
+			const rootHalf = Math.min(rb.hx, rb.hy) || cfg.rootSize;
+			floor = Math.max(cfg.minScale, (0.28 * half) / rootHalf);
+		}
+
+		// Hard clamp as a final safety net (keeps the anchor fixed while clamping).
+		if (cam.sx > cfg.maxScale || cam.sx < floor) {
+			const hitFloor = cam.sx < floor;
+			const clamped = Math.max(floor, Math.min(cfg.maxScale, cam.sx));
+			const k = clamped / cam.sx;
+			const wx = (ax - cam.x) / cam.sx;
+			const wy = (ay - cam.y) / cam.sy;
+			cam = { sx: clamped, sy: cam.sy * k, x: ax - wx * clamped, y: ay - wy * cam.sy * k };
+			// Pinned at the zoom-out floor: also pull the root back toward centre,
+			// or fully-zoomed-out could leave the whole scene OFFSCREEN (blank view
+			// with nothing to grab). Each further zoom-out notch glides it home.
+			if (hitFloor && index.parent.get(rootId) == null) {
+				const rb = nodeBox(laid.nodes.get(rootId));
+				const tx = viewport.w / 2 - rb.cx * cam.sx;
+				const ty = viewport.h / 2 - rb.cy * cam.sy;
+				cam = { ...cam, x: cam.x + (tx - cam.x) * 0.25, y: cam.y + (ty - cam.y) * 0.25 };
+			} else if (!hitFloor) {
+				// Pinned at the zoom-in cap: the anchor sits over empty interior (a
+				// hollow core, a packing gap) or a bare leaf — zooming further would
+				// just be a blank void. Each further notch pulls the nearest content
+				// (preferring subtrees that continue) toward the anchor; once it
+				// arrives under the cursor the natural descend takes over and the
+				// dive continues VISIBLY instead of through featureless white.
+				const tgt = nearestChild(ax, ay, cam) ?? laid.nodes.get(rootId);
+				if (tgt) {
+					const b = nodeBox(tgt);
+					const tx = ax - b.cx * cam.sx;
+					const ty = ay - b.cy * cam.sy;
+					cam = { ...cam, x: cam.x + (tx - cam.x) * 0.2, y: cam.y + (ty - cam.y) * 0.2 };
+				}
+			}
+		}
+
+		// write back only if a rebase or clamp actually changed the camera —
+		// otherwise the store subscription would re-dirty the renderer every frame
+		if (cam !== camIn) camera.set(cam);
+		return cam;
+	}
+
+	// Compute the visible, pixel-meaningful draw items in SCREEN coords.
+	// Single pass over `order` (parents before children) with subtree pruning:
+	// a node is culled if its parent was culled, or it is off-screen, or too
+	// small — and a culled node's descendants are therefore skipped too.
+	function frame() {
+		let cam = maybeRebase(camera.get());
+		const { w: W, h: H } = viewport;
+		const culled = new Set(); // node + subtree not rendered
+		const closed = new Set(); // rendered as a summary; children gated off
+		const extById = new Map(); // on-screen half-extent
+		const openById = new Map(); // continuous 0..1 openness, drives morph + fades
+		const items = [];
+
+		for (const id of laid.order) {
+			const v = laid.nodes.get(id);
+			const p = v.parentId;
+			const isRoot = id === rootId;
+			// children only exist when the parent is rendered AND open (LOD gate).
+			// The root is exempt: with contextUp its layout-parent (the context
+			// level) may be culled, but the root must always anchor the frame.
+			if (!isRoot && p != null && (culled.has(p) || closed.has(p))) {
+				culled.add(id);
+				continue;
+			}
+			const b = nodeBox(v);
+			const sx = b.cx * cam.sx + cam.x;
+			const sy = b.cy * cam.sy + cam.y;
+			const rx = b.hx * cam.sx;
+			const ry = b.hy * cam.sy;
+			const ext = Math.min(rx, ry);
+
+			// too small -> prune subtree (descendants are strictly smaller)
+			if (!isRoot && ext < cfg.minPx) {
+				culled.add(id);
+				continue;
+			}
+			// off-screen -> prune subtree (children nest within this box). The root
+			// is never culled here: it anchors the view, and culling it would take
+			// its whole subtree with it and leave a blank frame with nothing to grab.
+			if (!isRoot && (sx + rx < 0 || sx - rx > W || sy + ry < 0 || sy - ry > H)) {
+				culled.add(id);
+				continue;
+			}
+
+			extById.set(id, ext);
+			const childCount = (index.children.get(id) ?? []).length;
+			// LOD: a node "opens" (reveals children) once big enough; until then it
+			// is a summary blob standing in for its whole subtree. `openness` is the
+			// CONTINUOUS version (0=solid blob, 1=container) so the summary→container
+			// morph and the children's fade-in are smooth, never a pop.
+			const hasKids = childCount > 0;
+			const open = isRoot || ext >= cfg.openPx; // gate: do children exist this frame
+			if (hasKids && !open) closed.add(id);
+			const openness = !hasKids ? 0 : isRoot ? 1 : clamp01((ext - cfg.openPx) / (cfg.openPx * 0.3));
+			openById.set(id, openness);
+
+			// children fade in with their parent's openness
+			const alpha = p != null ? (openById.get(p) ?? 1) : 1;
+
+			const item = {
+				id,
+				parentId: p,
+				kind: v.kind,
+				depth: v.depth,
+				absDepth: absDepthOf(id),
+				childCount,
+				data: index.byId.get(id),
+				open: hasKids && open, // children present this frame
+				openness, // 0..1 morph driver
+				leaf: childCount === 0,
+				alpha,
+				showLabel: ext >= cfg.labelPx
+			};
+			// WORLD coordinates (renderer applies the camera as one <g> transform, so
+			// node geometry is static and only the group transform animates).
+			item.cx = b.cx;
+			item.cy = b.cy;
+			item.ext = ext; // on-screen half-extent (px), for label sizing
+			if (v.kind === 'rect') {
+				item.x = b.cx - b.hx;
+				item.y = b.cy - b.hy;
+				item.w = 2 * b.hx;
+				item.h = 2 * b.hy;
+			} else {
+				item.r = b.hx;
+			}
+
+			// LOD preview: while a node is not (fully) open, carry its immediate
+			// children as ghost geometry — generic info about the unexpanded subtree
+			// (count, relative sizes, arrangement) at a glance. The layout already
+			// computed them; the renderer cross-fades ghosts into the real children
+			// as `openness` ramps to 1, so opening is continuous, never a pop.
+			if (cfg.childPreview && hasKids && openness < 1 && ext >= cfg.previewPx) {
+				const preview = [];
+				for (const kid of index.children.get(id) ?? []) {
+					const kv = laid.nodes.get(kid);
+					if (!kv) continue;
+					const kb = nodeBox(kv);
+					if (kv.kind === 'rect') {
+						preview.push({
+							id: kid,
+							kind: 'rect',
+							x: kb.cx - kb.hx,
+							y: kb.cy - kb.hy,
+							w: 2 * kb.hx,
+							h: 2 * kb.hy
+						});
+					} else {
+						preview.push({ id: kid, kind: 'circle', cx: kb.cx, cy: kb.cy, r: kb.hx });
+					}
+					if (preview.length >= cfg.previewMax) break;
+				}
+				if (preview.length) item.preview = preview;
+			}
+
+			items.push(item);
+		}
+
+		// Optional edge layer (network graph): the engine stays generic — it just
+		// hands the rendered, on-screen items to a display-supplied builder that
+		// aggregates the raw graph edges to the current level of detail.
+		const edges = cfg.edgeBuilder
+			? cfg.edgeBuilder(items, cam, { rootId, index })
+			: (laid.edges ?? null);
+
+		// Optional tree-link layer (the original radial had parent->child lines):
+		// one link per rendered node whose parent is also rendered, fading in with
+		// the child. World coords, drawn inside the camera group.
+		let links = null;
+		if (cfg.treeLinks) {
+			const itemById = new Map();
+			for (const it of items) itemById.set(it.id, it);
+			links = [];
+			for (const it of items) {
+				const pit = it.parentId != null ? itemById.get(it.parentId) : null;
+				if (!pit) continue;
+				links.push({
+					id: pit.id + '->' + it.id,
+					x1: pit.cx,
+					y1: pit.cy,
+					x2: it.cx,
+					y2: it.cy,
+					r1: pit.r ?? pit.ext,
+					r2: it.r ?? it.ext,
+					alpha: it.alpha
+				});
+			}
+		}
+
+		return { items, rootId, cam, edges, links };
+	}
+
+	function reset(id) {
+		rootId = id ?? index.roots[0] ?? rootId;
+		laid = relayout(rootId);
+		fit();
+	}
+
+	return {
+		setViewport,
+		fit,
+		fitCamera,
+		frame,
+		reset,
+		setAnchor,
+		clearAnchor,
+		pick: (px, py) => focusAt(px, py, camera.get()),
+		get rootId() {
+			return rootId;
+		},
+		get config() {
+			return cfg;
+		},
+		get layout() {
+			return laid;
+		}
+	};
+}
+
+function clamp01(v) {
+	return v < 0 ? 0 : v > 1 ? 1 : v;
+}

package/dist/core/interaction.d.ts

@@ -0,0 +1,13 @@
+export function createInteraction({ camera, svgElRef, onChange, onGesture, onAnchor }: {
+    camera: any;
+    svgElRef: any;
+    onChange: any;
+    onGesture: any;
+    onAnchor: any;
+}): {
+    onPointerDown: (e: any) => void;
+    onPointerMove: (e: any) => void;
+    onPointerUp: (e: any) => void;
+    onWheel: (e: any) => void;
+    destroy: () => void;
+};