@fnndsc/orrery 0.1.0

package/dist/controls/picker.js

@@ -0,0 +1,167 @@
+/**
+ * @file Picking: what lies under a pointer, however it is drawn.
+ *
+ * The drawers keep what they draw; the picker asks the scene for it as
+ * plain sources — meshes, stars and nebulae as points with a reach, a
+ * census that picks by ray — and answers with an id. In order: a solid
+ * sphere wins (an entered feed stands as spheres among stars), then a
+ * census member, then the nearest star within its drawn size, then a
+ * nebula the pointer is inside. A dimmed thing is scenery and takes no
+ * pointer; a halo wrapping a cluster is taken only when nothing solid lies
+ * along the ray.
+ *
+ * @module
+ */
+import * as THREE from 'three';
+/** A fingertip is wider than a cursor: the least a star reaches for one. */
+export const TOUCH_REACH_PX = 14;
+/** The least a star reaches for a cursor. */
+export const CURSOR_REACH_PX = 4;
+/**
+ * Finds what lies under a pointer.
+ */
+export class Picker {
+    camera;
+    world;
+    element;
+    sources;
+    starGlow;
+    raycaster = new THREE.Raycaster();
+    /**
+     * @param camera - The eye.
+     * @param world - The group every drawer hangs from.
+     * @param element - The canvas, for where a pointer falls on it.
+     * @param sources - What can be picked.
+     * @param starGlow - How far a star's glow reaches, in radii: its drawn size.
+     */
+    constructor(camera, world, element, sources, starGlow) {
+        this.camera = camera;
+        this.world = world;
+        this.element = element;
+        this.sources = sources;
+        this.starGlow = starGlow;
+    }
+    /**
+     * Aims the ray from the eye through the pointer, the world current.
+     *
+     * @param at - The pointer.
+     * @returns The aimed raycaster (shared: read it before the next aim).
+     */
+    ray_aim(at) {
+        const bounds = this.element.getBoundingClientRect();
+        const pointer = new THREE.Vector2(((at.clientX - bounds.left) / bounds.width) * 2 - 1, -((at.clientY - bounds.top) / bounds.height) * 2 + 1);
+        // A pick can land between a rebuild and its first render, when fresh
+        // meshes still carry identity matrices: bring them current.
+        this.world.updateMatrixWorld(true);
+        this.raycaster.setFromCamera(pointer, this.camera);
+        return this.raycaster;
+    }
+    /**
+     * The solid sphere under the pointer. A halo wraps its cluster, so its
+     * surface is hit before the spheres inside it: a solid hit anywhere along
+     * the ray wins, the halo only when nothing solid is.
+     *
+     * @param at - The pointer.
+     * @returns The mesh, or null.
+     */
+    mesh_under(at) {
+        const hits = this.ray_aim(at)
+            .intersectObjects([...this.sources.meshes()])
+            .filter((hit) => hit.object.userData['dim'] !== true);
+        const solid = hits.find((hit) => hit.object.userData['halo'] !== true);
+        const object = (solid ?? hits[0])?.object;
+        return object instanceof THREE.Mesh ? object : null;
+    }
+    /**
+     * The node behind the solid sphere under the pointer.
+     *
+     * @param at - The pointer.
+     * @returns Its id, or null.
+     */
+    meshNode_under(at) {
+        const nodeId = this.mesh_under(at)?.userData['nodeId'];
+        return typeof nodeId === 'string' ? nodeId : null;
+    }
+    /**
+     * The node under the pointer, however it is drawn: a solid sphere, a
+     * census member, or a star (or nebula) when nothing solid is.
+     *
+     * @param at - The pointer.
+     * @param touch - Whether a finger is asking: a star reaches farther for one.
+     * @returns Its id, or null.
+     */
+    node_under(at, touch) {
+        const solid = this.meshNode_under(at);
+        if (solid !== null)
+            return solid;
+        const census = this.sources.census();
+        if (census !== null)
+            return census.pick(this.ray_aim(at));
+        return this.star_under(at, touch);
+    }
+    /**
+     * The star — or, over no star, the nebula — under the pointer, picked in
+     * screen space: a star is hit within its drawn size (never less than a
+     * few pixels, more for a finger), the nearest centre for its size wins.
+     *
+     * @param at - The pointer.
+     * @param touch - Whether a finger is asking.
+     * @returns Its id, or null.
+     */
+    star_under(at, touch) {
+        const stars = this.sources.stars();
+        const nebulae = this.sources.nebulae();
+        const bounds = this.element.getBoundingClientRect();
+        const px = at.clientX - bounds.left;
+        const py = at.clientY - bounds.top;
+        this.world.updateMatrixWorld(true);
+        this.camera.updateMatrixWorld();
+        const perUnit = bounds.height / (2 * Math.tan((this.camera.fov * Math.PI) / 360));
+        // One matrix from the group's space to the screen's, one scratch
+        // reading: a census can hold tens of thousands of stars, and this runs
+        // on every pointer move.
+        const view = new THREE.Matrix4().multiplyMatrices(this.camera.matrixWorldInverse, this.world.matrixWorld);
+        const clip = new THREE.Matrix4().multiplyMatrices(this.camera.projectionMatrix, view);
+        const e = clip.elements;
+        const v = view.elements;
+        const screen = (p) => {
+            const depth = -(v[2] * p.x + v[6] * p.y + v[10] * p.z + v[14]);
+            if (depth <= 0)
+                return null;
+            const w = e[3] * p.x + e[7] * p.y + e[11] * p.z + e[15];
+            const x = (e[0] * p.x + e[4] * p.y + e[8] * p.z + e[12]) / w;
+            const y = (e[1] * p.x + e[5] * p.y + e[9] * p.z + e[13]) / w;
+            return { x: (x + 1) / 2 * bounds.width, y: (1 - y) / 2 * bounds.height, depth };
+        };
+        const floor = touch ? TOUCH_REACH_PX : CURSOR_REACH_PX;
+        let best = null;
+        let bestScore = Infinity;
+        for (const star of stars) {
+            if (star.dim)
+                continue;
+            const hit = screen(star.position);
+            if (hit === null)
+                continue;
+            const reach = Math.max(floor, (this.starGlow * star.radius * perUnit) / hit.depth);
+            const distance = Math.hypot(hit.x - px, hit.y - py);
+            if (distance > reach)
+                continue;
+            const score = distance / reach;
+            if (score < bestScore) {
+                bestScore = score;
+                best = star.id;
+            }
+        }
+        if (best !== null)
+            return best;
+        for (const nebula of nebulae) {
+            const hit = screen(nebula.position);
+            if (hit === null)
+                continue;
+            if (Math.hypot(hit.x - px, hit.y - py) <= (nebula.radius * perUnit) / hit.depth)
+                return nebula.id;
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=picker.js.map

package/dist/controls/picker.js.map

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

package/dist/controls/replay.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @file The replay: a space's history played back in the order it arrived.
+ *
+ * Every node the surface can date has an arrival time. A replay runs from
+ * the first arrival to the last in a fixed stretch of wall time (scaled by
+ * a speed), and says, frame by frame, which nodes have arrived since the
+ * last frame and which have left (a seek backwards). A node that arrives
+ * flashes, and the flash fades; the camera is untouched, the positions are
+ * the final ones, and a node with no arrival time stands throughout.
+ *
+ * Pure: a clock the caller can drive, no renderer.
+ *
+ * @module
+ */
+/** How long, in wall time, a replay at speed 1 takes from first arrival to last. */
+export declare const REPLAY_WALL_MS: number;
+/** How long an arrival's flash lasts, in wall time. */
+export declare const REPLAY_FLASH_MS: number;
+/**
+ * One frame's news.
+ *
+ * @property at - The replay's moment, in the arrivals' own units (epoch ms).
+ * @property arrived - Nodes that arrived since the last frame.
+ * @property departed - Nodes that are no longer there (a seek backwards).
+ * @property done - The replay has reached the last arrival.
+ */
+export interface ReplayFrame {
+    at: number;
+    arrived: string[];
+    departed: string[];
+    done: boolean;
+}
+/**
+ * A replay's clock.
+ */
+export declare class ReplayClock {
+    private readonly clock;
+    private readonly order;
+    private readonly first;
+    private readonly last;
+    /** How many of `order` are shown. */
+    private shown;
+    /** The replay's moment. */
+    private moment;
+    private speed;
+    private running;
+    private lastWall;
+    private readonly flashes;
+    /**
+     * @param arrivals - When each node arrived (any monotonic unit; epoch ms
+     *   for dates). Nodes absent from it stand throughout.
+     * @param clock - Wall-clock milliseconds; `Date.now` unless a test drives time.
+     */
+    constructor(arrivals: ReadonlyMap<string, number>, clock?: () => number);
+    /** @returns The first and last arrivals. */
+    span(): [number, number];
+    /** @returns Every node with an arrival, in arrival order. */
+    ids(): string[];
+    /** @returns Whether the replay is advancing. */
+    playing(): boolean;
+    /** @returns The replay's moment. */
+    at(): number;
+    /**
+     * Plays on, at a speed: 1 crosses the whole history in {@link REPLAY_WALL_MS}.
+     *
+     * @param speed - How much faster than 1; a replay at its end starts over.
+     */
+    play(speed?: number): void;
+    /** Holds the replay where it is. */
+    pause(): void;
+    /**
+     * Moves the replay to a moment. Nodes arrived by then are shown at once,
+     * without a flash; nodes that arrive after it are hidden again.
+     *
+     * @param at - The moment, clamped to the span.
+     * @returns What changed.
+     */
+    seek(at: number): ReplayFrame;
+    /**
+     * Advances by the wall time since the last frame, if playing. What arrives
+     * begins to flash; a replay that reaches the last arrival pauses there.
+     *
+     * @returns This frame's news.
+     */
+    step(): ReplayFrame;
+    /**
+     * The nodes still flashing, and how bright: 1 as they arrive, fading to 0
+     * over {@link REPLAY_FLASH_MS}. A flash that has faded is forgotten, and
+     * reported once at 0 so its light can be put back.
+     *
+     * @returns Each flashing node's brightness.
+     */
+    flashing(): Map<string, number>;
+}

package/dist/controls/replay.js

@@ -0,0 +1,147 @@
+/**
+ * @file The replay: a space's history played back in the order it arrived.
+ *
+ * Every node the surface can date has an arrival time. A replay runs from
+ * the first arrival to the last in a fixed stretch of wall time (scaled by
+ * a speed), and says, frame by frame, which nodes have arrived since the
+ * last frame and which have left (a seek backwards). A node that arrives
+ * flashes, and the flash fades; the camera is untouched, the positions are
+ * the final ones, and a node with no arrival time stands throughout.
+ *
+ * Pure: a clock the caller can drive, no renderer.
+ *
+ * @module
+ */
+/** How long, in wall time, a replay at speed 1 takes from first arrival to last. */
+export const REPLAY_WALL_MS = 30_000;
+/** How long an arrival's flash lasts, in wall time. */
+export const REPLAY_FLASH_MS = 900;
+/**
+ * A replay's clock.
+ */
+export class ReplayClock {
+    clock;
+    order;
+    first;
+    last;
+    /** How many of `order` are shown. */
+    shown = 0;
+    /** The replay's moment. */
+    moment;
+    speed = 1;
+    running = false;
+    lastWall;
+    flashes = new Map();
+    /**
+     * @param arrivals - When each node arrived (any monotonic unit; epoch ms
+     *   for dates). Nodes absent from it stand throughout.
+     * @param clock - Wall-clock milliseconds; `Date.now` unless a test drives time.
+     */
+    constructor(arrivals, clock = Date.now) {
+        this.clock = clock;
+        this.order = [...arrivals].map(([id, at]) => ({ id, at })).sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : 1));
+        this.first = this.order[0]?.at ?? 0;
+        this.last = this.order[this.order.length - 1]?.at ?? 0;
+        this.moment = this.first;
+        this.lastWall = clock();
+    }
+    /** @returns The first and last arrivals. */
+    span() {
+        return [this.first, this.last];
+    }
+    /** @returns Every node with an arrival, in arrival order. */
+    ids() {
+        return this.order.map((entry) => entry.id);
+    }
+    /** @returns Whether the replay is advancing. */
+    playing() {
+        return this.running;
+    }
+    /** @returns The replay's moment. */
+    at() {
+        return this.moment;
+    }
+    /**
+     * Plays on, at a speed: 1 crosses the whole history in {@link REPLAY_WALL_MS}.
+     *
+     * @param speed - How much faster than 1; a replay at its end starts over.
+     */
+    play(speed = this.speed) {
+        this.speed = Math.max(0.05, speed);
+        if (this.moment >= this.last && this.shown >= this.order.length)
+            this.seek(this.first);
+        this.running = true;
+        this.lastWall = this.clock();
+    }
+    /** Holds the replay where it is. */
+    pause() {
+        this.running = false;
+    }
+    /**
+     * Moves the replay to a moment. Nodes arrived by then are shown at once,
+     * without a flash; nodes that arrive after it are hidden again.
+     *
+     * @param at - The moment, clamped to the span.
+     * @returns What changed.
+     */
+    seek(at) {
+        this.moment = Math.max(this.first, Math.min(this.last, at));
+        const arrived = [];
+        const departed = [];
+        while (this.shown < this.order.length && this.order[this.shown].at <= this.moment) {
+            arrived.push(this.order[this.shown].id);
+            this.shown += 1;
+        }
+        while (this.shown > 0 && this.order[this.shown - 1].at > this.moment) {
+            this.shown -= 1;
+            const id = this.order[this.shown].id;
+            departed.push(id);
+            this.flashes.delete(id);
+        }
+        return { at: this.moment, arrived, departed, done: this.moment >= this.last };
+    }
+    /**
+     * Advances by the wall time since the last frame, if playing. What arrives
+     * begins to flash; a replay that reaches the last arrival pauses there.
+     *
+     * @returns This frame's news.
+     */
+    step() {
+        const wall = this.clock();
+        const elapsed = wall - this.lastWall;
+        this.lastWall = wall;
+        if (!this.running)
+            return { at: this.moment, arrived: [], departed: [], done: this.moment >= this.last };
+        const perWall = (this.last - this.first) / REPLAY_WALL_MS * this.speed;
+        // A history of one moment is crossed at once.
+        const frame = this.seek(perWall > 0 ? this.moment + elapsed * perWall : this.last);
+        for (const id of frame.arrived)
+            this.flashes.set(id, wall);
+        if (frame.done)
+            this.running = false;
+        return frame;
+    }
+    /**
+     * The nodes still flashing, and how bright: 1 as they arrive, fading to 0
+     * over {@link REPLAY_FLASH_MS}. A flash that has faded is forgotten, and
+     * reported once at 0 so its light can be put back.
+     *
+     * @returns Each flashing node's brightness.
+     */
+    flashing() {
+        const wall = this.clock();
+        const out = new Map();
+        for (const [id, began] of this.flashes) {
+            const t = (wall - began) / REPLAY_FLASH_MS;
+            if (t >= 1) {
+                this.flashes.delete(id);
+                out.set(id, 0);
+            }
+            else {
+                out.set(id, 1 - t);
+            }
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=replay.js.map

package/dist/controls/replay.js.map

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

package/dist/draw/censusField.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @file The census: every job of every stage.
+ *
+ * A stage that stands for many jobs is drawn as a shell of them around its
+ * place, each job its own sphere (or, under stars, its own point of light);
+ * each job is joined to a job of its parent stage — by tubes that carry
+ * the feed's pulses while there are few enough of them, by lines past that.
+ * A wave down the graph flares every job of a stage together.
+ *
+ * @module
+ */
+import * as THREE from 'three';
+import type { NodeState } from '../types/encoding.js';
+import type { Palette } from './palette.js';
+import type { StarField } from './starField.js';
+import { type TubeField } from './tubeField.js';
+/**
+ * One stage as the census draws it.
+ *
+ * @property id - The stage.
+ * @property position - Where it stands.
+ * @property radius - Its sphere's radius as a single node.
+ * @property count - How many jobs it stands for.
+ * @property color - Its hue.
+ * @property dim - Faint scenery.
+ * @property ember - Some of its jobs failed: under stars, drawn solid over the glow.
+ * @property state - What it is doing.
+ * @property parents - The stages it hangs from.
+ * @property ghost - An anchor, not a stage: it counts in the cloud's centre
+ *   and in how deep a stage lies, and draws no jobs.
+ */
+export interface CensusNode {
+    id: string;
+    position: THREE.Vector3;
+    radius: number;
+    count: number;
+    color: THREE.Color;
+    dim: boolean;
+    ember: boolean;
+    state: NodeState;
+    parents: ReadonlyArray<string>;
+    ghost?: boolean;
+}
+/** Where a census cloud stands and how far it reaches, for framing it. */
+export interface CensusCloud {
+    center: THREE.Vector3;
+    radius: number;
+}
+/** What a census draws with. */
+export interface CensusHost {
+    parent: THREE.Object3D;
+    stars: StarField;
+    tubes: TubeField;
+    /** The display's pixel ratio, the canvas height in device pixels, the camera's field of view. */
+    starsView(): {
+        pixelRatio: number;
+        heightPx: number;
+        fovDeg: number;
+    };
+}
+/** Every job of every stage, drawn. */
+export declare class CensusField {
+    private readonly host;
+    private mesh;
+    private base;
+    private memberIds;
+    private memberPositions;
+    /**
+     * @param host - What the census draws with.
+     */
+    constructor(host: CensusHost);
+    /** Whether the census is drawn as instanced spheres (not stars). */
+    drawn(): boolean;
+    /** The stage behind each job, in draw order. */
+    ids(): ReadonlyArray<string>;
+    /** Where each job stands, in draw order. */
+    positions(): ReadonlyArray<THREE.Vector3>;
+    /**
+     * Draws the census.
+     *
+     * @param nodes - The stages.
+     * @param starring - Draw jobs as points of light, not spheres.
+     * @param palette - The colours.
+     * @returns Where the cloud stands and how far it reaches.
+     */
+    build(nodes: ReadonlyArray<CensusNode>, starring: boolean, palette: Palette): CensusCloud;
+    /**
+     * Flares every job of a stage with the wave, written straight into the
+     * instance colours.
+     *
+     * @param fireAt - When a stage fires, by id; undefined when it does not.
+     * @param elapsed - Time since the wave set off.
+     * @param pulse - The flare's hue.
+     * @param flareMs - How long a flare lasts.
+     * @returns The latest a stage fires, so the caller knows when the wave is done.
+     */
+    flare(fireAt: (id: string) => number | undefined, elapsed: number, pulse: THREE.Color, flareMs: number): number;
+    /**
+     * The stage behind the job a ray meets first; the touched job lights up.
+     *
+     * @param raycaster - The ray, aimed by the caller.
+     * @returns The stage, or null.
+     */
+    pick(raycaster: THREE.Raycaster): string | null;
+    /** Forgets everything: the scene is being redrawn. */
+    clear(): void;
+    /**
+     * Joins the jobs with tubes: each to the job of its parent stage it stands
+     * against, in the stage's hue (red into a failed one); a live stage
+     * streams, a finished run replays with every job of a stage together.
+     */
+    private tubes_build;
+}