visualproof 0.1.0 → 0.3.0

package/dist/web/src/drag.js

@@ -0,0 +1,61 @@
+// What a drag on the canvas does (CanvasSpec, "Hover, click, drag", decided 2026-10-09): it pans the
+// view, by default, as a drag on empty space does; with the layout's lock let go (`l`, or the lock
+// behind ⋯) a drag on a declaration, a circle or a note moves it, for everyone on the board. The drag
+// key held at the press does the other way for that drag. The choice is the reader's, kept in this
+// browser for every project, as the theme is: a new visitor starts with the lock on, panning.
+//
+// The drag key is ⌘ on a Mac and Ctrl elsewhere (the owner's decision, 2026-10-11): on a Mac,
+// Ctrl+click is the secondary click, so Ctrl does nothing to drags there and a Ctrl+click stays the
+// right click, the canvas's menu. Ctrl and the wheel (a trackpad's pinch) zooms on every platform.
+const KEY = "visualproof:drag";
+/** Whether the page runs on a Mac — macOS, or iPadOS and iOS, whose keyboards have ⌘ too — by the
+ *  platform the browser names (`userAgentData` where it has one), else `navigator.platform` (an iPad
+ *  asking for desktop pages says MacIntel), else its user agent. */
+export function onMac(nav) {
+    const named = nav?.userAgentData?.platform || nav?.platform;
+    if (named)
+        return /^(mac|ios|iphone|ipad|ipod)/i.test(named);
+    return /Macintosh|Mac OS X|iPhone|iPad|iPod/.test(nav?.userAgent ?? "");
+}
+/** The page's platform, read once. */
+export const MAC = onMac(typeof navigator === "undefined" ? undefined : navigator);
+/** The drag key as the page names it: ⌘ on a Mac, Ctrl elsewhere. */
+export const dragKeyName = (mac = MAC) => (mac ? "⌘" : "Ctrl");
+/** Whether a pointer event was made with the drag key held: ⌘ alone on a Mac, Ctrl alone elsewhere
+ *  (⊞ or Super is the system's there). */
+export const dragKeyHeld = (e, mac = MAC) => (mac ? e.metaKey : e.ctrlKey);
+/** Whether a key, pressed or let go, is the drag key itself (KeyboardEvent.key). */
+export const isDragKey = (key, mac = MAC) => key === (mac ? "Meta" : "Control");
+/** Whether a press of the main button is a Mac's Ctrl+click, its secondary click: the browser opens
+ *  the canvas's menu on it (contextmenu), so let go where it was pressed it is no click of the page's
+ *  — it selects, toggles and opens nothing — while dragged it is a drag as any, Ctrl doing nothing to
+ *  drags there. */
+export const menuClick = (e, mac = MAC) => mac && e.button === 0 && e.ctrlKey;
+/** Whether a drag that starts on something moves it, rather than panning the view: the lock let go
+ *  and the drag key not held, or the lock on and the drag key held. */
+export function dragMoves(locked, held) {
+    return locked === held;
+}
+/** The lock as this browser keeps it: on unless the reader let it go. */
+export function lockedChoice() {
+    try {
+        return localStorage.getItem(KEY) !== "move";
+    }
+    catch {
+        // storage blocked: the default
+        return true;
+    }
+}
+/** Keep the reader's choice: the default (locked) is kept as nothing, so that a later change of
+ *  the default reaches whoever never chose. */
+export function setLockedChoice(locked) {
+    try {
+        if (locked)
+            localStorage.removeItem(KEY);
+        else
+            localStorage.setItem(KEY, "move");
+    }
+    catch {
+        // not kept: in force for this page only
+    }
+}

package/dist/web/src/edgequeue.js

@@ -0,0 +1,204 @@
+// The overview's zoom points, asked of a worker (web/src/edgeworker.ts) and kept as they come back
+// (CanvasSpec.md, "Edges"; the owner's request, 2026-10-10). The page asks for the points the camera
+// needs and one ahead in the direction it zooms; a few questions at most are out at once, and the
+// latest wins: an answer older than the point already held is dropped, and so is one whose point is
+// no longer near the camera when it comes, or that was chosen for a tree since replaced. Where no
+// worker can be had (no `Worker`, its file not served, the tests), the points are chosen on the page's
+// thread at once, as they used to be.
+import { OverviewModel, indexLooks } from "./overview.js";
+/** At most this many questions are out at once: one being answered, one waiting behind it. */
+export const IN_FLIGHT = 2;
+export class EdgeQueue {
+    /** the points held, by zoom-point index, all chosen for the tree now (`base`) */
+    points = new Map();
+    pending = new Map();
+    worker = null;
+    /** no worker: the page chooses itself, at once */
+    local = null;
+    spawn;
+    onReady;
+    graph = null;
+    tree = null;
+    toggles = { externals: true };
+    base = 0;
+    lo = -Infinity;
+    hi = Infinity;
+    next = 1;
+    serial = 0;
+    /** answers dropped (stale, superseded, another tree's) and answers kept, and how long the worker
+     *  took for the last one, ms */
+    dropped = 0;
+    answered = 0;
+    lastMs = 0;
+    /** how long an answer takes to come, waiting included, ms (smoothed): how far ahead a fast zoom
+     *  is asked for */
+    wait = 50;
+    /** `spawn`: a worker, or null where none can be had; `onReady`: something came back (a point, or a
+     *  question let go), so the page draws again and asks for what still waits. */
+    constructor(spawn, onReady) {
+        this.spawn = spawn;
+        this.onReady = onReady;
+    }
+    /** Whether the points are chosen on the page's thread (no worker). */
+    get onPageThread() {
+        if (!this.worker && !this.local)
+            this.start();
+        return this.local !== null;
+    }
+    /** How many questions are out. */
+    get inFlight() {
+        return this.pending.size;
+    }
+    /** A new graph: its edges go to the worker (a copy: the page keeps its own). */
+    setGraph(g) {
+        this.graph = g;
+        if (this.onPageThread)
+            this.local.setGraph(g);
+        else
+            this.send({ type: "graph", n: g.n, projectCount: g.projectCount, outStart: g.outStart, outDst: g.outDst, outSite: g.outSite });
+    }
+    /** A new tree (a layout, folds) or new toggles: every point held is let go, and answers to
+     *  questions asked before are dropped when they come. On the page's thread the scene's own arrays
+     *  are read; a worker is sent a copy. */
+    setBase(tree, toggles) {
+        this.base++;
+        this.tree = tree;
+        this.toggles = { ...toggles };
+        this.points.clear();
+        this.lo = -Infinity;
+        this.hi = Infinity;
+        if (this.onPageThread)
+            this.local.setTree(tree, toggles);
+        else
+            this.sendTree();
+    }
+    /** The zoom points still wanted, [lo, hi]: the worker drops questions for others, and an answer
+     *  for another is dropped when it comes. */
+    near(lo, hi) {
+        if (lo === this.lo && hi === this.hi)
+            return;
+        this.lo = lo;
+        this.hi = hi;
+        if (this.worker)
+            this.send({ type: "near", base: this.base, lo, hi });
+    }
+    /** The latest question out for point `i` under the tree now, if any. */
+    asked(i) {
+        let best;
+        for (const p of this.pending.values())
+            if (p.base === this.base && p.ask.point === i && (!best || p.id > best.id))
+                best = p;
+        return best?.ask;
+    }
+    /** Ask for a point, with the positions `places` gives (read at once on the page's thread, copied
+     *  for a worker). False when IN_FLIGHT questions are already out: ask again when one comes back. */
+    ask(a, places) {
+        const id = this.next++;
+        if (this.onPageThread) {
+            this.keep(id, a, this.local.choose(a, places()));
+            return true;
+        }
+        if (this.pending.size >= IN_FLIGHT)
+            return false;
+        this.pending.set(id, { id, base: this.base, ask: a, at: performance.now() });
+        const P = places();
+        const copy = { cwx: P.cwx.slice(), cwy: P.cwy.slice(), nwx: P.nwx.slice(), nwy: P.nwy.slice(), curR: P.curR.slice(), drawnR: P.drawnR.slice() };
+        const { style: _style, ...ask } = a;
+        this.send({ type: "choose", id, base: this.base, places: copy, ...ask }, Object.values(copy).map((x) => x.buffer));
+        return true;
+    }
+    /** Let go of the points `keep` does not want. */
+    evict(keep) {
+        for (const i of [...this.points.keys()])
+            if (!keep(i))
+                this.points.delete(i);
+    }
+    /** A point's looks by edge key. */
+    indexOf(p) {
+        return (p.index ??= indexLooks(p.looks));
+    }
+    keep(id, a, looks) {
+        this.answered++;
+        this.points.set(a.point, { point: a.point, looks, index: null, x: a.x, y: a.y, dim: a.dim, style: a.style, id, serial: ++this.serial });
+    }
+    start() {
+        let w = null;
+        try {
+            w = this.spawn();
+        }
+        catch {
+            w = null;
+        }
+        if (!w) {
+            this.toPageThread();
+            return;
+        }
+        this.worker = w;
+        w.onmessage = (e) => {
+            if (this.worker === w)
+                this.answer(e.data);
+        };
+        // a worker that cannot run (its file not served): the page chooses itself, from now on
+        w.onerror = () => {
+            if (this.worker !== w)
+                return;
+            this.fail();
+            this.onReady();
+        };
+    }
+    /** The worker is given up: the page chooses itself from now on, and what was out is asked again,
+     *  on the page's thread, at the next frame. */
+    fail() {
+        this.worker?.terminate();
+        this.worker = null;
+        this.toPageThread();
+        this.pending.clear();
+    }
+    toPageThread() {
+        this.local = new OverviewModel();
+        if (this.graph)
+            this.local.setGraph(this.graph);
+        if (this.tree)
+            this.local.setTree(this.tree, this.toggles);
+    }
+    answer(m) {
+        const p = this.pending.get(m.id);
+        if (!p)
+            return;
+        this.pending.delete(m.id);
+        if (m.type === "looks") {
+            this.lastMs = m.ms;
+            this.wait = 0.7 * this.wait + 0.3 * (performance.now() - p.at);
+            const held = this.points.get(p.ask.point);
+            // another tree's, no longer near the camera, or older than what is held: the latest wins
+            if (p.base !== this.base || p.ask.point < this.lo || p.ask.point > this.hi || (held && held.id > m.id))
+                this.dropped++;
+            else
+                this.keep(m.id, p.ask, m.looks);
+        }
+        else if (m.type === "dropped")
+            this.dropped++;
+        else if (m.type === "error") {
+            // the worker could not: the page chooses itself from now on, where what goes wrong shows
+            console.warn(`the overview's worker could not choose a point: ${m.error}`);
+            this.fail();
+        }
+        this.onReady();
+    }
+    sendTree() {
+        const T = this.tree;
+        this.send({
+            type: "tree",
+            base: this.base,
+            nc: T.nc,
+            n: T.n,
+            parent: T.parent,
+            nodeCluster: T.nodeCluster,
+            rep: T.rep,
+            externals: this.toggles.externals,
+        });
+    }
+    send(m, transfer = []) {
+        this.worker.postMessage(m, transfer);
+    }
+}

package/dist/web/src/gl/gl.js

@@ -0,0 +1,123 @@
+// Small WebGL2 helpers: programs, instanced buffers, colours.
+const colorCache = new Map();
+let probe = null;
+/** Any CSS colour → premultiplied-ready straight RGBA in 0..1, by letting the browser parse it; with
+ *  no browser (the artwork command, ExportSpec decision 21), as `parseColour` reads it. */
+export function rgba(css, alpha = 1) {
+    const key = css;
+    let c = colorCache.get(key);
+    if (!c) {
+        if (typeof document === "undefined")
+            c = parseColour(css);
+        else {
+            probe ??= document.createElement("canvas").getContext("2d", { willReadFrequently: true });
+            probe.clearRect(0, 0, 1, 1);
+            probe.fillStyle = "#000";
+            probe.fillStyle = css || "transparent";
+            probe.fillRect(0, 0, 1, 1);
+            const d = probe.getImageData(0, 0, 1, 1).data;
+            c = [d[0] / 255, d[1] / 255, d[2] / 255, d[3] / 255];
+        }
+        colorCache.set(key, c);
+    }
+    return [c[0], c[1], c[2], c[3] * alpha];
+}
+/** the named colours the page's colours use, and those a canvas takes for granted */
+const NAMED = { transparent: "#0000", black: "#000", white: "#fff", red: "#f00", green: "#008000", blue: "#00f", gray: "#808080", grey: "#808080", orange: "#ffa500", gold: "#ffd700" };
+/** A CSS colour read without a browser, as a canvas would draw it (in 0..1, its alpha straight, its
+ *  channels rounded to bytes as a canvas keeps them): `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`,
+ *  `rgb()`/`rgba()` (commas or spaces, numbers or percentages, `/ alpha`), `hsl()`/`hsla()` and a few
+ *  names; anything else is transparent. */
+export function parseColour(css) {
+    let s = (css || "").trim().toLowerCase();
+    s = NAMED[s] ?? s;
+    const byte = (v) => Math.round(Math.min(255, Math.max(0, v))) / 255;
+    const hex = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(s);
+    if (hex) {
+        let h = hex[1];
+        if (h.length <= 4)
+            h = [...h].map((x) => x + x).join("");
+        const n = (i) => parseInt(h.slice(i, i + 2), 16);
+        return [n(0) / 255, n(2) / 255, n(4) / 255, h.length === 8 ? n(6) / 255 : 1];
+    }
+    const fn = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(s);
+    if (!fn)
+        return [0, 0, 0, 0];
+    const parts = fn[2].replace(/\//g, " / ").split(/[\s,]+/).filter((x) => x && x !== "/");
+    const num = (x, scale) => (x === undefined ? NaN : x.endsWith("%") ? (parseFloat(x) / 100) * scale : parseFloat(x));
+    const a = parts.length > 3 ? Math.min(1, Math.max(0, num(parts[3], 1))) : 1;
+    if (fn[1].startsWith("rgb")) {
+        const [r, g, b] = [0, 1, 2].map((i) => num(parts[i], 255));
+        return [r, g, b].some(Number.isNaN) ? [0, 0, 0, 0] : [byte(r), byte(g), byte(b), Number.isNaN(a) ? 1 : Math.round(a * 255) / 255];
+    }
+    const h = (((parseFloat(parts[0]) % 360) + 360) % 360) / 360, sat = num(parts[1], 1), l = num(parts[2], 1);
+    if ([h, sat, l].some(Number.isNaN))
+        return [0, 0, 0, 0];
+    const q = l < 0.5 ? l * (1 + sat) : l + sat - l * sat, p = 2 * l - q;
+    const t = (x) => {
+        x = (x + 1) % 1;
+        return x < 1 / 6 ? p + (q - p) * 6 * x : x < 1 / 2 ? q : x < 2 / 3 ? p + (q - p) * (2 / 3 - x) * 6 : p;
+    };
+    return [byte(t(h + 1 / 3) * 255), byte(t(h) * 255), byte(t(h - 1 / 3) * 255), Number.isNaN(a) ? 1 : Math.round(a * 255) / 255];
+}
+export function program(gl, vs, fs) {
+    const make = (type, src) => {
+        const s = gl.createShader(type);
+        gl.shaderSource(s, src);
+        gl.compileShader(s);
+        if (!gl.getShaderParameter(s, gl.COMPILE_STATUS))
+            throw new Error(gl.getShaderInfoLog(s) ?? "shader");
+        return s;
+    };
+    const p = gl.createProgram();
+    gl.attachShader(p, make(gl.VERTEX_SHADER, vs));
+    gl.attachShader(p, make(gl.FRAGMENT_SHADER, fs));
+    gl.linkProgram(p);
+    if (!gl.getProgramParameter(p, gl.LINK_STATUS))
+        throw new Error(gl.getProgramInfoLog(p) ?? "link");
+    return p;
+}
+/** A growable float buffer of fixed-stride instances, uploaded on demand; with no context (a
+ *  renderer kept to its data, ExportSpec decision 21), never uploaded. */
+export class Instances {
+    data;
+    count = 0;
+    stride;
+    buffer;
+    gl;
+    uploaded = -1;
+    version = 0;
+    constructor(gl, stride, capacity = 1024) {
+        this.gl = gl;
+        this.stride = stride;
+        this.data = new Float32Array(stride * capacity);
+        this.buffer = gl ? gl.createBuffer() : null;
+    }
+    clear() {
+        this.count = 0;
+        this.version++;
+    }
+    /** Room for one more instance; returns its offset into `data`. */
+    push() {
+        if ((this.count + 1) * this.stride > this.data.length) {
+            const next = new Float32Array(this.data.length * 2);
+            next.set(this.data);
+            this.data = next;
+        }
+        this.version++;
+        return this.count++ * this.stride;
+    }
+    touch() {
+        this.version++;
+    }
+    upload() {
+        if (this.uploaded === this.version)
+            return;
+        const gl = this.gl;
+        if (!gl)
+            return;
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, this.data.subarray(0, this.count * this.stride), gl.DYNAMIC_DRAW);
+        this.uploaded = this.version;
+    }
+}