@fnndsc/orrery 0.1.0

package/dist/scene/orrery.d.ts

@@ -0,0 +1,592 @@
+import { PHYSICS_DEFAULT, type HierarchyArrangement, type PhysicsTerms } from '../layout/index.js';
+import { type Palette } from '../draw/index.js';
+import type { NodeLook } from '../types/encoding.js';
+/** One node as the orrery draws it; a surface's own node type extends this. */
+export interface SpaceNode {
+    id: string;
+    label: string;
+    /**
+     * What an engine that needs more reads (`LayoutEngine.needs`): a stage's
+     * plugin, a star's kind — whatever the surface supplies.
+     */
+    attrs?: Record<string, number | string | string[]>;
+    /** Words pinned above the node, read without hovering (a hub's name and count). */
+    caption?: string;
+    /** Drawn as a ringed star: a node of another kind among the stars (a plugin in constellations). */
+    ring?: boolean;
+    /** How it looks, read by the surface from its own domain. */
+    look: NodeLook;
+    parentIds: string[];
+    joinParentIds: string[];
+    /** Scalar for molecule radius scaling; undefined = degree fallback. */
+    metric?: number;
+    /** Collapsed-group multiplicity (×N); undefined or 1 for singletons. */
+    count?: number;
+    /**
+     * A ghost drawn as a halo: a translucent sphere at the anchor's place,
+     * sized by `count`, that names a cluster on hover and takes a click
+     * when no solid sphere is under the pointer. Never edged.
+     */
+    halo?: boolean;
+    /**
+     * Drawn as a lit sphere even when the scene draws stars: a node the
+     * operator is at (an entered feed's own nodes) stays solid to hover and
+     * press, whatever its size on screen.
+     */
+    solid?: boolean;
+    /**
+     * Drawn faint: the rest of a field while one part of it is entered.
+     * Present in the settle and drawn, but at a fraction of its opacity, and
+     * its edges with it.
+     */
+    dim?: boolean;
+    /**
+     * Present in the settle, never drawn: an anchor that pulls its children
+     * together (the universe hangs feeds of one shape from one), with no
+     * sphere, no edge and no pick of its own.
+     */
+    ghost?: boolean;
+    /**
+     * Its joins are drawn faint — a thread at a dim node's strength, never a
+     * tube — for a relation that is not an edge of the run (a feed's lineage
+     * to the feed it began from).
+     */
+    joinFaint?: boolean;
+}
+/** The normalized graph the scene renders. */
+/**
+ * How a space is arranged: a hierarchy round each shape's hub (galaxy,
+ * spokes, clumps), constellations round the plugin stars, or a tree of hubs
+ * the surface names (hubs), or grown feed by feed as a coral (accretion).
+ */
+export type SpaceArrangement = HierarchyArrangement | 'constellations' | 'hubs' | 'accretion';
+export interface SpaceGraph<N extends SpaceNode = SpaceNode> {
+    nodes: N[];
+}
+/** The two ways a graph takes shape. */
+export type LayoutStrategy = 'ranked' | 'molecule';
+/** Callbacks the host wires into picking. */
+export interface OrreryHandlers<N extends SpaceNode = SpaceNode> {
+    select?: (node: N) => void;
+    activate?: (node: N) => void;
+    /** A click on empty space cleared the selection. */
+    deselect?: () => void;
+    /**
+     * A two-finger gesture ended: the camera stands where the fingers left
+     * it. A host that reads a pinch as a step (out of a feed) asks
+     * {@link Orrery.camera_distance} here.
+     */
+    gesture_end?: () => void;
+    /** The words the hover tip shows for a node; null for the node's label. */
+    tip?: (node: N) => string | null;
+    /**
+     * A settle too big for one frame is run in slices, and each slice says
+     * how far it has come; `done === total` is the settle's end. A scene
+     * given this handler never holds the page for a whole settle.
+     */
+    progress?: (done: number, total: number, nodes: number) => void;
+    /**
+     * The feed a node belongs to, for the hand-off: while the scene draws
+     * stars, a feed near enough to read turns solid as a whole. No key, or no
+     * handler, and a node stays a star.
+     */
+    handoffKey?: (node: N) => string | null;
+    /**
+     * A replay moved: its moment (in the arrivals' units) and whether it
+     * still plays; called each frame it advances and once when it stops.
+     */
+    replay?: (at: number, playing: boolean) => void;
+}
+/** The terms a settle honours: orrery's own, re-exported for the panes. */
+export type { PhysicsTerms };
+export { PHYSICS_DEFAULT };
+/** What a surface hands the orrery beside its graph. */
+export interface OrreryOptions {
+    /** Ambient mode: slower spin, no picking, no selection ring. */
+    ambient?: boolean;
+    /**
+     * The colours to draw with, asked on every rebuild so a theme change
+     * repaints; the default palette when absent.
+     */
+    palette?: () => Palette;
+    /**
+     * A worker that settles a grouped space off the page, speaking the
+     * layout-worker protocol (`layout/worker` names the engines). The bundle
+     * that hosts the page must build it, so the surface makes it; without
+     * one, the settle runs on the page.
+     */
+    layoutWorker?: () => Worker;
+}
+/**
+ * The palette used when a surface hands none in.
+ *
+ * @returns Warm status colours, a cool root and a cool pulse.
+ */
+export declare function palette_default(): Palette;
+/**
+ * How a rebuild settles the graph it draws.
+ *
+ * - `full`: every node settles (seeded nodes start where they stood).
+ * - `new`: nodes that already stood somewhere hold still; only nodes new to
+ *   the scene settle among them — a landing adds a molecule without moving
+ *   three thousand spheres.
+ * - `hold`: nothing settles when every node already stands somewhere (a
+ *   census toggle, a palette change, a space re-shown as it was); any new
+ *   node settles as under `new`.
+ */
+export type SettleMode = 'full' | 'new' | 'hold';
+/** How the scene draws its nodes: lit spheres, or points of light. */
+export type DrawMode = 'spheres' | 'stars';
+/**
+ * One live DAG rendering bound to a container element.
+ */
+export declare class Orrery<N extends SpaceNode = SpaceNode> {
+    private readonly container;
+    private readonly handlers;
+    private readonly paletteOf;
+    /** The replay under way, or null: its clock, the arrivals, and what is shown. */
+    private replay;
+    private readonly layoutWorkerOf;
+    private readonly ambient;
+    private readonly renderer;
+    private readonly scene;
+    private readonly camera;
+    private readonly group;
+    /** What lies under a pointer, among everything drawn. */
+    private readonly picker;
+    /** The solid spheres, halos and plain edges. */
+    private readonly spheres;
+    /** Every drawn sphere and halo, by its node's id: the sphere field's own map. */
+    private get meshes();
+    /** The field's stars, threads and nebulae. */
+    private readonly starField;
+    /** Captions pinned above nodes. */
+    private readonly labels;
+    /** Every solid molecule's tubes, and the lamps its stages wear. */
+    private readonly tubes;
+    /** Every molecule's place between stars and spheres. */
+    private readonly handoffField;
+    /** Every job of every stage, when the scene draws a census. */
+    private readonly censusField;
+    /** Where the last projection left every node — the next settle's seed. */
+    private lastPositions;
+    /** Nodes held still through the current settle. */
+    private frozen;
+    /** Physics for the current settle alone, over the standing terms. */
+    private physicsOnce;
+    /** CENSUS: render every member of every ×N group as an instanced point. */
+    private census;
+    /** The molecule's physics terms (see PhysicsTerms). */
+    private physics;
+    /** Sets physics terms and re-settles (warm-started, so it morphs). */
+    physics_set(terms: Partial<PhysicsTerms>, resettle?: boolean): void;
+    physics_get(): PhysicsTerms;
+    /**
+     * Toggles the census projection: the full multiplicity of the graph as
+     * instanced members on analytic shells (spectacle), versus the semantic
+     * shape (work). Selection belongs to shape; census draws, never picks.
+     *
+     * @param on - Whether census is active.
+     */
+    census_set(on: boolean): void;
+    census_get(): boolean;
+    private graph;
+    /** The grab in progress: which node, its drag plane, and travel so far. */
+    private drag;
+    /** The live reaction simulation while (and shortly after) a grab. */
+    private pull;
+    /** The pulse wave's schedule: node id to flare time (ms into the wave). */
+    private waveTimes;
+    /** Wall-clock start of the running wave, or null when no wave runs. */
+    private waveStartAt;
+    /**
+     * The camera and the world it turns: the focus, the flights, the hold
+     * inside a node, the idle spin, and whether the operator has placed the
+     * camera since the scene last framed itself.
+     */
+    private readonly rig;
+    /** How nodes are drawn: lit spheres (every pane), or stars (the universe's choice). */
+    private drawMode;
+    /** Placed nodes by id, for the spheres a solid feed draws. */
+    private placedById;
+    /**
+     * The pointer's intents on the canvas — the view drag, the fingers, the
+     * taps — or null for a miniature, which nobody steers.
+     */
+    private gestures;
+    /** The pending hide of a tap's name. */
+    private tapTipTimer;
+    /** The node the hover tip names, and where the pointer was. */
+    private hovered;
+    /** Times the scene has framed the graph itself (`camera_fit`). */
+    private fits;
+    private strategy;
+    private selectedId;
+    private frameHandle;
+    private disposed;
+    /** The hover tip naming the node under the pointer (pane mode only). */
+    private tip;
+    /** The wave's flare color, re-read from the palette on every rebuild. */
+    private pulseColor;
+    /**
+     * @param container - The element the canvas fills.
+     * @param handlers - Picking callbacks (ignored in ambient mode).
+     * @param options - Pane vs miniature behavior.
+     */
+    constructor(container: HTMLElement, handlers?: OrreryHandlers<N>, options?: OrreryOptions);
+    /**
+     * Replaces the rendered graph. Layout runs under the current strategy.
+     *
+     * @param graph - The normalized graph.
+     */
+    graph_set(graph: SpaceGraph<N>, options?: {
+        wave?: boolean;
+        fit?: boolean;
+        frozen?: ReadonlyArray<string>;
+        physics?: Partial<PhysicsTerms>;
+        settle?: SettleMode;
+    }): void;
+    /** Whether the pane's wave loops continuously (the PULSE ON state). */
+    private waveLooping;
+    /** Sets continuous wave looping; enabling fires a wave immediately. */
+    waveLoop_set(on: boolean): void;
+    /** @returns Whether the wave is looping. */
+    waveLoop_get(): boolean;
+    /**
+     * Where every node settled last, by id, for a caller that remembers.
+     *
+     * @returns Rounded positions, node id to [x, y, z].
+     */
+    positions_get(): Record<string, [number, number, number]>;
+    /**
+     * Seeds the next settle from remembered positions: a node that was here
+     * before starts where it stood, a new one starts fresh. Takes effect on
+     * the next `graph_set`.
+     *
+     * @param positions - Node id to [x, y, z].
+     */
+    positions_seed(positions: Record<string, [number, number, number]>): void;
+    /**
+     * Starts the pulse wave: nodes flare in dependency order, a join waiting
+     * for its last parent. History-honest — only nodes that actually executed
+     * (terminal success or error, or an authored template node) fire, so on a
+     * running feed the wave halts at the execution frontier.
+     */
+    wave_start(): void;
+    /**
+     * Flies the camera into a node: a dolly toward the sphere until it fills
+     * the frame. The idle spin holds for the whole stay; `flight_back` reverses.
+     *
+     * @param nodeId - The node to fly into.
+     * @param onArrived - Called once the camera is inside the node.
+     */
+    flight_into(nodeId: string, onArrived: () => void): void;
+    /**
+     * Flies the camera to frame a set of nodes: the fit `camera_fit` would
+     * give those nodes alone, reached by a flight from where the camera
+     * stands rather than a cut. A descent into one feed frames that feed;
+     * the climb back frames everything. Never holds: picking goes on.
+     *
+     * @param ids - The nodes to frame; every drawn node when empty.
+     * @param durationMs - The flight's length.
+     * @param onDone - Called when the camera arrives.
+     * @param bulk - The share of the nodes the frame must hold, 0..1: at 1
+     *   every outlier is inside the frame; at 0.85 the farthest few spill,
+     *   and the bulk is close enough to touch. A large feed's settle throws
+     *   a few nodes far out, and a frame that held them all put the feed at
+     *   the centre as a starburst of two-pixel spheres nobody could click.
+     */
+    camera_flyToFit(ids: ReadonlyArray<string>, durationMs: number, onDone: () => void, bulk?: number, margin?: number): void;
+    /**
+     * How far the camera stands from what it looks at.
+     *
+     * @returns The distance from the eye to the focus, in scene units.
+     */
+    camera_distance(): number;
+    /**
+     * Whether the operator has placed the camera since the scene last framed
+     * the graph: a wheel or a drag. A repaint of the same space keeps a
+     * placed camera; a fresh space is framed whole.
+     *
+     * @returns True once the operator has wheeled or dragged since the last fit.
+     */
+    camera_touched(): boolean;
+    /**
+     * Draws the nodes as lit spheres or as stars. Moves nothing: the scene
+     * is redrawn where it stands, the camera where the operator put it.
+     *
+     * @param mode - The draw mode.
+     */
+    draw_set(mode: DrawMode): void;
+    /**
+     * Shows or hides the nodes' captions; nothing is redrawn.
+     *
+     * @param on - Shown.
+     */
+    captions_set(on: boolean): void;
+    /** @returns How nodes are drawn. */
+    draw_get(): DrawMode;
+    /**
+     * What the scene holds, for a surface asked to say so: how it draws,
+     * how many nodes are solid spheres and how many stars, which of the
+     * graph's solid-marked nodes are drawn solid, and the hand-off's state.
+     *
+     * @returns A plain summary.
+     */
+    state_get(): Record<string, unknown>;
+    /**
+     * Flies the camera toward one node, along the line it already looks
+     * down, to a distance where its neighbourhood fills the view: the zoom
+     * into the star the operator clicked, not a framing of all it belongs to.
+     *
+     * @param id - The node.
+     * @param distance - How far from it to stop, in scene units.
+     * @param durationMs - The flight's length.
+     * @param onDone - Called on arrival (at once when the node is not drawn).
+     */
+    camera_flyToward(id: string, distance: number, durationMs: number, onDone: () => void): void;
+    /**
+     * Whether the camera is parked inside a node.
+     *
+     * The fly-in dollies to just shy of a node's surface, so while this is
+     * true the pane is filled by the inside of one sphere. Anything that can
+     * leave an operator there without an overlay on top has to be able to ask
+     * this and fly them back.
+     *
+     * @returns True while the camera is held inside a node.
+     */
+    holding_get(): boolean;
+    /**
+     * Flies the camera back out to its pre-dive stance and releases the hold.
+     *
+     * @param onDone - Called once the camera is home.
+     */
+    flight_back(onDone: () => void): void;
+    /** Computes each fireable node's flare time, in ms into the wave. */
+    private waveSchedule_compute;
+    /** Applies the wave's flares for this frame; loops in ambient mode. */
+    private wave_animate;
+    /**
+     * Switches the layout strategy and re-lays the current graph.
+     *
+     * @param strategy - Ranked tiers or the force-settled molecule.
+     */
+    strategy_set(strategy: LayoutStrategy): void;
+    /** Clears the node selection (a new graph owes nothing to the old one). */
+    selection_clear(): void;
+    /**
+     * Lights the selected sphere and dims the rest, touching materials only.
+     * Selection used to rebuild the scene: every click re-ran the settle of
+     * every node (seconds, on three thousand) and refitted the camera to
+     * the whole graph, so a click on a sphere the operator had dollied up
+     * to threw them back out to the whole space before anything else
+     * happened, and a double click could never land. A selection is paint.
+     */
+    private selection_paint;
+    /** @returns The active layout strategy. */
+    strategy_get(): LayoutStrategy;
+    /** The active projection: the sculpted 3D stage, or the flat schematic. */
+    private projection;
+    /**
+     * Switches projection. 2D is the schematic reading: the layout flattens
+     * to the plane, the view squares up face-on, the idle spin rests, and an
+     * empty-space drag pans (there is no depth to orbit). 3D restores the
+     * sculpted stage.
+     *
+     * @param projection - The projection to show.
+     */
+    projection_set(projection: '3d' | '2d'): void;
+    /** @returns The active projection. */
+    projection_get(): '3d' | '2d';
+    /**
+     * Updates one node's look in place (its state changed on the progress
+     * channel) without re-laying the graph.
+     *
+     * @param nodeId - The node.
+     * @param look - How it looks now.
+     */
+    look_update(nodeId: string, look: NodeLook): void;
+    /** @returns The colours to draw with now. */
+    private palette_read;
+    /** Re-reads the palette (the THEME pill changed) and repaints. */
+    palette_refresh(): void;
+    /** Fits the renderer to the container's current box. */
+    size_fit(): void;
+    /** Tears the scene down and releases the GL context. */
+    dispose(): void;
+    /**
+     * Fits the camera to the placed graph: distance from the bounding sphere
+     * so a sprawling molecule (or a wide 2D settle) sits inside the frustum
+     * instead of clipping through the near plane as black voids — or leaving
+     * the view entirely.
+     */
+    /**
+     * Builds the census: one instanced member per collapsed count, on a
+     * fibonacci shell around its group's anchor; equal-count parent/child
+     * groups pair members by index, so chains of ×N groups render as
+     * branched filaments over the shell — the cell-surface reading.
+     */
+    private censusBuild;
+    private camera_fit;
+    /** Counts rebuilds, so a sliced settle overtaken by a newer one stops. */
+    private rebuildGen;
+    /** Whether a settle is running in slices, its readout up. */
+    private slicing;
+    /**
+     * Rebuilds meshes and edges from the current graph and strategy.
+     *
+     * @param fit - Frame the result.
+     * @param mode - How the graph settles; see {@link SettleMode}.
+     */
+    private rebuild;
+    /** The layout worker, made on the first big settle and kept. */
+    private layoutWorker;
+    /** How a hierarchy sits molecules around their anchor. */
+    private arrangement;
+    /** Where each arrangement's spheres stood, for a return to it. */
+    private arrangementMemory;
+    /**
+     * Arranges molecules as clumps or spokes. The space is laid out afresh:
+     * a remembered shape would keep the old arrangement.
+     *
+     * @param arrangement - The arrangement: a registered engine's name.
+     * @param remembered - Where its spheres stood, from a host's memory.
+     * @param redraw - Redraw at once; false when the host is about to hand
+     *   in the graph the arrangement needs (constellations bring their stars).
+     */
+    arrangement_set(arrangement: SpaceArrangement, remembered?: Record<string, [number, number, number]>, redraw?: boolean): void;
+    /** @returns How a hierarchy sits molecules round their hubs. */
+    arrangement_get(): SpaceArrangement;
+    /**
+     * Settles the graph as a hierarchy in the worker, reporting progress, and
+     * draws the answer if no newer rebuild has overtaken it.
+     */
+    private hierarchy_run;
+    /** Draws placed nodes as the scene: meshes, edges, census, the frame. */
+    private draw;
+    /**
+     * Plays the space's history: every node with an arrival hidden until it
+     * arrives, then shown with a flash, at its final place, the camera
+     * untouched. Nodes without one stand throughout. Nothing turns solid
+     * while it plays; stars only.
+     *
+     * @param arrivals - When each node arrived (epoch ms for dates).
+     * @param speed - 1 crosses the whole history in {@link REPLAY_WALL_MS}.
+     */
+    replay_begin(arrivals: ReadonlyMap<string, number>, speed?: number): void;
+    /**
+     * Plays on (or again from the start, at the end).
+     *
+     * @param speed - A new speed, or the one it had.
+     */
+    replay_play(speed?: number): void;
+    /** Holds the replay where it is. */
+    replay_pause(): void;
+    /**
+     * Moves the replay to a moment: what had arrived by then shown, the rest hidden.
+     *
+     * @param at - The moment, in the arrivals' units.
+     */
+    replay_seek(at: number): void;
+    /** Ends the replay: the space redrawn whole, the hand-off back. */
+    replay_stop(): void;
+    /**
+     * Where the replay stands, or null when none runs.
+     *
+     * @returns Whether it plays, its moment, and its span.
+     */
+    replay_state(): {
+        playing: boolean;
+        at: number;
+        span: [number, number];
+    } | null;
+    /** One frame of the replay: arrivals shown, departures hidden, flashes faded. */
+    private replay_step;
+    /** Shows what arrived and hides what left, threads following. */
+    private replay_apply;
+    /** Paints every dated node as the replay has it: shown if arrived, else hidden. */
+    private replay_paintAll;
+    /**
+     * Steps the hand-off once a frame: a feed whose largest sphere spans
+     * more than a few pixels turns solid, crossfading, its threads rising
+     * to edges; one that shrinks back goes to stars and its spheres are let go.
+     */
+    private handoff_step;
+    /**
+     * How a placed node's sphere is drawn when its molecule turns solid.
+     *
+     * @param id - The node.
+     * @returns Where it stands, how large, what hue.
+     */
+    private handoffLook_of;
+    /**
+     * A placed node as the tubes read it.
+     *
+     * @param id - The node.
+     * @returns Where it stands, how large, what it hangs from, its state.
+     */
+    private tubeNode_of;
+    /**
+     * A cluster's handle while the scene draws stars: a soft glow at its
+     * anchor, facing the camera, sized as its halo would be.
+     */
+    private nebula_add;
+    /**
+     * Where a drawn node stands in the world and how big it is — a sphere,
+     * a star or a census member alike — for flights and framing.
+     *
+     * @param id - The node.
+     * @returns Its world position and radius, or null when it is not drawn.
+     */
+    private nodeWorld_of;
+    /** Every drawn node's id: spheres and stars. */
+    private drawnIds;
+    /** Copies simulation positions onto meshes and re-anchors every edge. */
+    private positions_sync;
+    /**
+     * A press the gestures could not place: when it landed on a node it
+     * begins a pull (the structure reacts through a live force simulation
+     * anchored at the grabbed node) and the press is the scene's to follow.
+     *
+     * @param event - The press.
+     * @returns True when a node was taken hold of.
+     */
+    private grab_begin;
+    /**
+     * Builds the reaction simulation, from the meshes' current positions with
+     * the grabbed node fixed. Deferred to the first real pointer movement: a
+     * heated simulation on a mere press would shift nodes out from under the
+     * click and dblclick raycasts. Links and charge only — no centering
+     * force, or the pull would fight a recentering spring.
+     */
+    private dragSim_begin;
+    /** Follows the pointer during a pull: the grabbed node tracks the drag plane. */
+    private drag_move;
+    /** Nodes easing home after a ranked peek: mesh, from, to, start time. */
+    private dragReturns;
+    /**
+     * Releases a pull: the grip opens and the simulation cools to rest.
+     *
+     * @returns Whether the pull had moved, so its click is swallowed.
+     */
+    private grab_end;
+    /**
+     * Draws nodes as lit spheres joined by tubes, among a census: the feed the
+     * operator entered, which the census's points would otherwise swallow.
+     *
+     * @param solidOnes - The nodes to draw solid.
+     * @param palette - The palette.
+     */
+    private solid_draw;
+    /**
+     * The pointer left the field. A finger lifting leaves at once, so its
+     * name stays up a moment to be read; a cursor's goes with it.
+     *
+     * @param event - The leave.
+     */
+    private leave_handle;
+    /** Names the node under the pointer in the hover tip, or hides it. */
+    private hover_handle;
+    /** Resolves a pointer event to a node and fires the matching handler. */
+    private pick_handle;
+}