topotopo 0.1.0 → 0.3.0

package/dist/viewer/app/api.js

@@ -0,0 +1,64 @@
+// The viewer server's routes (src/viewer/server.ts), one function each. Every call resolves (never throws): failures
+// come back as {ok: false, error} so the page can show them in the status bar.
+
+const fail = (error) => ({ ok: false, error: String(error) });
+const offline = 'the viewer server is not answering';
+const q = (o) => Object.entries(o).map(([k, v]) => `${k}=${encodeURIComponent(v ?? '')}`).join('&');
+
+async function json(url, init) {
+  let res;
+  try { res = await fetch(url, init); } catch { return { status: 0, j: { ok: false, error: offline } }; }
+  const j = await res.json().catch(() => ({ ok: false, error: `${res.status} ${res.statusText}` }));
+  return { status: res.status, j };
+}
+/** A GLB route: {ok, buf} or {ok: false, error}. */
+async function glb(url) {
+  let res;
+  try { res = await fetch(url); } catch { return fail(offline); }
+  if (!res.ok) { const j = await res.json().catch(() => ({})); return fail(j.error ?? `${res.status} ${res.statusText}`); }
+  return { ok: true, buf: await res.arrayBuffer() };
+}
+const post = (body) => ({ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+
+export const api = {
+  /** [{name, output, version, vars, params, nodes: [{name, type, in, error, ms}]}] or null */
+  async graphs() { const { status, j } = await json('/api/graphs'); return status === 200 && Array.isArray(j) ? j : null; },
+  /** the last cook of a graph: {ok, ms, target, errors, warnings} */
+  async report(graph) { const { status, j } = await json('/api/report?' + q({ graph })); return status === 200 ? j : null; },
+  geo: (graph, node) => glb('/api/geo?' + q({ graph, node })),
+  /** {target, summary, ms} or null */
+  async info(graph, node) { const { status, j } = await json('/api/info?' + q({ graph, node })); return status === 200 ? j : null; },
+  /** {ok, ms, errors, vars?} */
+  async vars(graph, vars) { const { status, j } = await json('/api/vars?' + q({ graph }), post({ vars })); return status ? j : { ok: false, ms: 0, errors: [offline] }; },
+  async inputs() { const { status, j } = await json('/api/inputs'); return status === 200 && Array.isArray(j) ? j : null; },
+  /** {dir, where} or null */
+  async inputsDir() { const { status, j } = await json('/api/inputs_dir'); return status === 200 ? j : null; },
+  /** POST /api/inputs: {status, j} as the server answers (409 when the file exists and overwrite is false) */
+  async upload(file, overwrite) {
+    try {
+      const res = await fetch('/api/inputs?' + q({ name: file.name, overwrite: overwrite ? 1 : 0 }), { method: 'POST', body: file });
+      return { status: res.status, j: await res.json().catch(() => ({})) };
+    } catch (e) { return { status: 0, j: { error: `upload failed: ${e?.message ?? e}` } }; }
+  },
+  input: (path) => glb('/api/input?' + q({ path })),
+  /** {ok, summary} or {ok: false, error} */
+  async inputInfo(path) {
+    const { status, j } = await json('/api/input_info?' + q({ path }));
+    return status === 200 ? { ok: true, summary: String(j.summary ?? '') } : fail(j.error ?? `${status}`);
+  },
+  /** {markers, error?} */
+  async markers() { const { status, j } = await json('/api/markers'); return status === 200 && Array.isArray(j.markers) ? j : { markers: null, error: j.error ?? offline }; },
+  /** {ok, count, points, prims} or {ok: false, error} */
+  async saveMarkers(body) {
+    const { status, j } = await json('/api/markers', { method: 'POST', headers: { 'content-type': 'application/json' }, body });
+    return status === 200 && j.ok ? j : fail(j.error ?? `${status}`);
+  },
+  /** The event stream: on({open, error, message}); returns the EventSource. */
+  events(on) {
+    const es = new EventSource('/api/events');
+    es.onopen = () => on.open?.();
+    es.onerror = () => on.error?.();
+    es.onmessage = (m) => { let ev; try { ev = JSON.parse(m.data); } catch { return; } on.message?.(ev); };
+    return es;
+  },
+};

package/dist/viewer/app/camera.js

@@ -0,0 +1,250 @@
+// Cameras and views (docs/design/viewer.md section 3): our own controller, no OrbitControls. Tumble around a pivot,
+// track, dolly towards a point, no inertia: the camera moves only while the person drags, scrolls or frames. Seven
+// named cameras (persp and the axis views); one view, or four in a 2×2 quad, each showing one of them with its own
+// shading. Orthographic cameras cannot tumble. Near and far planes follow the scene size (the renderer keeps a
+// logarithmic depth buffer), so a 1 km terrain and a 2 cm bolt both draw.
+import * as THREE from 'three';
+
+export const CAMERA_NAMES = ['persp', 'top', 'front', 'right', 'bottom', 'back', 'left'];
+/** Axis views as the render tool's (src/render/raster.ts ORTHO): view direction f and up u. */
+export const AXIS_VIEWS = {
+  top: { f: [0, -1, 0], u: [0, 0, -1] }, bottom: { f: [0, 1, 0], u: [0, 0, 1] },
+  front: { f: [0, 0, -1], u: [0, 1, 0] }, back: { f: [0, 0, 1], u: [0, 1, 0] },
+  right: { f: [-1, 0, 0], u: [0, 1, 0] }, left: { f: [1, 0, 0], u: [0, 1, 0] },
+};
+/** The axis view that looks from the + or − side of an axis (the axis gizmo's ends). */
+export const VIEW_OF_AXIS = { '+x': 'right', '-x': 'left', '+y': 'top', '-y': 'bottom', '+z': 'front', '-z': 'back' };
+export const SHADINGS = [['wire', 'wire'], ['shaded', 'shaded'], ['shadedWire', 'shaded + wire']];
+/** The render tool's persp: 32° across the narrower side, from azimuth 35°, elevation 25°. */
+const FOV = 32, AZ = 35, EL = 25;
+const TUMBLE = 0.3 * Math.PI / 180; // radians per pixel
+const MIN_D = 1e-4, MAX_D = 1e7;
+
+const quatOf = (f, u) => {
+  const z = new THREE.Vector3(...f).negate(), y = new THREE.Vector3(...u), x = new THREE.Vector3().crossVectors(y, z);
+  return new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().makeBasis(x, y, z));
+};
+const perspQuat = () => {
+  const az = AZ * Math.PI / 180, el = EL * Math.PI / 180;
+  const back = new THREE.Vector3(Math.cos(el) * Math.sin(az), Math.sin(el), Math.cos(el) * Math.cos(az));
+  const m = new THREE.Matrix4().lookAt(back, new THREE.Vector3(), new THREE.Vector3(0, 1, 0));
+  return new THREE.Quaternion().setFromRotationMatrix(m);
+};
+
+/** One named camera: where it looks (target), how (orientation), how far (persp distance / ortho half height). */
+class Cam {
+  constructor(name) {
+    this.name = name;
+    this.ortho = name !== 'persp';
+    this.target = new THREE.Vector3();
+    this.pivot = new THREE.Vector3();
+    this.quat = name === 'persp' ? perspQuat() : quatOf(AXIS_VIEWS[name].f, AXIS_VIEWS[name].u);
+    this.dist = 12;
+    this.halfH = 6;
+  }
+  get back() { return new THREE.Vector3(0, 0, 1).applyQuaternion(this.quat); }
+  get right() { return new THREE.Vector3(1, 0, 0).applyQuaternion(this.quat); }
+  get up() { return new THREE.Vector3(0, 1, 0).applyQuaternion(this.quat); }
+  get eye() { return this.target.clone().addScaledVector(this.back, this.dist); }
+  toJSON() { return { ortho: this.ortho, target: this.target.toArray(), pivot: this.pivot.toArray(), quat: this.quat.toArray(), dist: this.dist, halfH: this.halfH }; }
+  load(j) {
+    if (!j) return;
+    const ok = (a, n) => Array.isArray(a) && a.length === n && a.every(Number.isFinite);
+    if (typeof j.ortho === 'boolean') this.ortho = j.ortho;
+    if (ok(j.target, 3)) this.target.fromArray(j.target);
+    this.pivot.copy(this.target);
+    if (ok(j.pivot, 3)) this.pivot.fromArray(j.pivot);
+    if (ok(j.quat, 4)) this.quat.fromArray(j.quat).normalize();
+    if (j.dist > 0) this.dist = Math.min(MAX_D, Math.max(MIN_D, j.dist));
+    if (j.halfH > 0) this.halfH = Math.min(MAX_D, Math.max(MIN_D, j.halfH));
+  }
+}
+
+/** Vertical field of view (degrees) giving FOV across the narrower side. */
+const vfov = (aspect) => (aspect >= 1 ? FOV : 2 * Math.atan(Math.tan((FOV * Math.PI) / 360) / aspect) * 180 / Math.PI);
+
+/**
+ * The views: four slots (quad: top, persp / front, right as in Maya and Houdini), one shown alone in single mode.
+ * `scene()` gives {center: Vector3, radius} of everything drawn, for the near and far planes.
+ */
+export function createViews(scene) {
+  const cams = new Map(CAMERA_NAMES.map((n) => [n, new Cam(n)]));
+  const slots = ['top', 'persp', 'front', 'right'].map((cam) => ({ cam, shading: 'shaded', rect: { x: 0, y: 0, w: 1, h: 1 }, p: null, o: null }));
+  for (const s of slots) { s.p = new THREE.PerspectiveCamera(FOV, 1, 0.01, 1000); s.o = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1000); }
+  const v = {
+    cams, slots, quad: false, active: 1,
+    /** true once a camera was placed (framed, restored or moved by the person) */
+    placed: false,
+    /** the slots on screen, with their rects (CSS px in the viewport) */
+    visible() { return v.quad ? slots : [slots[v.active]]; },
+    layout(W, H) {
+      if (!v.quad) { slots[v.active].rect = { x: 0, y: 0, w: W, h: H }; return; }
+      const w0 = Math.floor(W / 2), h0 = Math.floor(H / 2);
+      slots[0].rect = { x: 0, y: 0, w: w0, h: h0 };
+      slots[1].rect = { x: w0, y: 0, w: W - w0, h: h0 };
+      slots[2].rect = { x: 0, y: h0, w: w0, h: H - h0 };
+      slots[3].rect = { x: w0, y: h0, w: W - w0, h: H - h0 };
+    },
+    /** The slot index under a viewport point, or -1. */
+    slotAt(x, y) {
+      for (const s of v.visible()) { const r = s.rect; if (x >= r.x && x < r.x + r.w && y >= r.y && y < r.y + r.h) return slots.indexOf(s); }
+      return -1;
+    },
+    cam: (i) => cams.get(slots[i].cam),
+    /** The three.js camera of slot i, set up for its rect and the scene's size. */
+    camera(i) {
+      const s = slots[i], c = cams.get(s.cam), r = s.rect, aspect = Math.max(1e-3, r.w / Math.max(1, r.h));
+      const { center, radius } = scene();
+      const R = Math.max(radius, 1e-3);
+      if (!c.ortho) {
+        const p = s.p, eye = c.eye;
+        p.fov = vfov(aspect); p.aspect = aspect;
+        const away = eye.distanceTo(center);
+        p.near = Math.max(1e-6, Math.min(c.dist, R) * 1e-4);
+        p.far = Math.max(c.dist * 200, (away + R) * 4);
+        p.position.copy(eye); p.quaternion.copy(c.quat);
+        p.updateProjectionMatrix(); p.updateMatrixWorld();
+        return p;
+      }
+      const o = s.o, D = c.target.distanceTo(center) + R * 2 + c.halfH * 4;
+      o.left = -c.halfH * aspect; o.right = c.halfH * aspect; o.top = c.halfH; o.bottom = -c.halfH;
+      o.near = 0; o.far = D * 2;
+      o.position.copy(c.target).addScaledVector(c.back, D); o.quaternion.copy(c.quat);
+      o.updateProjectionMatrix(); o.updateMatrixWorld();
+      return o;
+    },
+    /** Metres per pixel at the slot's target (the grid step and constant-size marks use it). */
+    worldPerPixel(i) {
+      const s = slots[i], c = cams.get(s.cam), h = Math.max(1, s.rect.h);
+      if (c.ortho) return (2 * c.halfH) / h;
+      return (2 * c.dist * Math.tan((vfov(s.rect.w / h) * Math.PI) / 360)) / h;
+    },
+    /** Normalised device coordinates of a viewport point (px in the viewport, as every pointer position here) in slot i. */
+    ndc(i, x, y) { const r = slots[i].rect; return new THREE.Vector2(((x - r.x) / r.w) * 2 - 1, -((y - r.y) / r.h) * 2 + 1); },
+    ray(i, x, y) { const rc = new THREE.Raycaster(); rc.setFromCamera(v.ndc(i, x, y), v.camera(i)); return rc; },
+    /** A world point in viewport pixels as slot i shows it, or null behind the camera. */
+    project(i, p, cam = v.camera(i)) {
+      const q = new THREE.Vector3(p.x, p.y, p.z).project(cam), r = slots[i].rect;
+      if (q.z > 1 || q.z < -1) return null;
+      return { x: r.x + ((q.x + 1) / 2) * r.w, y: r.y + ((1 - q.y) / 2) * r.h };
+    },
+    /** The point under a viewport point on the plane through the slot's target facing the camera. */
+    targetPlanePoint(i, x, y, at) {
+      const c = v.cam(i), rc = v.ray(i, x, y), n = c.back;
+      const p = new THREE.Vector3();
+      return rc.ray.intersectPlane(new THREE.Plane().setFromNormalAndCoplanarPoint(n, at ?? c.target), p) ? p : (at ?? c.target).clone();
+    },
+
+    // ---------------------------------------------------------------- navigation
+    /** Tumble slot i's camera by a mouse move (px) around `pivot`; nothing in orthographic cameras. */
+    tumble(i, dx, dy, pivot) {
+      const c = v.cam(i);
+      if (c.ortho) return false;
+      const yaw = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), -dx * TUMBLE);
+      const pitch = new THREE.Quaternion().setFromAxisAngle(c.right, -dy * TUMBLE);
+      let q = yaw.clone().multiply(pitch);
+      // stay upright: no rolling over the top
+      if (new THREE.Vector3(0, 1, 0).applyQuaternion(q.clone().multiply(c.quat)).y < 0) q = yaw;
+      const P = (pivot ?? c.target).clone();
+      c.target.sub(P).applyQuaternion(q).add(P);
+      c.quat.premultiply(q).normalize();
+      v.placed = true;
+      return true;
+    },
+    /** Track: the point at the target's depth follows the mouse. */
+    track(i, dx, dy, at) {
+      const c = v.cam(i);
+      const depth = at && !c.ortho ? Math.max(MIN_D, c.eye.clone().sub(at).dot(c.back)) : c.dist;
+      const k = v.worldPerPixel(i) * (c.ortho ? 1 : depth / c.dist);
+      const delta = c.right.multiplyScalar(-dx * k).addScaledVector(c.up, dy * k);
+      c.target.add(delta); c.pivot.add(delta);
+      v.placed = true;
+    },
+    /** Pick a navigation pivot without changing the camera's eye, aim or distance. */
+    anchor(i, hit) {
+      const c = v.cam(i);
+      if (hit && hit.toArray().every(Number.isFinite) && c.eye.clone().sub(hit).dot(c.back) > MIN_D) c.pivot.copy(hit);
+      return c.pivot.clone();
+    },
+    zoomAt(i, factor, at) {
+      const c = v.cam(i), before = c.ortho ? c.halfH : c.dist;
+      v.dolly(i, factor, at);
+      const scale = (c.ortho ? c.halfH : c.dist) / before;
+      c.pivot.sub(at).multiplyScalar(scale).add(at);
+    },
+    /** Dolly by factor s (< 1 closer) towards `at` (a world point on the target plane; default the target). */
+    dolly(i, s, at) {
+      const c = v.cam(i);
+      const cur = c.ortho ? c.halfH : c.dist;
+      const next = Math.min(MAX_D, Math.max(MIN_D, cur * s));
+      s = next / cur;
+      if (at) c.target.sub(at).multiplyScalar(s).add(at);
+      if (c.ortho) c.halfH = next; else c.dist = next;
+      v.placed = true;
+    },
+    /** Frame a world box in slot i. */
+    frame(i, box) {
+      if (!box || box.isEmpty()) return;
+      const s = slots[i], c = cams.get(s.cam), r = s.rect, aspect = Math.max(1e-3, r.w / Math.max(1, r.h));
+      const center = box.getCenter(new THREE.Vector3()), size = box.getSize(new THREE.Vector3());
+      const radius = Math.max(size.length() / 2, 1e-3);
+      c.target.copy(center);
+      c.pivot.copy(center);
+      const half = (vfov(aspect) * Math.PI) / 360, halfW = Math.atan(Math.tan(half) * aspect);
+      c.dist = Math.min(MAX_D, Math.max(MIN_D, (radius / Math.sin(Math.min(half, halfW))) * 1.05));
+      // ortho: the box's extent across the view
+      const rt = c.right, up = c.up;
+      let ex = 0, ey = 0;
+      for (let k = 0; k < 8; k++) {
+        const p = new THREE.Vector3(k & 1 ? box.max.x : box.min.x, k & 2 ? box.max.y : box.min.y, k & 4 ? box.max.z : box.min.z).sub(center);
+        ex = Math.max(ex, Math.abs(p.dot(rt))); ey = Math.max(ey, Math.abs(p.dot(up)));
+      }
+      c.halfH = Math.min(MAX_D, Math.max(MIN_D, Math.max(ey, ex / aspect, 1e-3) * 1.1));
+      v.placed = true;
+    },
+    /** Show camera `name` in slot i. */
+    setCam(i, name) { if (cams.has(name)) slots[i].cam = name; },
+    toggleOrtho(i) {
+      const c = v.cam(i), aspect = slots[i].rect.w / Math.max(1, slots[i].rect.h), t = Math.tan((vfov(aspect) * Math.PI) / 360);
+      if (c.ortho) c.dist = Math.min(MAX_D, c.halfH / t); else c.halfH = Math.max(MIN_D, c.dist * t);
+      c.ortho = !c.ortho;
+      v.placed = true;
+    },
+    /** The axis gizmo's click: persp turns to look along the axis; an axis view becomes that axis view. */
+    lookAlong(i, axis) {
+      const name = VIEW_OF_AXIS[axis];
+      if (!name) return;
+      const c = v.cam(i);
+      if (c.name === 'persp') { c.quat.copy(quatOf(AXIS_VIEWS[name].f, AXIS_VIEWS[name].u)); v.placed = true; }
+      else {
+        // the new view looks at the same place at the same scale
+        const n = cams.get(name);
+        n.target.copy(c.target); n.halfH = c.ortho ? c.halfH : c.dist * 0.3;
+        n.pivot.copy(c.pivot);
+        slots[i].cam = name;
+      }
+    },
+    toJSON() {
+      return { cams: Object.fromEntries([...cams].map(([n, c]) => [n, c.toJSON()])), slots: slots.map((s) => ({ cam: s.cam, shading: s.shading })), quad: v.quad, active: v.active };
+    },
+    load(j) {
+      if (!j || typeof j !== 'object') return false;
+      for (const [n, c] of cams) c.load(j.cams?.[n]);
+      (j.slots ?? []).slice(0, 4).forEach((s, k) => {
+        if (cams.has(s?.cam)) slots[k].cam = s.cam;
+        if (SHADINGS.some(([id]) => id === s?.shading)) slots[k].shading = s.shading;
+      });
+      v.quad = !!j.quad;
+      if (Number.isInteger(j.active) && j.active >= 0 && j.active < 4) v.active = j.active;
+      v.placed = true;
+      return true;
+    },
+  };
+  return v;
+}
+
+/** The view name a slot prints: the camera's name, "(ortho)" / "(persp)" when it is not its own projection. */
+export function viewLabel(c) {
+  if (c.name === 'persp') return c.ortho ? 'persp (ortho)' : 'persp';
+  return c.ortho ? c.name : `${c.name} (persp)`;
+}

package/dist/viewer/app/export-popover.js

@@ -0,0 +1,68 @@
+// The export target popover: a format and a file name inside exports/, opened by an output's Export button when it
+// has no target yet, or to change it. Submitting stores the target in the graph and exports.
+const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text !== undefined) e.textContent = text; return e; };
+
+/** A file name stem like the server's (io/targets.ts fileStem). */
+export const fileStem = (s) => String(s).replace(/[^A-Za-z0-9_.-]+/g, '_').replace(/^\.+|[. ]+$/g, '') || 'output';
+
+/** The path a format writes to by default: <stem><extension>, a folder for formats without one. */
+export function defaultPath(stem, format, formats) {
+  return fileStem(stem) + (formats.find((f) => f.format === format)?.extension ?? '');
+}
+
+/** The path with its extension swapped from one format's to another's (a custom name keeps its stem). */
+export function swapExtension(p, from, to, formats) {
+  const ext = (f) => formats.find((x) => x.format === f)?.extension ?? '';
+  const a = ext(from), b = ext(to);
+  const stem = a && p.toLowerCase().endsWith(a.toLowerCase()) ? p.slice(0, -a.length) : p;
+  return stem + b;
+}
+
+/**
+ * Open the popover under `anchor`. item: an output entry (label, kind, graph, output, target); formats: [{format, label,
+ * extension}] from /api/outputs; directory: the exports folder. Resolves to {format, path} or null (cancelled).
+ */
+export function exportPopover({ anchor, item, formats, directory }) {
+  document.querySelector('.export-popover')?.dispatchEvent(new Event('cancel'));
+  return new Promise((resolve) => {
+    const stem = item.output ?? item.graph ?? 'output';
+    const startFormat = item.target?.format ?? (item.kind === 'image' ? 'textures' : 'glb');
+    const box = el('form', 'export-popover');
+    box.setAttribute('role', 'dialog'); box.setAttribute('aria-label', `Export ${item.label}`);
+    const title = el('div', 'export-title', item.target ? `Export target of ${item.label}` : `Export ${item.label}`);
+    const format = el('select'); format.setAttribute('aria-label', 'Format');
+    for (const f of formats) format.append(new Option(f.label, f.format));
+    format.value = startFormat;
+    const file = el('input'); file.type = 'text'; file.spellcheck = false; file.setAttribute('aria-label', 'File in exports/');
+    file.value = item.target?.path ?? defaultPath(stem, startFormat, formats);
+    const where = el('div', 'export-where dim');
+    const error = el('div', 'export-error err');
+    const cancel = el('button', '', 'Cancel'), go = el('button', 'primary', 'Export');
+    cancel.type = 'button'; go.type = 'submit';
+    const field = (label, input) => { const l = el('label', 'export-field'); l.append(el('span', 'dim', label), input); return l; };
+    const actions = el('div', 'export-actions'); actions.append(cancel, go);
+    box.append(title, field('Format', format), field('File', file), where, error, actions);
+    let previous = format.value;
+    const sync = () => { where.textContent = `${directory}/${file.value.trim() || '…'}`; error.textContent = ''; };
+    format.onchange = () => { file.value = swapExtension(file.value.trim(), previous, format.value, formats); previous = format.value; sync(); };
+    file.oninput = sync;
+    const close = (value) => { box.remove(); removeEventListener('pointerdown', outside, true); anchor?.focus?.(); resolve(value); };
+    const outside = (e) => { if (!box.contains(e.target)) close(null); };
+    box.addEventListener('cancel', () => close(null));
+    cancel.onclick = () => close(null);
+    box.onkeydown = (e) => { if (e.key === 'Escape') { e.preventDefault(); close(null); } };
+    box.onsubmit = (e) => {
+      e.preventDefault();
+      const p = file.value.trim().replace(/\\/g, '/');
+      if (!p || p.startsWith('/') || /^[A-Za-z]:/.test(p) || p.split('/').some((s) => !s || s === '.' || s === '..')) { error.textContent = 'a path inside exports/, without ".." or a drive'; file.focus(); return; }
+      close({ format: format.value, path: p });
+    };
+    sync();
+    document.body.append(box);
+    const r = anchor.getBoundingClientRect();
+    box.style.left = Math.max(6, Math.min(r.left, innerWidth - box.offsetWidth - 6)) + 'px';
+    box.style.top = (r.bottom + 4 + box.offsetHeight < innerHeight ? r.bottom + 4 : Math.max(6, r.top - box.offsetHeight - 4)) + 'px';
+    addEventListener('pointerdown', outside, true);
+    format.focus();
+  });
+}

package/dist/viewer/app/grid.js

@@ -0,0 +1,217 @@
+// The adaptive metre grid, the world axes, the axis gizmo and each view's readouts (docs/design/viewer.md section 4).
+// The grid lies on y = 0 under persp and the top / bottom views, and on each side view's own plane (front: XY,
+// right: ZY), as Maya and Houdini draw them; minor lines every `step`, major every 10 steps, the axes in the
+// standard colours. One plane is set up again before each view renders.
+import * as THREE from 'three';
+import { AXIS_VIEWS, viewLabel } from './camera.js';
+import { gridStep, MAJOR_EVERY, fmtStep, fmtPoint } from './units.js';
+
+export const AXIS_COLORS = { x: '#d9534f', y: '#6abf4b', z: '#4a86d9' };
+const lin = (hex) => new THREE.Color(hex);
+
+const vertex = /* glsl */`
+  #include <common>
+  #include <logdepthbuf_pars_vertex>
+  varying vec3 vWorld;
+  void main() {
+    vec4 w = modelMatrix * vec4(position, 1.0);
+    vWorld = w.xyz;
+    gl_Position = projectionMatrix * viewMatrix * w;
+    #include <logdepthbuf_vertex>
+  }`;
+const fragment = /* glsl */`
+  #include <common>
+  #include <logdepthbuf_pars_fragment>
+  uniform float uStep;
+  uniform int uPlane;          // 0: xz, 1: xy, 2: zy
+  uniform vec3 uMinor, uMajor, uAxisU, uAxisV;
+  uniform vec3 uCenter;
+  uniform float uFade;         // fade-out radius around uCenter (0: none)
+  varying vec3 vWorld;
+  float lineOf(vec2 c) {
+    vec2 g = abs(fract(c - 0.5) - 0.5) / max(fwidth(c), vec2(1e-6));
+    return 1.0 - min(min(g.x, g.y), 1.0);
+  }
+  void main() {
+    #include <logdepthbuf_fragment>
+    vec2 p = uPlane == 0 ? vWorld.xz : (uPlane == 1 ? vWorld.xy : vWorld.zy);
+    vec2 c = p / uStep;
+    vec2 fw = fwidth(c);
+    // minor cells fade out from 7 px down to 3 px, majors likewise
+    float dens = max(fw.x, fw.y);
+    float minor = lineOf(c) * (1.0 - smoothstep(0.15, 0.35, dens));
+    float major = lineOf(c / ${MAJOR_EVERY.toFixed(1)}) * (1.0 - smoothstep(0.15, 0.35, dens / ${MAJOR_EVERY.toFixed(1)}));
+    vec2 pw = max(fwidth(p), vec2(1e-9));
+    float onU = 1.0 - min(abs(p.y) / pw.y / 1.2, 1.0); // the U axis runs where p.y = 0
+    float onV = 1.0 - min(abs(p.x) / pw.x / 1.2, 1.0);
+    vec3 col = uMinor; float a = minor * 0.55;
+    if (major * 0.9 > a) { col = uMajor; a = major * 0.9; }
+    if (onU > 0.0 && onU >= a) { col = uAxisU; a = max(a, onU); }
+    if (onV > 0.0 && onV >= a) { col = uAxisV; a = max(a, onV); }
+    if (uFade > 0.0) a *= 1.0 - smoothstep(uFade * 0.55, uFade, length(vWorld - uCenter));
+    if (a < 0.004) discard;
+    gl_FragColor = vec4(col, a);
+    #include <colorspace_fragment>
+  }`;
+
+/** The grid plane and the vertical world axis; `prepare(...)` sets them up for one view before it renders. */
+export function createGrid(scene) {
+  const mat = new THREE.ShaderMaterial({
+    vertexShader: vertex, fragmentShader: fragment, transparent: true, depthWrite: false, side: THREE.DoubleSide,
+    uniforms: {
+      uStep: { value: 1 }, uPlane: { value: 0 }, uMinor: { value: lin('#3d4046') }, uMajor: { value: lin('#575b62') },
+      uAxisU: { value: lin(AXIS_COLORS.x) }, uAxisV: { value: lin(AXIS_COLORS.z) }, uCenter: { value: new THREE.Vector3() }, uFade: { value: 0 },
+    },
+  });
+  const plane = new THREE.Mesh(new THREE.PlaneGeometry(2, 2, 8, 8), mat);
+  plane.renderOrder = -10;
+  plane.frustumCulled = false;
+  plane.name = 'grid';
+  scene.add(plane);
+  // the axis that stands out of the grid plane (Y under persp), through the origin
+  const yAxis = new THREE.Line(new THREE.BufferGeometry().setFromPoints([new THREE.Vector3(0, -1, 0), new THREE.Vector3(0, 1, 0)]),
+    new THREE.LineBasicMaterial({ color: AXIS_COLORS.y, transparent: true, opacity: 0.8 }));
+  yAxis.frustumCulled = false;
+  yAxis.renderOrder = -9;
+  yAxis.name = 'y axis';
+  scene.add(yAxis);
+
+  return {
+    plane,
+    /**
+     * Set up for one view: cam (a Cam of camera.js) and its metres per pixel at the target. Returns the grid step.
+     */
+    prepare(cam, wpp) {
+      const step = gridStep(wpp);
+      const kind = cam.name === 'persp' ? 'persp' : cam.name;
+      const f = kind === 'persp' ? null : AXIS_VIEWS[kind].f;
+      // the plane: xz for persp / top / bottom, xy for front / back, zy for right / left
+      const planeId = !f || f[1] !== 0 ? 0 : f[2] !== 0 ? 1 : 2;
+      const u = mat.uniforms;
+      u.uStep.value = step;
+      u.uPlane.value = planeId;
+      u.uAxisU.value.set(planeId === 2 ? AXIS_COLORS.z : AXIS_COLORS.x);
+      u.uAxisV.value.set(planeId === 0 ? AXIS_COLORS.z : AXIS_COLORS.y);
+      const t = cam.target.clone();
+      // snapped to major cells, so the lines never swim
+      const big = step * MAJOR_EVERY;
+      const snap = (x) => Math.round(x / big) * big;
+      let half;
+      // ortho: the whole view (aspects up to 4); persp: far enough to fade out before the horizon
+      if (cam.ortho) half = Math.max(cam.halfH * 4, big * 2);
+      else half = Math.max(cam.dist * 40, big * 4);
+      half = Math.ceil(half / big) * big;
+      plane.scale.set(half, half, 1);
+      plane.rotation.set(0, 0, 0);
+      if (planeId === 0) { plane.rotation.x = -Math.PI / 2; plane.position.set(snap(t.x), 0, snap(t.z)); }
+      else if (planeId === 1) plane.position.set(snap(t.x), snap(t.y), 0);
+      else { plane.rotation.y = Math.PI / 2; plane.position.set(0, snap(t.y), snap(t.z)); }
+      plane.updateMatrixWorld();
+      u.uCenter.value.copy(cam.ortho ? plane.position : t.clone().projectOnPlane(new THREE.Vector3(...(planeId === 0 ? [0, 1, 0] : planeId === 1 ? [0, 0, 1] : [1, 0, 0]))));
+      u.uFade.value = cam.ortho ? 0 : half;
+      yAxis.visible = !cam.ortho && planeId === 0;
+      if (yAxis.visible) {
+        // a line whose end lies behind the camera draws nothing under a logarithmic depth buffer: cut it in front
+        const eye = cam.eye, fwd = cam.back.negate(), ahead = Math.max(1e-4, cam.dist * 1e-3);
+        const a = new THREE.Vector3(0, -half, 0), b = new THREE.Vector3(0, half, 0);
+        const da = a.clone().sub(eye).dot(fwd), db = b.clone().sub(eye).dot(fwd);
+        if (da < ahead && db < ahead) yAxis.visible = false;
+        else {
+          if (da < ahead) a.lerp(b, (ahead - da) / (db - da));
+          else if (db < ahead) b.lerp(a, (ahead - db) / (da - db));
+          const pos = yAxis.geometry.attributes.position;
+          pos.setXYZ(0, a.x, a.y, a.z); pos.setXYZ(1, b.x, b.y, b.z); pos.needsUpdate = true;
+        }
+      }
+      return step;
+    },
+  };
+}
+
+// ------------------------------------------------------------------------------------ view overlays (DOM)
+const SVG = 'http://www.w3.org/2000/svg';
+const svgEl = (tag, attrs = {}) => { const e = document.createElementNS(SVG, tag); for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v); return e; };
+
+/**
+ * Per view slot: its frame, the name, the readouts (grid step, cursor position in orthographic views, the
+ * selection's size), the axis gizmo (clicking an end calls `onAxis(slot, '+x' …)`), and layers for marks and labels.
+ */
+export function createOverlays(host, onAxis) {
+  return [0, 1, 2, 3].map((slot) => {
+    const box = document.createElement('div');
+    box.className = 'vw';
+    const name = document.createElement('div');
+    name.className = 'vname';
+    const info = document.createElement('div');
+    info.className = 'vinfo';
+    const marks = svgEl('svg', { class: 'marks' });
+    const labels = document.createElement('div');
+    labels.className = 'labels';
+    const giz = svgEl('svg', { class: 'gizmo', viewBox: '-32 -32 64 64' });
+    box.append(marks, labels, name, info, giz);
+    host.append(box);
+    const ends = {};
+    for (const a of ['x', 'y', 'z']) {
+      for (const sgn of ['+', '-']) {
+        const g = svgEl('g', { class: 'end' });
+        const line = sgn === '+' ? svgEl('line', { x1: 0, y1: 0, stroke: AXIS_COLORS[a], 'stroke-width': 2 }) : null;
+        const dot = svgEl('circle', { r: sgn === '+' ? 7 : 4.5, fill: sgn === '+' ? AXIS_COLORS[a] : '#2b2d31', stroke: AXIS_COLORS[a], 'stroke-width': 1.5 });
+        const txt = sgn === '+' ? svgEl('text') : null;
+        if (txt) txt.textContent = a.toUpperCase();
+        const t = svgEl('title');
+        t.textContent = `look along ${sgn === '+' ? '-' : '+'}${a.toUpperCase()} (from ${sgn}${a.toUpperCase()})`;
+        g.append(t, ...[line, dot, txt].filter(Boolean));
+        g.addEventListener('pointerdown', (e) => { e.stopPropagation(); e.preventDefault(); onAxis(slot, `${sgn}${a}`); });
+        ends[sgn + a] = { g, line, dot, txt };
+      }
+    }
+    return {
+      box, name, info, marks, labels, giz, ends,
+      /** Place and fill for this frame. */
+      update({ rect, visible, quad, active, cam, camera, step, cursor, selSize }) {
+        box.hidden = !visible;
+        if (!visible) return;
+        Object.assign(box.style, { left: `${rect.x}px`, top: `${rect.y}px`, width: `${rect.w}px`, height: `${rect.h}px` });
+        box.classList.toggle('quad', quad);
+        box.classList.toggle('active', active);
+        const label = viewLabel(cam);
+        if (name.dataset.t !== label) { name.dataset.t = label; name.textContent = label; }
+        const lines = [`grid ${fmtStep(step)}`];
+        if (cursor && cam.ortho) lines.push(cursor);
+        const text = lines.join('\n') + (selSize ? '\n' : '');
+        const sel = selSize ? `sel ${selSize}` : '';
+        if (info.dataset.t !== text + sel) {
+          info.dataset.t = text + sel;
+          info.textContent = text;
+          if (sel) { const s = document.createElement('span'); s.className = 'selsize'; s.textContent = sel; info.append(s); }
+        }
+        // the gizmo: world axes as the camera sees them, the far ends drawn first
+        const m = new THREE.Matrix4().extractRotation(camera.matrixWorldInverse);
+        const order = [];
+        for (const a of ['x', 'y', 'z']) for (const sgn of [1, -1]) {
+          const v = new THREE.Vector3(a === 'x' ? sgn : 0, a === 'y' ? sgn : 0, a === 'z' ? sgn : 0).applyMatrix4(m);
+          order.push({ k: (sgn > 0 ? '+' : '-') + a, x: v.x * 22, y: -v.y * 22, z: v.z });
+        }
+        order.sort((p, q) => p.z - q.z);
+        for (const o of order) {
+          const e = ends[o.k];
+          if (e.line) { e.line.setAttribute('x2', o.x.toFixed(1)); e.line.setAttribute('y2', o.y.toFixed(1)); }
+          e.dot.setAttribute('cx', o.x.toFixed(1)); e.dot.setAttribute('cy', o.y.toFixed(1));
+          if (e.txt) { e.txt.setAttribute('x', o.x.toFixed(1)); e.txt.setAttribute('y', o.y.toFixed(1)); }
+          giz.append(e.g);
+        }
+      },
+    };
+  });
+}
+
+/** The cursor's world position on a view's construction plane, printed for orthographic views. */
+export function cursorText(cam, p, step) {
+  if (!p) return '';
+  const kind = cam.name === 'persp' ? 'top' : cam.name;
+  const f = AXIS_VIEWS[kind].f;
+  // the coordinates in the view's plane, the one along the view as the plane's
+  const axes = f[1] !== 0 ? ['x', 'z'] : f[2] !== 0 ? ['x', 'y'] : ['z', 'y'];
+  const v = { x: p.x, y: p.y, z: p.z };
+  return axes.map((a) => `${a} ${fmtPoint([v[a]], step).slice(1, -1)}`).join('  ');
+}